'''`[array] startsearch`''' starts an array search



** Synopsis **

'''`[array] startsearch`''' ''`arrayName`'' start



** Description **

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,


<<categories>> Category Command | Tcl syntax