Synopsis:
   $finditem(<array> <string>)
   $ifinditem(<array> <string>)
   $ifindfirst(<array> <string>)

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(7); getitem(6); setitem(6)