finditem, ifinditem, ifindfirst
Synopsis:
$finditem(
$ifinditem(
$ifindfirst(
Technical:
These functions do a binary search on the items stored in the given array, looking
for an exact match of the input string. It will only return the results
of an exact match. Unlike other string handlers in the client, these are case-sensitive.
They only operate on arrays created with the $setitem( ) function. These
functions differ only in which exact match they will return. The $finditem(
) function returns the item number of the first match found; it does not
check the array sequentially, so other exact matches with lower item numbers
may not be returned. The $ifinditem( ) function is same, except it returns
the index number of the first match found (also regardless of the actual indexing
order). The $ifindfirst( ) function is similar to $ifinditem( ),
except it returns the first exact match after the array has been sorted.
Practical:
These functions are useful when you want to see if a particular string is present
in an array. Being sensitive to case, they are more precise than the general
pattern-matching functions.
Returns:
-2 item not found in array
-1 array does not exist
> -1 item/index number that matches input
Examples:
/* contrived sample array */
$setitem(booya 0 blah)
$setitem(booya 1 foobar)
$setitem(booya 2 blah)
$finditem(booya blah)
returns 0
$ifinditem(booya blah) returns 1
$ifindfirst(booya blah) returns 0
$finditem(booya Blah) returns -1
$finditem(foobar blah) returns -2
See Also:
Arrays
getitem
setitem