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


KEYWORDS
       array, element names, search
