$ifindfirst(<array> <string>)

If you remember with setitem, you provided an array name, an item number, and some stuff. This function returns the index number of an item whose “stuff” is <string>. Even though this does a binary search, if multiple items have the same “stuff”, this function will return the value of the first one of them.

To be more precise about it, this function returns the smallest number N for which

igetitem(//array// $ifindfirst(//array// //string//) === '//string//'

is true. If multiple items in the array have the same value string, the first one is returned. This makes it slower than ifinditem that doesn't look for the smallest value. Check out ifinditems to get a list of all the items. Check out finditem to get the item number instead of the index 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