1mNAME0m
       foreach - Iterate over all elements in one or more lists

1mSYNOPSIS0m
       1mforeach 4m22mvarname24m 4mlist24m 4mbody0m
       1mforeach 4m22mvarlist124m 4mlist124m ?4mvarlist224m 4mlist224m 4m...24m? 4mbody0m


1mDESCRIPTION0m
       The  1mforeach  22mcommand 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, 4mvarname24m, and one list, 4mlist24m, that is a list of values to
       assign to 4mvarname24m.  The 4mbody24m argument is a Tcl script.  For  each  ele-
       ment  of  4mlist24m  (in order from first to last), 1mforeach 22massigns the con-
       tents of the element to 4mvarname24m as if the 1mlindex 22mcommand had been  used
       to extract the element, then calls the Tcl interpreter to execute 4mbody24m.

       In the general case there can be more than one value list (e.g.,  4mlist10m
       and  4mlist224m),  and each value list can be associated with a list of loop
       variables (e.g., 4mvarlist124m and 4mvarlist224m).  During each iteration of  the
       loop the variables of each 4mvarlist24m are assigned consecutive values from
       the corresponding 4mlist24m.  Values in each 4mlist24m 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 variables in each iteration, empty values are used for
       the missing elements.

       The  1mbreak 22mand 1mcontinue 22mstatements may be invoked inside 4mbody24m, with the
       same effect as in the 1mfor 22mcommand.  1mForeach 22mreturns an empty string.

1mEXAMPLES0m
       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.



1mSEE ALSO0m
       for(n), while(n), break(n), continue(n)


1mKEYWORDS0m
