1array(n) Tcl Built-In Commands array(n)
2______________________________________________________________________________
6
8 array - Manipulate array variables
9
11 array option arrayName ?arg arg ...?
12______________________________________________________________________________
13
15 This command performs one of several operations on the variable given
16 by arrayName. Unless otherwise specified for individual commands
17 below, arrayName must be the name of an existing array variable. The
18 option argument determines what action is carried out by the command.
19 The legal options (which may be abbreviated) are:
20 array anymore arrayName searchId
22 Returns 1 if there are any more elements left to be processed in
23 an array search, 0 if all elements have already been returned.
24 SearchId indicates which search on arrayName to check, and must
25 have been the return value from a previous invocation of array
26 startsearch. This option is particularly useful if an array has
27 an element with an empty name, since the return value from array
28 nextelement will not indicate whether the search has been com‐
29 pleted.
30 array donesearch arrayName searchId
32 This command terminates an array search and destroys all the
33 state associated with that search. SearchId indicates which
34 search on arrayName to destroy, and must have been the return
35 value from a previous invocation of array startsearch. Returns
36 an empty string.
37 array exists arrayName
39 Returns 1 if arrayName is an array variable, 0 if there is no
40 variable by that name or if it is a scalar variable.
41 array get arrayName ?pattern?
43 Returns a list containing pairs of elements. The first element
44 in each pair is the name of an element in arrayName and the sec‐
45 ond element of each pair is the value of the array element. The
46 order of the pairs is undefined. If pattern is not specified,
47 then all of the elements of the array are included in the
48 result. If pattern is specified, then only those elements whose
49 names match pattern (using the matching rules of string match)
50 are included. If arrayName is not the name of an array vari‐
51 able, or if the array contains no elements, then an empty list
52 is returned. If traces on the array modify the list of ele‐
53 ments, the elements returned are those that exist both before
54 and after the call to array get.
55 array names arrayName ?mode? ?pattern?
57 Returns a list containing the names of all of the elements in
58 the array that match pattern. Mode may be one of -exact, -glob,
59 or -regexp. If specified, mode designates which matching rules
60 to use to match pattern against the names of the elements in the
61 array. If not specified, mode defaults to -glob. See the docu‐
62 mentation for string match for information on glob style match‐
63 ing, and the documentation for regexp for information on regexp
64 matching. If pattern is omitted then the command returns all of
65 the element names in the array. If there are no (matching) ele‐
66 ments in the array, or if arrayName is not the name of an array
67 variable, then an empty string is returned.
68 array nextelement arrayName searchId
70 Returns the name of the next element in arrayName, or an empty
71 string if all elements of arrayName have already been returned
72 in this search. The searchId argument identifies the search,
73 and must have been the return value of an array startsearch com‐
74 mand. Warning: if elements are added to or deleted from the
75 array, then all searches are automatically terminated just as if
76 array donesearch had been invoked; this will cause array nex‐
77 telement operations to fail for those searches.
78 array set arrayName list
80 Sets the values of one or more elements in arrayName. list must
81 have a form like that returned by array get, consisting of an
82 even number of elements. Each odd-numbered element in list is
83 treated as an element name within arrayName, and the following
84 element in list is used as a new value for that array element.
85 If the variable arrayName does not already exist and list is
86 empty, arrayName is created with an empty array value.
87 array size arrayName
89 Returns a decimal string giving the number of elements in the
90 array. If arrayName is not the name of an array then 0 is
91 returned.
92 array startsearch arrayName
94 This command initializes an element-by-element search through
95 the array given by arrayName, such that invocations of the array
96 nextelement command will return the names of the individual ele‐
97 ments in the array. When the search has been completed, the
98 array donesearch command should be invoked. The return value is
99 a search identifier that must be used in array nextelement and
100 array donesearch commands; it allows multiple searches to be
101 underway simultaneously for the same array. It is currently
102 more efficient and easier to use either the array get or array
103 names, together with foreach, to iterate over all but very large
104 arrays. See the examples below for how to do this.
105 array statistics arrayName
107 Returns statistics about the distribution of data within the
108 hashtable that represents the array. This information includes
109 the number of entries in the table, the number of buckets, and
110 the utilization of the buckets.
111 array unset arrayName ?pattern?
113 Unsets all of the elements in the array that match pattern
114 (using the matching rules of string match). If arrayName is not
115 the name of an array variable or there are no matching elements
116 in the array, no error will be raised. If pattern is omitted
117 and arrayName is an array variable, then the command unsets the
118 entire array. The command always returns an empty string.
119
121 array set colorcount {
122 red 1
123 green 5
124 blue 4
125 white 9
126 }
127 foreach {color count} [array get colorcount] {
129 puts "Color: $color Count: $count"
130 }
131 → Color: blue Count: 4
132 Color: white Count: 9
133 Color: green Count: 5
134 Color: red Count: 1
135 foreach color [array names colorcount] {
137 puts "Color: $color Count: $colorcount($color)"
138 }
139 → Color: blue Count: 4
140 Color: white Count: 9
141 Color: green Count: 5
142 Color: red Count: 1
143 foreach color [lsort [array names colorcount]] {
145 puts "Color: $color Count: $colorcount($color)"
146 }
147 → Color: blue Count: 4
148 Color: green Count: 5
149 Color: red Count: 1
150 Color: white Count: 9
151 array statistics colorcount
153 → 4 entries in table, 4 buckets
154 number of buckets with 0 entries: 1
155 number of buckets with 1 entries: 2
156 number of buckets with 2 entries: 1
157 number of buckets with 3 entries: 0
158 number of buckets with 4 entries: 0
159 number of buckets with 5 entries: 0
160 number of buckets with 6 entries: 0
161 number of buckets with 7 entries: 0
162 number of buckets with 8 entries: 0
163 number of buckets with 9 entries: 0
164 number of buckets with 10 or more entries: 0
165 average search distance for entry: 1.2
166
168 list(n), string(n), variable(n), trace(n), foreach(n)
169
171 array, element names, search
172Tcl 8.3 array(n)