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

======Description:======
If you remember with [[setitem]], you provided an array name, an item
number, and some stuff.  This function returns a word list of ALL of the
item numbers whose "stuff" is <string>.

To be more precise about it, this function returns a word list //X// that
contains numbers //N// such that

	for i in ($finditems(//array// //string//)) { 
		if (getitem(//array// $i) === '//string//' {
			echo True;
		} else {
			echo False;
		};
	};

only outputs True and never False.  This function is slower than [[finditem]]
which only finds one item, instead of all of them.  The function [[ifindfirst]]
finds the first 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>