no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.

@@ Line 1: / Line 1: @@
+# $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>