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