NAME
       array - Manipulate array variables

SYNOPSIS
       array option arrayName ?arg arg ...?


DESCRIPTION
       This  command  performs  one  of several operations on the
       variable given by arrayName.  Unless  otherwise  specified
       for  individual commands below, arrayName must be the name
       of an existing array variable.  The option argument deter-
       mines  what  action  is  carried  out by the command.  The
       legal options (which may be abbreviated) are:

       array anymore arrayName searchId
              Returns 1 if there are any more elements left to be
              processed  in  an  array  search, 0 if all elements
              have already  been  returned.   SearchId  indicates
              which  search  on arrayName to check, and must have
              been the return value from a previous invocation of
              array  startsearch.   This  option  is particularly
              useful if an array has an  element  with  an  empty
              name, since the return value from array nextelement
              won't indicate whether the  search  has  been  com-
              pleted.

       array donesearch arrayName searchId
              This   command   terminates  an  array  search  and
              destroys all the state associated with that search.
              SearchId  indicates  which  search  on arrayName to
              destroy, and must have been the return value from a
              previous  invocation of array startsearch.  Returns
              an empty string.

       array exists arrayName
              Returns 1 if arrayName is an array variable,  0  if
              there  is  no  variable  by that name or if it is a
              scalar variable.

       array get arrayName ?pattern?
              Returns a list containing pairs of  elements.   The
              first  element  in each pair is the name of an ele-
              ment in arrayName and the second  element  of  each
              pair  is the value of the array element.  The order
              of the pairs is undefined.  If pattern is not spec-
              ified,  then  all  of the elements of the array are
              included in the result.  If pattern  is  specified,
              then  only those elements whose names match pattern
              (using the matching  rules  of  string  match)  are
              included.   If arrayName isn't the name of an array
              variable, or if the  array  contains  no  elements,
              then an empty list is returned.
       array names arrayName ?pattern?
              Returns  a  list containing the names of all of the
              elements in the array that match pattern (using the
              matching  rules  of  string  match).  If pattern is
              omitted then the command returns all of the element
              names  in  the  array.   If there are no (matching)
              elements in the array, or if  arrayName  isn't  the
              name  of an array variable, then an empty string is
              returned.

       array nextelement arrayName searchId
              Returns the name of the next element in  arrayName,
              or  an  empty  string  if all elements of arrayName
              have already been returned  in  this  search.   The
              searchId  argument  identifies the search, and must
              have been the return value of an array  startsearch
              command.   Warning:   if  elements  are added to or
              deleted from the array, then all searches are auto-
              matically  terminated  just  as if array donesearch
              had been invoked; this will cause array nextelement
              operations to fail for those searches.

       array set arrayName list
              Sets  the  values of one or more elements in array-
              Name.  list must have a form like that returned  by
              array  get,  consisting  of  an even number of ele-
              ments.   Each  odd-numbered  element  in  list   is
              treated  as  an  element name within arrayName, and
              the following element in list  is  used  as  a  new
              value  for  that  array  element.   If the variable
              arrayName does not already exist and list is empty,
              arrayName is created with an empty array value.

       array size arrayName
              Returns  a decimal string giving the number of ele-
              ments in the array.  If arrayName isn't the name of
              an array then 0 is returned.

       array startsearch arrayName
              This   command  initializes  an  element-by-element
              search through the array given by  arrayName,  such
              that  invocations  of the array nextelement command
              will return the names of the individual elements in
              the array.  When the search has been completed, the
              array donesearch command should  be  invoked.   The
              return  value  is  a search identifier that must be
              used in array nextelement and array donesearch com-
              mands;  it  allows multiple searches to be underway
              simultaneously for the same array.

       array unset arrayName ?pattern?
              Unsets all of the elements in the array that  match
              pattern (using the matching rules of string match).
              If arrayName isn't the name of an array variable or
              there  are  no matching elements in the array, then
              an empty string is returned.  If pattern is omitted
              and  is  it  an  array  variable,  then the command
              unsets the entire array.


KEYWORDS
       array, element names, search
