array

array(n)                     Tcl Built-In Commands                    array(n)



______________________________________________________________________________

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 determines 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
              completed.

       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 element 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
              specified, 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 automatically 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 arrayName.  list must
              have a form like that returned by array get, consisting of an
              even number of elements.  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 elements 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 commands; 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



Tcl                                   8.3                             array(n)