[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
| 3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
| 4 | '\" |
---|
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 7 | '\" |
---|
| 8 | '\" RCS: @(#) $Id: foreach.n,v 1.10 2007/12/13 15:22:32 dgp Exp $ |
---|
| 9 | '\" |
---|
| 10 | .so man.macros |
---|
| 11 | .TH foreach n "" Tcl "Tcl Built-In Commands" |
---|
| 12 | .BS |
---|
| 13 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
| 14 | .SH NAME |
---|
| 15 | foreach \- Iterate over all elements in one or more lists |
---|
| 16 | .SH SYNOPSIS |
---|
| 17 | \fBforeach \fIvarname list body\fR |
---|
| 18 | .br |
---|
| 19 | \fBforeach \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR |
---|
| 20 | .BE |
---|
| 21 | |
---|
| 22 | .SH DESCRIPTION |
---|
| 23 | .PP |
---|
| 24 | The \fBforeach\fR command implements a loop where the loop |
---|
| 25 | variable(s) take on values from one or more lists. |
---|
| 26 | In the simplest case there is one loop variable, \fIvarname\fR, |
---|
| 27 | and one list, \fIlist\fR, that is a list of values to assign to \fIvarname\fR. |
---|
| 28 | The \fIbody\fR argument is a Tcl script. |
---|
| 29 | For each element of \fIlist\fR (in order |
---|
| 30 | from first to last), \fBforeach\fR assigns the contents of the |
---|
| 31 | element to \fIvarname\fR as if the \fBlindex\fR command had been used |
---|
| 32 | to extract the element, then calls the Tcl interpreter to execute |
---|
| 33 | \fIbody\fR. |
---|
| 34 | .PP |
---|
| 35 | In the general case there can be more than one value list |
---|
| 36 | (e.g., \fIlist1\fR and \fIlist2\fR), |
---|
| 37 | and each value list can be associated with a list of loop variables |
---|
| 38 | (e.g., \fIvarlist1\fR and \fIvarlist2\fR). |
---|
| 39 | During each iteration of the loop |
---|
| 40 | the variables of each \fIvarlist\fR are assigned |
---|
| 41 | consecutive values from the corresponding \fIlist\fR. |
---|
| 42 | Values in each \fIlist\fR are used in order from first to last, |
---|
| 43 | and each value is used exactly once. |
---|
| 44 | The total number of loop iterations is large enough to use |
---|
| 45 | up all the values from all the value lists. |
---|
| 46 | If a value list does not contain enough |
---|
| 47 | elements for each of its loop variables in each iteration, |
---|
| 48 | empty values are used for the missing elements. |
---|
| 49 | .PP |
---|
| 50 | The \fBbreak\fR and \fBcontinue\fR statements may be |
---|
| 51 | invoked inside \fIbody\fR, with the same effect as in the \fBfor\fR |
---|
| 52 | command. \fBForeach\fR returns an empty string. |
---|
| 53 | .SH EXAMPLES |
---|
| 54 | This loop prints every value in a list together with the square and |
---|
| 55 | cube of the value: |
---|
| 56 | .CS |
---|
| 57 | '\" Maintainers: notice the tab hacking below! |
---|
| 58 | .ta 3i |
---|
| 59 | set values {1 3 5 7 2 4 6 8} ;# Odd numbers first, for fun! |
---|
| 60 | puts "Value\etSquare\etCube" ;# Neat-looking header |
---|
| 61 | \fBforeach\fR x $values { ;# Now loop and print... |
---|
| 62 | puts " $x\et [expr {$x**2}]\et [expr {$x**3}]" |
---|
| 63 | } |
---|
| 64 | .CE |
---|
| 65 | .PP |
---|
| 66 | The following loop uses i and j as loop variables to iterate over |
---|
| 67 | pairs of elements of a single list. |
---|
| 68 | .CS |
---|
| 69 | set x {} |
---|
| 70 | \fBforeach\fR {i j} {a b c d e f} { |
---|
| 71 | lappend x $j $i |
---|
| 72 | } |
---|
| 73 | # The value of x is "b a d c f e" |
---|
| 74 | # There are 3 iterations of the loop. |
---|
| 75 | .CE |
---|
| 76 | .PP |
---|
| 77 | The next loop uses i and j to iterate over two lists in parallel. |
---|
| 78 | .CS |
---|
| 79 | set x {} |
---|
| 80 | \fBforeach\fR i {a b c} j {d e f g} { |
---|
| 81 | lappend x $i $j |
---|
| 82 | } |
---|
| 83 | # The value of x is "a d b e c f {} g" |
---|
| 84 | # There are 4 iterations of the loop. |
---|
| 85 | .CE |
---|
| 86 | .PP |
---|
| 87 | The two forms are combined in the following example. |
---|
| 88 | .CS |
---|
| 89 | set x {} |
---|
| 90 | \fBforeach\fR i {a b c} {j k} {d e f g} { |
---|
| 91 | lappend x $i $j $k |
---|
| 92 | } |
---|
| 93 | # The value of x is "a d e b f g c {} {}" |
---|
| 94 | # There are 3 iterations of the loop. |
---|
| 95 | .CE |
---|
| 96 | |
---|
| 97 | .SH "SEE ALSO" |
---|
| 98 | for(n), while(n), break(n), continue(n) |
---|
| 99 | |
---|
| 100 | .SH KEYWORDS |
---|
| 101 | foreach, iteration, list, looping |
---|