1<HTML><HEAD><TITLE>Tcl Built-In Commands - array manual page</TITLE></HEAD><BODY> 2<DL> 3<DD><A HREF="array.htm#M2" NAME="L49">NAME</A> 4<DL><DD>array - Manipulate array variables</DL> 5<DD><A HREF="array.htm#M3" NAME="L50">SYNOPSIS</A> 6<DL> 7<DD><B>array </B><I>option arrayName</I> ?<I>arg arg ...</I>? 8</DL> 9<DD><A HREF="array.htm#M4" NAME="L51">DESCRIPTION</A> 10<DL> 11<DD><A HREF="array.htm#M5" NAME="L52"><B>array anymore </B><I>arrayName searchId</I></A> 12<DD><A HREF="array.htm#M6" NAME="L53"><B>array donesearch </B><I>arrayName searchId</I></A> 13<DD><A HREF="array.htm#M7" NAME="L54"><B>array exists </B><I>arrayName</I></A> 14<DD><A HREF="array.htm#M8" NAME="L55"><B>array get </B><I>arrayName</I> ?<I>pattern</I>?</A> 15<DD><A HREF="array.htm#M9" NAME="L56"><B>array names </B><I>arrayName</I> ?<I>mode</I>? ?<I>pattern</I>?</A> 16<DD><A HREF="array.htm#M10" NAME="L57"><B>array nextelement </B><I>arrayName searchId</I></A> 17<DD><A HREF="array.htm#M11" NAME="L58"><B>array set </B><I>arrayName list</I></A> 18<DD><A HREF="array.htm#M12" NAME="L59"><B>array size </B><I>arrayName</I></A> 19<DD><A HREF="array.htm#M13" NAME="L60"><B>array startsearch </B><I>arrayName</I></A> 20<DD><A HREF="array.htm#M14" NAME="L61"><B>array statistics </B><I>arrayName</I></A> 21<DD><A HREF="array.htm#M15" NAME="L62"><B>array unset </B><I>arrayName</I> ?<I>pattern</I>?</A> 22</DL> 23<DD><A HREF="array.htm#M16" NAME="L63">EXAMPLES</A> 24<DD><A HREF="array.htm#M17" NAME="L64">SEE ALSO</A> 25<DD><A HREF="array.htm#M18" NAME="L65">KEYWORDS</A> 26</DL><HR> 27<H3><A NAME="M2">NAME</A></H3> 28array - Manipulate array variables 29<H3><A NAME="M3">SYNOPSIS</A></H3> 30<B>array </B><I>option arrayName</I> ?<I>arg arg ...</I>?<BR> 31<H3><A NAME="M4">DESCRIPTION</A></H3> 32This command performs one of several operations on the 33variable given by <I>arrayName</I>. 34Unless otherwise specified for individual commands below, 35<I>arrayName</I> must be the name of an existing array variable. 36The <I>option</I> argument determines what action is carried 37out by the command. 38The legal <I>options</I> (which may be abbreviated) are: 39<P> 40<DL> 41<DT><A NAME="M5"><B>array anymore </B><I>arrayName searchId</I></A><DD> 42Returns 1 if there are any more elements left to be processed 43in an array search, 0 if all elements have already been 44returned. 45<I>SearchId</I> indicates which search on <I>arrayName</I> to 46check, and must have been the return value from a previous 47invocation of <B>array startsearch</B>. 48This option is particularly useful if an array has an element 49with an empty name, since the return value from 50<B>array nextelement</B> won't indicate whether the search 51has been completed. 52<P><DT><A NAME="M6"><B>array donesearch </B><I>arrayName searchId</I></A><DD> 53This command terminates an array search and destroys all the 54state associated with that search. <I>SearchId</I> indicates 55which search on <I>arrayName</I> to destroy, and must have 56been the return value from a previous invocation of 57<B>array startsearch</B>. Returns an empty string. 58<P><DT><A NAME="M7"><B>array exists </B><I>arrayName</I></A><DD> 59Returns 1 if <I>arrayName</I> is an array variable, 0 if there 60is no variable by that name or if it is a scalar variable. 61<P><DT><A NAME="M8"><B>array get </B><I>arrayName</I> ?<I>pattern</I>?</A><DD> 62Returns a list containing pairs of elements. The first 63element in each pair is the name of an element in <I>arrayName</I> 64and the second element of each pair is the value of the 65array element. The order of the pairs is undefined. 66If <I>pattern</I> is not specified, then all of the elements of the 67array are included in the result. 68If <I>pattern</I> is specified, then only those elements whose names 69match <I>pattern</I> (using the matching rules of 70<B><A HREF="../TclCmd/string.htm">string match</A></B>) are included. 71If <I>arrayName</I> isn't the name of an array variable, or if 72the array contains no elements, then an empty list is returned. 73<P><DT><A NAME="M9"><B>array names </B><I>arrayName</I> ?<I>mode</I>? ?<I>pattern</I>?</A><DD> 74Returns a list containing the names of all of the elements in 75the array that match <I>pattern</I>. <I>Mode</I> may be one of 76<B>-exact</B>, <B>-glob</B>, or <B>-regexp</B>. If specified, <I>mode</I> 77designates which matching rules to use to match <I>pattern</I> against 78the names of the elements in the array. If not specified, <I>mode</I> 79defaults to <B>-glob</B>. See the documentation for <B><A HREF="../TclCmd/string.htm">string match</A></B> 80for information on glob style matching, and the documentation for 81<B><A HREF="../TclCmd/regexp.htm">regexp</A></B> for information on regexp matching. 82If <I>pattern</I> is omitted then the command returns all of 83the element names in the array. If there are no (matching) elements 84in the array, or if <I>arrayName</I> isn't the name of an array 85variable, then an empty string is returned. 86<P><DT><A NAME="M10"><B>array nextelement </B><I>arrayName searchId</I></A><DD> 87Returns the name of the next element in <I>arrayName</I>, or 88an empty string if all elements of <I>arrayName</I> have 89already been returned in this search. The <I>searchId</I> 90argument identifies the search, and must have 91been the return value of an <B>array startsearch</B> command. 92Warning: if elements are added to or deleted from the array, 93then all searches are automatically terminated just as if 94<B>array donesearch</B> had been invoked; this will cause 95<B>array nextelement</B> operations to fail for those searches. 96<P><DT><A NAME="M11"><B>array set </B><I>arrayName list</I></A><DD> 97Sets the values of one or more elements in <I>arrayName</I>. 98<I>list</I> must have a form like that returned by <B>array get</B>, 99consisting of an even number of elements. 100Each odd-numbered element in <I>list</I> is treated as an element 101name within <I>arrayName</I>, and the following element in <I>list</I> 102is used as a new value for that array element. 103If the variable <I>arrayName</I> does not already exist 104and <I>list</I> is empty, 105<I>arrayName</I> is created with an empty array value. 106<P><DT><A NAME="M12"><B>array size </B><I>arrayName</I></A><DD> 107Returns a decimal string giving the number of elements in the 108array. 109If <I>arrayName</I> isn't the name of an array then 0 is returned. 110<P><DT><A NAME="M13"><B>array startsearch </B><I>arrayName</I></A><DD> 111This command initializes an element-by-element search through the 112array given by <I>arrayName</I>, such that invocations of the 113<B>array nextelement</B> command will return the names of the 114individual elements in the array. 115When the search has been completed, the <B>array donesearch</B> 116command should be invoked. 117The return value is a 118search identifier that must be used in <B>array nextelement</B> 119and <B>array donesearch</B> commands; it allows multiple 120searches to be underway simultaneously for the same array. 121It is currently more efficient and easier to use either the <B>array 122get</B> or <B>array names</B>, together with <B><A HREF="../TclCmd/foreach.htm">foreach</A></B>, to iterate 123over all but very large arrays. See the examples below for how to do 124this. 125<P><DT><A NAME="M14"><B>array statistics </B><I>arrayName</I></A><DD> 126Returns statistics about the distribution of data within the hashtable 127that represents the array. This information includes the number of 128entries in the table, the number of buckets, and the utilization of 129the buckets. 130<P><DT><A NAME="M15"><B>array unset </B><I>arrayName</I> ?<I>pattern</I>?</A><DD> 131Unsets all of the elements in the array that match <I>pattern</I> (using the 132matching rules of <B><A HREF="../TclCmd/string.htm">string match</A></B>). If <I>arrayName</I> isn't the name 133of an array variable or there are no matching elements in the array, no 134error will be raised. If <I>pattern</I> is omitted and <I>arrayName</I> is 135an array variable, then the command unsets the entire array. 136The command always returns an empty string. 137<P></DL> 138<H3><A NAME="M16">EXAMPLES</A></H3> 139<PRE><B>array set</B> colorcount { 140 red 1 141 green 5 142 blue 4 143 white 9 144} 145 146foreach {color count} [<B>array get</B> colorcount] { 147 puts "Color: $color Count: $count" 148} 149 => Color: blue Count: 4 150 Color: white Count: 9 151 Color: green Count: 5 152 Color: red Count: 1 153 154foreach color [<B>array names</B> colorcount] { 155 puts "Color: $color Count: $colorcount($color)" 156} 157 => Color: blue Count: 4 158 Color: white Count: 9 159 Color: green Count: 5 160 Color: red Count: 1 161 162foreach color [lsort [array names colorcount]] { 163 puts "Color: $color Count: $colorcount($color)" 164} 165 => Color: blue Count: 4 166 Color: green Count: 5 167 Color: red Count: 1 168 Color: white Count: 9 169 170<B>array statistics</B> colorcount 171 => 4 entries in table, 4 buckets 172 number of buckets with 0 entries: 1 173 number of buckets with 1 entries: 2 174 number of buckets with 2 entries: 1 175 number of buckets with 3 entries: 0 176 number of buckets with 4 entries: 0 177 number of buckets with 5 entries: 0 178 number of buckets with 6 entries: 0 179 number of buckets with 7 entries: 0 180 number of buckets with 8 entries: 0 181 number of buckets with 9 entries: 0 182 number of buckets with 10 or more entries: 0 183 average search distance for entry: 1.2</PRE> 184<H3><A NAME="M17">SEE ALSO</A></H3> 185<B><A HREF="../TclCmd/list.htm">list</A></B>, <B><A HREF="../TclCmd/string.htm">string</A></B>, <B><A HREF="../TclCmd/variable.htm">variable</A></B>, <B><A HREF="../TclCmd/trace.htm">trace</A></B>, <B><A HREF="../TclCmd/foreach.htm">foreach</A></B> 186<H3><A NAME="M18">KEYWORDS</A></H3> 187<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> 188<HR><PRE> 189<A HREF="../copyright.htm">Copyright</A> © 1993-1994 The Regents of the University of California. 190<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc. 191<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE> 192</BODY></HTML> 193