ircII has traditionally been able to deal with various sets of data in
numerous ways.  The usual ways are generally word lists (a list of words
inside a variable) and structures (a tree-like structure of variables or
aliases).  These are explained adequately in the ALIAS and ASSIGN help
files, as well as ircII programming.

ircII-EPIC adds another composite data type, arrays, courtesy of Aaron
Gifford <Karll!agifford@sci.dixie.edu>.  These arrays are accessed with
a set of function specially designed for this purpose.  They are not, and
indeed cannot be, accessed as conventional variables are.  In other words,
if you create an array called `blah' with an item in cell 0, you cannot
get at the data with $blah[0].  Similarly, a structure $foo[0] cannot be
accessed with the array functions.  Arrays and structures are mutually
exclusive.

The upside is that these arrays are blindingly fast, as they are binary
searchable.  Additionally, data they hold remains case-sensitive, which
can often prove useful.  The only downside is this is yet another thing
to learn ;)

The following conventions are followed:

  array names: the name of the array, case-insensitive, may be composed
    of any printable, non-whitespace character
  item number: the cell the data is being placed into, starting with 0,
    numbered sequentially
  index number: the item number translated to the data's order in the
    array, according to qsort() (semi-alphabetical)
  data: whatever you want to place inthe array cell, case-sensitive

Now for the actual functions.  Much of this is ripped straight from Karll's
documentation on the functions in array.c, I only take credit for making it
more readable ;)

  $setitem(array item# data)
    This is used to add data to an existing array.  If the specified array
    does not exist, it is created.
      returns:
         0 (zero) if an existing item# is assigned data
         1 if a new array is created
         2 if a new item# is added
        -1 if cannot find array (item# > 0)
        -2 if cannot find item# (item# too large)

  $getitem(array item#)
    This returns the data in item# from the given array, or an empty
    string if either the array or item cannot be found.

  $numitems(array)
    This returns the number of items in the given array, or an empty
    string if the array cannot be found.

  $delitem(array item#)
    This deletes an item from the array.  Because items in the array are
    always sorted sequentially, items are shifted as needed to fill empty
    spots left behind by deleted data.  For instance, if item 5 is deleted
    from an array of 9 elements (0..8), 6-7-8 are bumped down to 5-6-7.
    If the item deleted is the only item in the array, the array is also
    deleted.
      returns:
         0 (zero) if item is successfully deleted
        -1 if cannot find array
        -2 if cannot find item

  $matchitem(array pattern)
    This searches through the array's contents for the data that best
    matches the pattern specified, similar to the $match() function.
      returns:
         0 (zero) or a positive integer, which is the item# matched
        -1 if cannot find array
        -2 if cannot find a match

  $rmatchitem(array data)
    Same as $matchitem(), except it searches the array for the pattern
    best matching the given data, similar to $rmatch().
      returns:
         0 (zero) or a positive integer, which is the item# matched
        -1 if cannot find array
        -2 if cannot find a match

  $getmatches(array pattern)
    Similar to $matchitem(), except it returns a list of all item#'s that
    match the given pattern.  If none match, an empty string is returned.

  $getrmatches(array data)
    Same as $getmatches(), except it matches patterns in the array vs. the
    data given.

  $finditem(array data)
    This looks in the array for an exact match to the data specified.  The
    array is binary searched, and the match is case-sensitive (a departure
    from normal ircII conventions).
      returns:
         0 (zero) or a positive integer, which is the first item# matched
        -1 if cannot find array
        -2 if cannot find a match

  $igetitem(array index#)
    Same as $getitem(), except it uses the index number.  Normally arrays
    are sorted based on the order data is entered.  With this and the other
    `index' functions, they are evaluated in semi-alphabetic order (or more
    precisely, using their ascii order, like $sort() does).  The item and
    index numbers will always be within the same range.  It returns the
    data referred to by the index, or an empty string if either the array
    or the index cannot be found.

  $ifinditem(array data)
    Same as $finditem(), except it returns the index# to the first match
    found.

  $ifindfirst(array data)
    Same as $ifinditem(), except it returns the first index# found that
    matches the data given.  The difference is that $ifinditem() still
    searches in the item order, whereas this searches in theindex order.
    (Well not really, but it's convenient to think of it like that ;).)

  $indextoitem(array index#)
    This converts an index number to an item number (see $igetitem()).
      returns:
        the item# corresponding to the given index#
        -1 if cannot find array
        -2 if cannot find index

  $itemtoindex(array item#)
    The opposite of $indextoitem().
      returns:
        the index# corresponding to the given item#
        -1 if cannot find array
        -2 if cannot find item

  $delarray(array)
    Deletes all items in the specified array (and thus the array itself).
      returns:
         0 (zero) if the array was successfully deleted
        -1 if cannot find array

  $numarrays()
    Returns the number of arrays that currently exist.


  $getarrays()
    Returns a space-separated list of all existing arrays, or an empty
    string if none.

