71 lines
3.4 KiB
HTML
71 lines
3.4 KiB
HTML
<HTML><HEAD><TITLE>Built-In Commands - foreach manual page</TITLE></HEAD><BODY>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
foreach - Iterate over all elements in one or more lists
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>foreach </B><I>varname list body</I><BR>
|
|
<B>foreach </B><I>varlist1 list1</I> ?<I>varlist2 list2 ...</I>? <I>body</I><BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
The <B>foreach</B> 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, <I>varname</I>,
|
|
and one list, <I>list</I>, that is a list of values to assign to <I>varname</I>.
|
|
The <I>body</I> argument is a Tcl script.
|
|
For each element of <I>list</I> (in order
|
|
from first to last), <B>foreach</B> assigns the contents of the
|
|
element to <I>varname</I> as if the <B><A HREF="../TkCmd/lindex.htm">lindex</A></B> command had been used
|
|
to extract the element, then calls the Tcl interpreter to execute
|
|
<I>body</I>.
|
|
<P>
|
|
In the general case there can be more than one value list
|
|
(e.g., <I>list1</I> and <I>list2</I>),
|
|
and each value list can be associated with a list of loop variables
|
|
(e.g., <I>varlist1</I> and <I>varlist2</I>).
|
|
During each iteration of the loop
|
|
the variables of each <I>varlist</I> are assigned
|
|
consecutive values from the corresponding <I>list</I>.
|
|
Values in each <I>list</I> 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.
|
|
<P>
|
|
The <B><A HREF="../TkCmd/break.htm">break</A></B> and <B><A HREF="../TkCmd/continue.htm">continue</A></B> statements may be
|
|
invoked inside <I>body</I>, with the same effect as in the <B><A HREF="../TkCmd/for.htm">for</A></B>
|
|
command. <B>Foreach</B> returns an empty string.
|
|
<H3><A NAME="M5">EXAMPLES</A></H3>
|
|
The following loop uses i and j as loop variables to iterate over
|
|
pairs of elements of a single list.
|
|
<PRE>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.</PRE>
|
|
<P>
|
|
The next loop uses i and j to iterate over two lists in parallel.
|
|
<PRE>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.</PRE>
|
|
<P>
|
|
The two forms are combined in the following example.
|
|
<PRE>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.</PRE>
|
|
<H3><A NAME="M6">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/for.htm">for</A></B>, <B><A HREF="../TkCmd/while.htm">while</A></B>, <B><A HREF="../TkCmd/break.htm">break</A></B>, <B><A HREF="../TkCmd/continue.htm">continue</A></B>
|
|
<H3><A NAME="M7">KEYWORDS</A></H3>
|
|
<A href="../Keywords/F.htm#foreach">foreach</A>, <A href="../Keywords/I.htm#iteration">iteration</A>, <A href="../Keywords/L.htm#list">list</A>, <A href="../Keywords/L.htm#looping">looping</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|