# $EPIC: finditem.txt,v 1.3 2007/02/27 04:57:37 jnelson Exp $
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