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 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