129 lines
7.0 KiB
HTML
129 lines
7.0 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - array manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="array.htm#M2" NAME="L35">NAME</A>
|
|
<DL><DD>array - Manipulate array variables</DL>
|
|
<DD><A HREF="array.htm#M3" NAME="L36">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>array </B><I>option arrayName</I> ?<I>arg arg ...</I>?
|
|
</DL>
|
|
<DD><A HREF="array.htm#M4" NAME="L37">DESCRIPTION</A>
|
|
<DL>
|
|
<DD><A HREF="array.htm#M5" NAME="L38"><B>array anymore </B><I>arrayName searchId</I></A>
|
|
<DD><A HREF="array.htm#M6" NAME="L39"><B>array donesearch </B><I>arrayName searchId</I></A>
|
|
<DD><A HREF="array.htm#M7" NAME="L40"><B>array exists </B><I>arrayName</I></A>
|
|
<DD><A HREF="array.htm#M8" NAME="L41"><B>array get </B><I>arrayName</I> ?<I>pattern</I>?</A>
|
|
<DD><A HREF="array.htm#M9" NAME="L42"><B>array names </B><I>arrayName</I> ?<I>pattern</I>?</A>
|
|
<DD><A HREF="array.htm#M10" NAME="L43"><B>array nextelement </B><I>arrayName searchId</I></A>
|
|
<DD><A HREF="array.htm#M11" NAME="L44"><B>array set </B><I>arrayName list</I></A>
|
|
<DD><A HREF="array.htm#M12" NAME="L45"><B>array size </B><I>arrayName</I></A>
|
|
<DD><A HREF="array.htm#M13" NAME="L46"><B>array startsearch </B><I>arrayName</I></A>
|
|
<DD><A HREF="array.htm#M14" NAME="L47"><B>array unset </B><I>arrayName</I> ?<I>pattern</I>?</A>
|
|
</DL>
|
|
<DD><A HREF="array.htm#M15" NAME="L48">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
array - Manipulate array variables
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>array </B><I>option arrayName</I> ?<I>arg arg ...</I>?<BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
This command performs one of several operations on the
|
|
variable given by <I>arrayName</I>.
|
|
Unless otherwise specified for individual commands below,
|
|
<I>arrayName</I> must be the name of an existing array variable.
|
|
The <I>option</I> argument determines what action is carried
|
|
out by the command.
|
|
The legal <I>options</I> (which may be abbreviated) are:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M5"><B>array anymore </B><I>arrayName searchId</I></A><DD>
|
|
Returns 1 if there are any more elements left to be processed
|
|
in an array search, 0 if all elements have already been
|
|
returned.
|
|
<I>SearchId</I> indicates which search on <I>arrayName</I> to
|
|
check, and must have been the return value from a previous
|
|
invocation of <B>array startsearch</B>.
|
|
This option is particularly useful if an array has an element
|
|
with an empty name, since the return value from
|
|
<B>array nextelement</B> won't indicate whether the search
|
|
has been completed.
|
|
<P><DT><A NAME="M6"><B>array donesearch </B><I>arrayName searchId</I></A><DD>
|
|
This command terminates an array search and destroys all the
|
|
state associated with that search. <I>SearchId</I> indicates
|
|
which search on <I>arrayName</I> to destroy, and must have
|
|
been the return value from a previous invocation of
|
|
<B>array startsearch</B>. Returns an empty string.
|
|
<P><DT><A NAME="M7"><B>array exists </B><I>arrayName</I></A><DD>
|
|
Returns 1 if <I>arrayName</I> is an array variable, 0 if there
|
|
is no variable by that name or if it is a scalar variable.
|
|
<P><DT><A NAME="M8"><B>array get </B><I>arrayName</I> ?<I>pattern</I>?</A><DD>
|
|
Returns a list containing pairs of elements. The first
|
|
element in each pair is the name of an element in <I>arrayName</I>
|
|
and the second element of each pair is the value of the
|
|
array element. The order of the pairs is undefined.
|
|
If <I>pattern</I> is not specified, then all of the elements of the
|
|
array are included in the result.
|
|
If <I>pattern</I> is specified, then only those elements whose names
|
|
match <I>pattern</I> (using the matching rules of
|
|
<B><A HREF="../TkCmd/string.htm">string match</A></B>) are included.
|
|
If <I>arrayName</I> isn't the name of an array variable, or if
|
|
the array contains no elements, then an empty list is returned.
|
|
<P><DT><A NAME="M9"><B>array names </B><I>arrayName</I> ?<I>pattern</I>?</A><DD>
|
|
Returns a list containing the names of all of the elements in
|
|
the array that match <I>pattern</I> (using the matching
|
|
rules of <B><A HREF="../TkCmd/string.htm">string match</A></B>).
|
|
If <I>pattern</I> 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 <I>arrayName</I>
|
|
isn't the name of an array variable, then an empty string is
|
|
returned.
|
|
<P><DT><A NAME="M10"><B>array nextelement </B><I>arrayName searchId</I></A><DD>
|
|
Returns the name of the next element in <I>arrayName</I>, or
|
|
an empty string if all elements of <I>arrayName</I> have
|
|
already been returned in this search. The <I>searchId</I>
|
|
argument identifies the search, and must have
|
|
been the return value of an <B>array startsearch</B> command.
|
|
Warning: if elements are added to or deleted from the array,
|
|
then all searches are automatically terminated just as if
|
|
<B>array donesearch</B> had been invoked; this will cause
|
|
<B>array nextelement</B> operations to fail for those searches.
|
|
<P><DT><A NAME="M11"><B>array set </B><I>arrayName list</I></A><DD>
|
|
Sets the values of one or more elements in <I>arrayName</I>.
|
|
<I>list</I> must have a form like that returned by <B>array get</B>,
|
|
consisting of an even number of elements.
|
|
Each odd-numbered element in <I>list</I> is treated as an element
|
|
name within <I>arrayName</I>, and the following element in <I>list</I>
|
|
is used as a new value for that array element.
|
|
If the variable <I>arrayName</I> does not already exist
|
|
and <I>list</I> is empty,
|
|
<I>arrayName</I> is created with an empty array value.
|
|
<P><DT><A NAME="M12"><B>array size </B><I>arrayName</I></A><DD>
|
|
Returns a decimal string giving the number of elements in the
|
|
array.
|
|
If <I>arrayName</I> isn't the name of an array then 0 is returned.
|
|
<P><DT><A NAME="M13"><B>array startsearch </B><I>arrayName</I></A><DD>
|
|
This command initializes an element-by-element search through the
|
|
array given by <I>arrayName</I>, such that invocations of the
|
|
<B>array nextelement</B> command will return the names of the
|
|
individual elements in the array.
|
|
When the search has been completed, the <B>array donesearch</B>
|
|
command should be invoked.
|
|
The return value is a
|
|
search identifier that must be used in <B>array nextelement</B>
|
|
and <B>array donesearch</B> commands; it allows multiple
|
|
searches to be underway simultaneously for the same array.
|
|
<P><DT><A NAME="M14"><B>array unset </B><I>arrayName</I> ?<I>pattern</I>?</A><DD>
|
|
Unsets all of the elements in the array that match <I>pattern</I> (using the
|
|
matching rules of <B><A HREF="../TkCmd/string.htm">string match</A></B>). If <I>arrayName</I> isn't the name
|
|
of an array variable or there are no matching elements in the array, then
|
|
an empty string is returned. If <I>pattern</I> is omitted and is it an
|
|
array variable, then the command unsets the entire array.
|
|
|
|
<P></DL>
|
|
<H3><A NAME="M15">KEYWORDS</A></H3>
|
|
<A href="../Keywords/A.htm#array">array</A>, <A href="../Keywords/E.htm#element names">element names</A>, <A href="../Keywords/S.htm#search">search</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1993-1994 The Regents of the University of California.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|