# $EPIC: ifindfirst.txt,v 1.2 2007/02/27 04:57:37 jnelson Exp $
======Synopsis:======
$[[ifindfirst]](<array> <string>) 

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

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