Previous section   Next section

Practical Programming in Tcl & Tk, Third Edition
By Brent B. Welch

Table of Contents
Chapter 8.  Tcl Arrays

The array Command

The array command returns information about array variables. The array names command returns the index names that are defined in the array. If the array variable is not defined, then array names just returns an empty list. It allows easy iteration through an array with a foreach loop:

foreach index [array names arr pattern] {
    # use arr($index)

The order of the names returned by array names is arbitrary. It is essentially determined by the hash table implementation of the array. You can limit what names are returned by specifying a pattern that matches indices. The pattern is the kind supported by the string match command, which is described on page 48.

It is also possible to iterate through the elements of an array one at a time using the search-related commands listed in Table 8-1. The ordering is also random, and I find the foreach over the results of array names much more convenient. If your array has an extremely large number of elements, or if you need to manage an iteration over a long period of time, then the array search operations might be more appropriate. Frankly, I never use them. Table 8-1 summarizes the array command:

Table 8-1. The array command.
array exists arrReturns 1 if arr is an array variable.
array get arr ?pattern?Returns a list that alternates between an index and the corresponding array value. pattern selects matching indices. If not specified, all indices and values are returned.
array names arr ?pattern?Returns the list of all indices defined for arr, or those that match the string match pattern.
array set arr listInitializes the array arr from list, which has the same form as the list returned by array get.
array size arrReturns the number of indices defined for arr.
array startsearch arrReturns a search token for a search through arr.
array nextelement arr idReturns the value of the next element in array in the search identified by the token id. Returns an empty string if no more elements remain in the search.
array anymore arr idReturns 1 if more elements remain in the search.
array donesearch arr idEnds the search identified by id.

Converting Between Arrays and Lists

The array get and array set operations are used to convert between an array and a list. The list returned by array get has an even number of elements. The first element is an index, and the next is the corresponding array value. The list elements continue to alternate between index and value. The list argument to array set must have the same structure.

array set fruit {
   best   kiwi
   worst  peach
   ok     banana
array get fruit
=> ok banana best kiwi worst peach

Another way to loop through the contents of an array is to use array get and the two-variable form of the foreach command.

foreach {key value}[array get fruit] {
   # key is ok, best, or worst
   # value is some fruit

Passing Arrays by Name

The upvar command works on arrays. You can pass an array name to a procedure and use the upvar command to get an indirect reference to the array variable in the caller's scope. This is illustrated in Example 8-4, which inverts an array. As with array names, you can specify a pattern to array get to limit what part of the array is returned. This example uses upvar because the array names are passed into the ArrayInvert procedure. The inverse array does not need to exist before you call ArrayInvert.

Example 8-4 ArrayInvert inverts an array.
proc ArrayInvert {arrName inverseName {pattern *}} {
   upvar $arrName array $inverseName inverse
   foreach {index value}[array get array $pattern] {
      set inverse($value) $index

      Previous section   Next section