$finditem(<array> <string>)

If you remember with setitem, you provided an array name, an item number, and some stuff. This function returns the item number of an item whose “stuff” is <string>. Because this function does a binary search, if multiple items have the same “stuff”, there's no rule which one will be returned.

To be more precise about it, this function returns a number N such that

getitem(//array// $finditem(//array// //string//) === '//string//'

is true. If multiple items in the array have the same value string, which one is returned is undefined. Check out findfirst to get the first one, and finditems to get a list of all of them. Check out ifinditem to get the index number instead of the item number.

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.

  -2   item not found in array
  -1   array does not exist
> -1   item/index number that matches input

/* 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