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

======Technical:======
This function treats the items in the array as wildcard patterns, and 
returns the wildcard pattern that "best matches" the literal string.
The item value of the best matching pattern is returned.

This string is similar to the [[rmatch]] function, and the reverse of
the [[matchitem]] function.

======Practical:======
These functions are analogous to $[[match]]() and $[[rmatch]]().  Given a word
or pattern, they search through the given array's contents and look
for the best match, if any.  Basically, the array's contents behave as
if they were the list of words or patterns passed to $[[match]]() or
$[[rmatch]]().

======Returns:======
<file>
> -1   item number in array that matched
  -1   could not find specified array
  -2   could not find a matching item
</file>