'\" '\" Copyright (c) 1993-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" RCS: @(#) $Id: array.n,v 1.2 2001/09/14 01:42:17 zlaski Exp $ '\" .so man.macros .TH array n 7.4 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME array \- Manipulate array variables .SH SYNOPSIS \fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP This command performs one of several operations on the variable given by \fIarrayName\fR. Unless otherwise specified for individual commands below, \fIarrayName\fR must be the name of an existing array variable. The \fIoption\fR argument determines what action is carried out by the command. The legal \fIoptions\fR (which may be abbreviated) are: .TP \fBarray anymore \fIarrayName searchId\fR Returns 1 if there are any more elements left to be processed in an array search, 0 if all elements have already been returned. \fISearchId\fR indicates which search on \fIarrayName\fR to check, and must have been the return value from a previous invocation of \fBarray startsearch\fR. This option is particularly useful if an array has an element with an empty name, since the return value from \fBarray nextelement\fR won't indicate whether the search has been completed. .TP \fBarray donesearch \fIarrayName searchId\fR This command terminates an array search and destroys all the state associated with that search. \fISearchId\fR indicates which search on \fIarrayName\fR to destroy, and must have been the return value from a previous invocation of \fBarray startsearch\fR. Returns an empty string. .TP \fBarray exists \fIarrayName\fR Returns 1 if \fIarrayName\fR is an array variable, 0 if there is no variable by that name or if it is a scalar variable. .TP \fBarray get \fIarrayName\fR ?\fIpattern\fR? Returns a list containing pairs of elements. The first element in each pair is the name of an element in \fIarrayName\fR and the second element of each pair is the value of the array element. The order of the pairs is undefined. If \fIpattern\fR is not specified, then all of the elements of the array are included in the result. If \fIpattern\fR is specified, then only those elements whose names match \fIpattern\fR (using the glob-style matching rules of \fBstring match\fR) are included. If \fIarrayName\fR isn't the name of an array variable, or if the array contains no elements, then an empty list is returned. .TP \fBarray names \fIarrayName\fR ?\fIpattern\fR? Returns a list containing the names of all of the elements in the array that match \fIpattern\fR (using the glob-style matching rules of \fBstring match\fR). If \fIpattern\fR 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 \fIarrayName\fR isn't the name of an array variable, then an empty string is returned. .TP \fBarray nextelement \fIarrayName searchId\fR Returns the name of the next element in \fIarrayName\fR, or an empty string if all elements of \fIarrayName\fR have already been returned in this search. The \fIsearchId\fR argument identifies the search, and must have been the return value of an \fBarray startsearch\fR command. Warning: if elements are added to or deleted from the array, then all searches are automatically terminated just as if \fBarray donesearch\fR had been invoked; this will cause \fBarray nextelement\fR operations to fail for those searches. .TP \fBarray set \fIarrayName list\fR Sets the values of one or more elements in \fIarrayName\fR. \fIlist\fR must have a form like that returned by \fBarray get\fR, consisting of an even number of elements. Each odd-numbered element in \fIlist\fR is treated as an element name within \fIarrayName\fR, and the following element in \fIlist\fR is used as a new value for that array element. If the variable \fIarrayName\fR does not already exist and \fIlist\fR is empty, \fIarrayName\fR is created with an empty array value. .TP \fBarray size \fIarrayName\fR Returns a decimal string giving the number of elements in the array. If \fIarrayName\fR isn't the name of an array then 0 is returned. .TP \fBarray startsearch \fIarrayName\fR This command initializes an element-by-element search through the array given by \fIarrayName\fR, such that invocations of the \fBarray nextelement\fR command will return the names of the individual elements in the array. When the search has been completed, the \fBarray donesearch\fR command should be invoked. The return value is a search identifier that must be used in \fBarray nextelement\fR and \fBarray donesearch\fR commands; it allows multiple searches to be underway simultaneously for the same array. .SH KEYWORDS array, element names, search