1 | '\" |
---|
2 | '\" Copyright (c) 1993-1994 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: array.n,v 1.21 2007/12/13 15:22:32 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH array n 8.3 Tcl "Tcl Built-In Commands" |
---|
12 | .BS |
---|
13 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
14 | .SH NAME |
---|
15 | array \- Manipulate array variables |
---|
16 | .SH SYNOPSIS |
---|
17 | \fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR? |
---|
18 | .BE |
---|
19 | .SH DESCRIPTION |
---|
20 | .PP |
---|
21 | This command performs one of several operations on the |
---|
22 | variable given by \fIarrayName\fR. |
---|
23 | Unless otherwise specified for individual commands below, |
---|
24 | \fIarrayName\fR must be the name of an existing array variable. |
---|
25 | The \fIoption\fR argument determines what action is carried |
---|
26 | out by the command. |
---|
27 | The legal \fIoptions\fR (which may be abbreviated) are: |
---|
28 | .TP |
---|
29 | \fBarray anymore \fIarrayName searchId\fR |
---|
30 | Returns 1 if there are any more elements left to be processed |
---|
31 | in an array search, 0 if all elements have already been |
---|
32 | returned. |
---|
33 | \fISearchId\fR indicates which search on \fIarrayName\fR to |
---|
34 | check, and must have been the return value from a previous |
---|
35 | invocation of \fBarray startsearch\fR. |
---|
36 | This option is particularly useful if an array has an element |
---|
37 | with an empty name, since the return value from |
---|
38 | \fBarray nextelement\fR will not indicate whether the search |
---|
39 | has been completed. |
---|
40 | .TP |
---|
41 | \fBarray donesearch \fIarrayName searchId\fR |
---|
42 | This command terminates an array search and destroys all the |
---|
43 | state associated with that search. \fISearchId\fR indicates |
---|
44 | which search on \fIarrayName\fR to destroy, and must have |
---|
45 | been the return value from a previous invocation of |
---|
46 | \fBarray startsearch\fR. Returns an empty string. |
---|
47 | .TP |
---|
48 | \fBarray exists \fIarrayName\fR |
---|
49 | Returns 1 if \fIarrayName\fR is an array variable, 0 if there |
---|
50 | is no variable by that name or if it is a scalar variable. |
---|
51 | .TP |
---|
52 | \fBarray get \fIarrayName\fR ?\fIpattern\fR? |
---|
53 | Returns a list containing pairs of elements. The first |
---|
54 | element in each pair is the name of an element in \fIarrayName\fR |
---|
55 | and the second element of each pair is the value of the |
---|
56 | array element. The order of the pairs is undefined. |
---|
57 | If \fIpattern\fR is not specified, then all of the elements of the |
---|
58 | array are included in the result. |
---|
59 | If \fIpattern\fR is specified, then only those elements whose names |
---|
60 | match \fIpattern\fR (using the matching rules of |
---|
61 | \fBstring match\fR) are included. |
---|
62 | If \fIarrayName\fR is not the name of an array variable, or if |
---|
63 | the array contains no elements, then an empty list is returned. |
---|
64 | If traces on the array modify the list of elements, the elements |
---|
65 | returned are those that exist both before and after the call to |
---|
66 | \fBarray get\fR. |
---|
67 | .TP |
---|
68 | \fBarray names \fIarrayName\fR ?\fImode\fR? ?\fIpattern\fR? |
---|
69 | Returns a list containing the names of all of the elements in |
---|
70 | the array that match \fIpattern\fR. \fIMode\fR may be one of |
---|
71 | \fB\-exact\fR, \fB\-glob\fR, or \fB\-regexp\fR. If specified, \fImode\fR |
---|
72 | designates which matching rules to use to match \fIpattern\fR against |
---|
73 | the names of the elements in the array. If not specified, \fImode\fR |
---|
74 | defaults to \fB\-glob\fR. See the documentation for \fBstring match\fR |
---|
75 | for information on glob style matching, and the documentation for |
---|
76 | \fBregexp\fR for information on regexp matching. |
---|
77 | If \fIpattern\fR is omitted then the command returns all of |
---|
78 | the element names in the array. If there are no (matching) elements |
---|
79 | in the array, or if \fIarrayName\fR is not the name of an array |
---|
80 | variable, then an empty string is returned. |
---|
81 | .TP |
---|
82 | \fBarray nextelement \fIarrayName searchId\fR |
---|
83 | Returns the name of the next element in \fIarrayName\fR, or |
---|
84 | an empty string if all elements of \fIarrayName\fR have |
---|
85 | already been returned in this search. The \fIsearchId\fR |
---|
86 | argument identifies the search, and must have |
---|
87 | been the return value of an \fBarray startsearch\fR command. |
---|
88 | Warning: if elements are added to or deleted from the array, |
---|
89 | then all searches are automatically terminated just as if |
---|
90 | \fBarray donesearch\fR had been invoked; this will cause |
---|
91 | \fBarray nextelement\fR operations to fail for those searches. |
---|
92 | .TP |
---|
93 | \fBarray set \fIarrayName list\fR |
---|
94 | Sets the values of one or more elements in \fIarrayName\fR. |
---|
95 | \fIlist\fR must have a form like that returned by \fBarray get\fR, |
---|
96 | consisting of an even number of elements. |
---|
97 | Each odd-numbered element in \fIlist\fR is treated as an element |
---|
98 | name within \fIarrayName\fR, and the following element in \fIlist\fR |
---|
99 | is used as a new value for that array element. |
---|
100 | If the variable \fIarrayName\fR does not already exist |
---|
101 | and \fIlist\fR is empty, |
---|
102 | \fIarrayName\fR is created with an empty array value. |
---|
103 | .TP |
---|
104 | \fBarray size \fIarrayName\fR |
---|
105 | Returns a decimal string giving the number of elements in the |
---|
106 | array. |
---|
107 | If \fIarrayName\fR is not the name of an array then 0 is returned. |
---|
108 | .TP |
---|
109 | \fBarray startsearch \fIarrayName\fR |
---|
110 | This command initializes an element-by-element search through the |
---|
111 | array given by \fIarrayName\fR, such that invocations of the |
---|
112 | \fBarray nextelement\fR command will return the names of the |
---|
113 | individual elements in the array. |
---|
114 | When the search has been completed, the \fBarray donesearch\fR |
---|
115 | command should be invoked. |
---|
116 | The return value is a |
---|
117 | search identifier that must be used in \fBarray nextelement\fR |
---|
118 | and \fBarray donesearch\fR commands; it allows multiple |
---|
119 | searches to be underway simultaneously for the same array. |
---|
120 | It is currently more efficient and easier to use either the \fBarray |
---|
121 | get\fR or \fBarray names\fR, together with \fBforeach\fR, to iterate |
---|
122 | over all but very large arrays. See the examples below for how to do |
---|
123 | this. |
---|
124 | .TP |
---|
125 | \fBarray statistics \fIarrayName\fR |
---|
126 | Returns statistics about the distribution of data within the hashtable |
---|
127 | that represents the array. This information includes the number of |
---|
128 | entries in the table, the number of buckets, and the utilization of |
---|
129 | the buckets. |
---|
130 | .TP |
---|
131 | \fBarray unset \fIarrayName\fR ?\fIpattern\fR? |
---|
132 | Unsets all of the elements in the array that match \fIpattern\fR (using the |
---|
133 | matching rules of \fBstring match\fR). If \fIarrayName\fR is not the name |
---|
134 | of an array variable or there are no matching elements in the array, no |
---|
135 | error will be raised. If \fIpattern\fR is omitted and \fIarrayName\fR is |
---|
136 | an array variable, then the command unsets the entire array. |
---|
137 | The command always returns an empty string. |
---|
138 | .SH EXAMPLES |
---|
139 | .CS |
---|
140 | \fBarray set\fR colorcount { |
---|
141 | red 1 |
---|
142 | green 5 |
---|
143 | blue 4 |
---|
144 | white 9 |
---|
145 | } |
---|
146 | |
---|
147 | foreach {color count} [\fBarray get\fR colorcount] { |
---|
148 | puts "Color: $color Count: $count" |
---|
149 | } |
---|
150 | \fB\(->\fR Color: blue Count: 4 |
---|
151 | Color: white Count: 9 |
---|
152 | Color: green Count: 5 |
---|
153 | Color: red Count: 1 |
---|
154 | |
---|
155 | foreach color [\fBarray names\fR colorcount] { |
---|
156 | puts "Color: $color Count: $colorcount($color)" |
---|
157 | } |
---|
158 | \fB\(->\fR Color: blue Count: 4 |
---|
159 | Color: white Count: 9 |
---|
160 | Color: green Count: 5 |
---|
161 | Color: red Count: 1 |
---|
162 | |
---|
163 | foreach color [lsort [\fBarray names\fR colorcount]] { |
---|
164 | puts "Color: $color Count: $colorcount($color)" |
---|
165 | } |
---|
166 | \fB\(->\fR Color: blue Count: 4 |
---|
167 | Color: green Count: 5 |
---|
168 | Color: red Count: 1 |
---|
169 | Color: white Count: 9 |
---|
170 | |
---|
171 | \fBarray statistics\fR colorcount |
---|
172 | \fB\(->\fR 4 entries in table, 4 buckets |
---|
173 | number of buckets with 0 entries: 1 |
---|
174 | number of buckets with 1 entries: 2 |
---|
175 | number of buckets with 2 entries: 1 |
---|
176 | number of buckets with 3 entries: 0 |
---|
177 | number of buckets with 4 entries: 0 |
---|
178 | number of buckets with 5 entries: 0 |
---|
179 | number of buckets with 6 entries: 0 |
---|
180 | number of buckets with 7 entries: 0 |
---|
181 | number of buckets with 8 entries: 0 |
---|
182 | number of buckets with 9 entries: 0 |
---|
183 | number of buckets with 10 or more entries: 0 |
---|
184 | average search distance for entry: 1.2 |
---|
185 | .CE |
---|
186 | .SH "SEE ALSO" |
---|
187 | list(n), string(n), variable(n), trace(n), foreach(n) |
---|
188 | .SH KEYWORDS |
---|
189 | array, element names, search |
---|