# $EPIC: itemtoindex.txt,v 1.2 2006/08/01 03:40:36 sthalik Exp $
======Synopsis:======
$indextoitem(<array> <index number>) \\
$itemtoindex(<array> <item number>)

======Technical:======
These functions are used to convert between array item numbers are index
numbers.

Item numbers are counted incrementally as items are added to an array,
starting at 0 (zero).  Each new item uses the next available item number;
if there are 5 items in an array, the next item that may be added is item
number 5 (remember that we count from zero... 5 items is 0..4).

Index numbers represent each items position in the array when sorted.
Items are sorted based on their ascii values.  This is generally
alphabetical; however, since it is based on ascii values, all capital
letters are sorted after all lowercase letters.  It follows a sorting
algorithm similar to the $[[sort]]() function's.

======Practical:======
The $__indextoitem__() function converts an index number in the given array
to its corresponding item number; $__itemtoindex__() does just the opposite.
This is mostly useful in conjunction with $[[igetitem]]() or $[[ifinditem]](),
allowing an array to be dealt with in a logical order.

======Returns:======
<file>
  -2   cannot find index/item number in array
  -1   cannot find named array
> -1   item number corresponding to given index number (and vice verse)
</file>

======Examples:======
<file>
$setitem(booya 0 hello)
$setitem(booya 1 goodbye)
$itemtoindex(booya 0)                 returns 1
$indextoitem(booya 1)                 returns 0
$itemtoindex(foobar 0)                returns -1
$itemtoindex(booya 100)               returns -2
</file>