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
              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 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
              glob-style 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.

       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.


KEYWORDS
       array, element names, search
