Updated 2015-03-06 22:19:13 by AMG

array startsearch arrayName

This command initializes an element-by-element search through the array given by arrayName, such that invocations of the array nextelement command will return the names of the individual elements in the array. When the search has been completed, the array donesearch command should be invoked. The return value is a search identifier that must be used in array nextelement and array donesearch commands; it allows multiple searches to be underway simultaneously for the same array.

This command should be considered to be deprecated. It is still supported in 8.6, but will probably be culled in 9.0.

Note that this may not work correctly with the special env array.

example of use of array startsearch, nextelement:
array set test {0 a 1 b 2 c 3 d 4 f} ;# create an array.
array get test ;# prints the array to show it is in random order

set srch [array startsearch test]
while {[array anymore test $srch]} {
   set key [array nextelement test $srch]
   puts "test($key) = $test($key)"
array donesearch test $srch ;# releases temporary memory associated with the search

The "array get test" returns:
4 f 0 a 1 b 2 c 3 d

The loop prints:
test(4) = f
test(0) = a
test(1) = b
test(2) = c
test(3) = d

NB using
while {[set key [array nextelement test $srch]] ne ""} {...}

is bad since IF the array contains a key "" the test will terminate early. Which it can.

See also edit