Scripting > UNICOM Intelligence Function Library > List functions > FindItem
 
FindItem
This function returns a specified item from a list, or NULL if the item isn't found.
Syntax
FindItem(List, Key)
Parameters
List
Type: None
Array, collection or Categorical value to operate on.
Key
Type: None
Index, name, or value of the item to be found.
(return)
Type: None
A copy of the requested item if found in List, or NULL if the item is not found.
Remarks
This function can be used to look up an item in a list, without generating an error if the item doesn't exist. If List or Key are NULL, the return value is NULL.
The way in which Key is used to locate an item depends on the type of the list, as follows:
If List is a Collection
Key is passed to the list's "Evaluate method", that is, the property or method that is given a COM Dispatch identifier of -5. If the list has no Evaluate method, Key is passed to the Item property of the list. If the list has neither an Evaluate method, nor a property or method called "Item" (in English only), or if accessing the Evaluate method or the Item property generates an error, the return value is NULL. Otherwise, the return value is the value returned by the Evaluate method or the Item property, which may be NULL if the item isn't found.
If List is an Array or Categorical Value, and Key is of type Long
Key is taken as the positional index of an item in the list, starting at 0 for the first item. If Key is greater than or equal to zero and less than the number of items in List, the return value is the item at that position. Otherwise, the return value is NULL.
For example, if List is a Categorical value that contains three or more categories and Key is 2 (Long), the return value is the third category in the list.
If List is an Array or Categorical Value, and Key is not of type Long
Key is compared with each list item in turn until a match is found. The way that Key is compared with each item depends on the type of the item:
▪For a string item, Key is converted to a string and compared with the item.
▪For an item that is an object, Key is converted to a string and compared with the value of the object's “Name property”, that is, the property that is given a COM Dispatch identifier of -800. If the object has no “Name property”, the key is compared with the value of the object's default property, which is converted to a string if necessary. If the object has no Name or default properties, or if accessing the Name or default properties generates an error, the item is considered not to be a match for Key.
▪For any other type of item, Key is compared with the item using the normal conversion and comparison rules for variant types.
In all string comparisons, differences between upper and lower case are ignored. If a matching item is found, the return value is the matching item. Otherwise the return value is NULL.
For example, if List is a Categorical value that contains a category with a value of 2 and Key is “2” (Text) or 2.0 (Double), the return value is 2 (Long).
Examples
Function call
List
Key
Result
Notes
FindItem(List, Key)
{8,5,7,1,3,4,9}
4
3
The item with a positional index of 4 (that is, the fifth item) in the categorical value is returned.
FindItem(List, Key)
{8,5,7,1,3,4,9}
10
NULL
There is no item with a positional index of 10, so NULL is returned.
FindItem(List, Key)
{8,5,7,1,3,4,9}
"4.0"
4
To compare with the Long values in the categorical value, Key is converted from a Text to a Long value, and the matching item is returned.
FindItem(List, Key)
{8,5,7,1,3,4,9}
4.0
4
To compare with the Long values in the categorical value, Key is converted from a Double to a Long value, and the matching item is returned.
FindItem(List, Key)
split("The quick brown fox")
1
"quick"
The item with a positional index of 1 (that is, the second item) in the array is returned.
FindItem(List, Key)
split("The quick brown fox")
"THE"
"The"
The matching Text item in the array is returned. String comparisons are always case insensitive.
FindItem(List, Key)
split("1 2 3 4 5")
4
"5"
Key is a Long value, so the item with a positional index of 4 in the array is returned.
FindItem(List, Key)
split("1 2 3 4 5")
"4"
"4"
Key is a Text value, so the matching text item in the array is returned.
FindItem(List, Key)
split("1 2 3 4 5")
4.0
"4"
Key is converted from a Double to a Text value, and the matching text item in the array is returned.
The Split function is used in some of the above examples to create an array of substrings that FindItem can operate on.
The following mrScriptBasic example uses the FindItem function to find an item called “Country” in a collection:
Dim myItem

Set myItem = myCollection.FindItem("Country")

If Not(myItem.IsNullObject()) Then
... ' Item found
Else
... ' Item not found
End If
See also
List functions