# $EPIC: finditem.txt,v 1.3 2007/02/27 04:57:37 jnelson Exp $
======Synopsis:======
$__finditem__(<array> <string>) 

======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 <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.

======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:======
<file>
  -2   item not found in array
  -1   array does not exist
> -1   item/index number that matches input
</file>

======Examples:======
<file>
/* 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
</file>