tcl7.6 User Commands - foreach






NAME

     foreach - Iterate over all elements in one or more lists


SYNOPSIS

     foreach varname list body
     foreach varlist1 list1 ?varlist2 list2 ...? body





DESCRIPTION

     The  foreach  command  implements  a  loop  where  the  loop
     variable(s)  take  on values from one or more lists.  In the
     simplest case there is one loop variable, varname,  and  one
     list,  list,  that is a list of values to assign to varname.
     The body argument is a Tcl script.  For each element of list
     (in  order from first to last), foreach assigns the contents
     of the element to varname as if the lindex command had  been
     used  to extract the element, then calls the Tcl interpreter
     to execute body.

     In the general case there can be more than  one  value  list
     (e.g.,  list1 and list2), and each value list can be associ-
     ated with a list of loop variables (e.g., varlist1 and  var-
     list2).   During each iteration of the loop the variables of
     each  varlist  are  assigned  consecutive  values  from  the
     corresponding  list.   Values in each list are used in order
     from first to last, and each value  is  used  exactly  once.
     The  total  number of loop iterations is large enough to use
     up all the values from all the value lists.  If a value list
     does  not contain enough elements for each of its loop vari-
     ables in each iteration, empty values are used for the miss-
     ing elements.

     The break and continue  statements  may  be  invoked  inside
     body,  with  the same effect as in the for command.  Foreach
     returns an empty string.


EXAMPLES

     The following loop uses i and j as loop variables to iterate
     over pairs of elements of a single list.

          set x {}
          foreach {i j} {a b c d e f} {
              lappend x $j $i
          }
          # The value of x is "b a d c f e"
          # There are 3 iterations of the loop.



     The next loop uses i and j to  iterate  over  two  lists  in
     parallel.

          set x {}
          foreach i {a b c} j {d e f g} {
              lappend x $i $j
          }
          # The value of x is "a d b e c f {} g"
          # There are 4 iterations of the loop.


     The two forms are combined in the following example.

          set x {}
          foreach i {a b c} {j k} {d e f g} {
              lappend x $i $j $k
          }
          # The value of x is "a d e b f g c {} {}"
          # There are 3 iterations of the loop.



KEYWORDS

     foreach, iteration, list, looping