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