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