In this section the package pgffor.sty is described. It can be used independently of PGF, but it works particularly well together with PGF and TikZ.
When you say \usepackage{pgffor}, two commands are defined: \foreach and \breakforeach. Their behaviour is described in the following:
The syntax of this command is a bit complicated, so let us go through it step-by-step.
In the easiest case, <variables> is a single TEX-command like \x or \point. (If you want to have some fun, you can also use active characters. If you do not know what active characters are, you are blessed.)
Still in the easiest case, <list> is a comma-separated list of values. Anything can be used as a value, but numbers are most likely.
Finally, in the easiest case, <commands> is some TEX-text in curly braces.
With all these assumptions, the \foreach statement will execute the <commands> repeatedly, once for every element of the <list>. Each time the <commands> are executed, the <variable> will be set to the current value of the list item.
| [1][2][3][0] |
|
Syntax for the commands. Let use move on to a more complicated setting. The first complication occurs when the <commands> are not some text in curly braces. If the \foreach statement does not encounter an opening brace, it will instead scan everything up to the next semicolon and use this as <commands>. This is most useful in situations like the following:
|
However, the “reading till the next semicolon” is not the whole truth. There is another rule: If a \foreach statement is directly followed by another \foreach statement, this second foreach statement is collected as <commands>. This allows you to write the following:
|
The dots notation. The second complication concerns the <list>. If this <list> contains the list item “...”, this list item is replaced by the “missing values.” More precisely, the following happens:
Normally, when a list item ... is encountered, there should already have been two list items before it, which where numbers. Examples of numbers are 1, -10, or -0.24. Let us call these numbers x and y and let d := y -x be their difference. Next, there should also be one number following the three dots, let us call this number z.
In this situation, the part of the list reading “x,y,...,z” is replaced by “x, x + d, x + 2d, x + 3d, ..., x + md,” where the last dots are semantic dots, not syntactic dots. The value m is the largest number such that x + md < z if d is positive or such that x + md > z if d is negative.
Perhaps it is best to explain this by some examples: The following <list> have the same effects:
\foreach \x in {1,2,...,6} {\x, } yields 1, 2, 3, 4, 5, 6,
\foreach \x in {1,2,3,...,6} {\x, } yields 1, 2, 3, 4, 5, 6,
\foreach \x in {1,3,...,11} {\x, } yields 1, 3, 5, 7, 9, 11,
\foreach \x in {1,3,...,10} {\x, } yields 1, 3, 5, 7, 9,
\foreach \x in {0,0.1,...,0.5} {\x, } yields 0, 0.1, 0.20001, 0.30002, 0.40002,
\foreach \x in {a,b,9,8,...,1,2,2.125,...,2.5} {\x, } yields a, b, 9, 8, 7, 6, 5, 4, 3, 2, 1, 2, 2.125, 2.25, 2.375, 2.5,
As can be seen, for fractional steps that are not multiples of 2-n for some small n, rounding errors can occur pretty easily. Thus, in the second last case, 0.5 should probably be replaced by 0.501 for robustness.
There is yet another special case for the ... statement: If the ... is used right after the first item in the list, that is, if there is an x, but no y, the difference d obviously cannot be computed and is set to 1 if the number z following the dots is larger than x and is set to -1 if z is smaller:
\foreach \x in {1,...,6} {\x, } yields 1, 2, 3, 4, 5, 6,
\foreach \x in {9,...,3.5} {\x, } yields 9, 8, 7, 6, 5, 4,
Special handling of pairs. Different list items are separated by commas. However, this causes a problem when the list items contain commas themselves as pairs like (0,1) do. In this case, you should put the items containing commas in braces as in {(0,1)}. However, since pairs are such a natural and useful case, they get a special treatment by the \foreach statement. When a list item starts with a ( everything up to the next ) is made part of the item. Thus, we can write things like the following:
|
Using the foreach-statement inside paths. TikZ allows you to use a \foreach statement inside a path construction. In such a case, the <commands> must be path construction commands. Here are two examples:
|
|
Multiple variables. You will often wish to iterate over two variables at the same time. Since you can nest \foreach loops, this is normally straight-forward. However, you sometimes wish variables to iterate “simultaneously.” For example, we might be given a list of edges that connect two coordinates and might wish to iterate over these edges. While doing so, we would like the source and target of the edges to be set to two different variables.
To achieve this, you can use the following syntax: The <variables> may not only be a single TEX-variable. Instead, it can also be a list of variables separated by slashes (/). In this case the list items can also be lists of values separated by slashes.
Assuming that the <variables> and the list items are lists of values, each time the <commands> are executed, each of the variables in <variables> is set to one part of the list making up the current list item. Here is an example to clarify this:
Example: \foreach \x / \y in {1/2,a/b} {``\x\ and \y''} yields “1 and 2”“a and b”.
If some entry in the <list> does not have “enough” slashes, the last entry will be repeated. Here is an example:
|
Here are more useful examples:
|
|
|
|
If this command is given inside a \foreach command, no further executions of the <commands> will occur. However, the current execution of the <commands> is continued normally, so it is probably best to use this command only at the end of a \foreach command.
|