array startsearch starts an array search

Synopsis  edit

array startsearch arrayName start

Description  edit

This command initializes an variable-by-variable search through the array given by arrayName and returns an identifier for the search. array nextelement and array donesearch commands; it allows multiple searches to be underway simultaneously for the same array. Each call to array nextelement returns the names of the the next matching variable in the array. When the search has been completed, call array donesearch to finalize the search.

Array searches may not work correctly with the special env array.

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

---

Example: array startsearch and array 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 name [array nextelement test $srch]
   puts "test($name) = $test($name)"
}
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 name [array nextelement test $srch]] ne {}} {...}

would cause the test to terminate if the empty string is the name of a variable in the array,

---