diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-pgffor.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-pgffor.tex | 418 |
1 files changed, 418 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-pgffor.tex b/graphics/pgf/base/doc/pgfmanual-en-pgffor.tex new file mode 100644 index 0000000000..94a41fbfe2 --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-pgffor.tex @@ -0,0 +1,418 @@ +% Copyright 2019 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Repeating Things: The Foreach Statement} +\label{section-foreach} + +This section describes the package |pgffor|, which is loaded automatically by +\tikzname, but not by \pgfname: + +\begin{package}{pgffor} + This package can be used independently of \pgfname, but works particularly + well together with \pgfname\ and \tikzname. It defines two new commands: + |\foreach| and |\breakforeach|. +\end{package} + +\begin{command}{\foreach| |\meta{variables}| |\opt{{\ttfamily[}\meta{options}{\ttfamily]}}| in |\meta{list} \meta{commands}} + The syntax of this command is a bit complicated, so let us go through it + step-by-step. + + In the easiest case, \meta{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, \meta{options} will be omitted. The keys for + customizing this command will be discussed below. + + Again, in the easiest case, \meta{list} is either a comma-separated list of + values surrounded by curly braces or it is the name of a macro that contain + such a list of values. Anything can be used as a value, but numbers are + most likely. + + Finally, in the easiest case, \meta{commands} is some \TeX-text in curly + braces. + + With all these assumptions, the |\foreach| statement will execute the + \meta{commands} repeatedly, once for every element of the \meta{list}. Each + time the \meta{commands} are executed, the \meta{variable} will be set to + the current value of the list item. + % +\begin{codeexample}[] +\foreach \x in {1,2,3,0} {[\x]} +\end{codeexample} + +\begin{codeexample}[] +\def\mylist{1,2,3,0} +\foreach \x in \mylist {[\x]} +\end{codeexample} + + Note that in each execution of \meta{commands} the \meta{commands} are put + in a \TeX\ group. This means that \emph{local changes to counters inside + \meta{commands} do not persist till the next iteration}. For instance, if + you add 1 to a counter inside \meta{commands} locally, then in the next + iteration the counter will have the same value it had at the beginning of + the first iteration. You have to add |\global| if you wish changes to + persist from iteration to iteration. + + + \medskip + \textbf{Syntax for the commands.} + Let us move on to a more complicated setting. The first complication occurs + when the \meta{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 \meta{commands}. + This is most useful in situations like the following: + % +\begin{codeexample}[] +\tikz + \foreach \x in {0,1,2,3} + \draw (\x,0) circle (0.2cm); +\end{codeexample} + + 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 + \meta{commands}. This allows you to write the following: + % +\begin{codeexample}[] +\begin{tikzpicture} + \foreach \x in {0,1,2,3} + \foreach \y in {0,1,2,3} + { + \draw (\x,\y) circle (0.2cm); + \fill (\x,\y) circle (0.1cm); + } +\end{tikzpicture} +\end{codeexample} + + \medskip + \textbf{The dots notation.} + The second complication concerns the \meta{list}. If this \meta{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 \emph{two} list items before it, which where numbers. Examples of + \emph{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$, \dots, $x+md$'', where the last + dots are semantic dots, not syntactic dots. The value $m$ is the largest + number such that $x + md \le z$ if $d$ is positive or such that $x+md \ge + z$ if $d$ is negative. + + Perhaps it is best to explain this by some examples: The following + \meta{list} have the same effects: + + |\foreach \x in {1,2,...,6} {\x, }| yields \foreach \x in {1,2,...,6} {\x, } + + |\foreach \x in {1,2,3,...,6} {\x, }| yields \foreach \x in {1,2,3,...,6} {\x, } + + |\foreach \x in {1,3,...,11} {\x, }| yields \foreach \x in {1,3,...,11} {\x, } + + |\foreach \x in {1,3,...,10} {\x, }| yields \foreach \x in {1,3,...,10} {\x, } + + |\foreach \x in {0,0.1,...,0.5} {\x, }| yields \foreach \x in {0,0.1,...,0.5} {\x, } + + |\foreach \x in {a,b,9,8,...,1,2,2.125,...,2.5} {\x, }| yields \foreach \x in {a,b,9,8,...,1,2,2.125,...,2.5} {\x, } + + 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 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 \foreach \x in {1,...,6} {\x, } + + |\foreach \x in {9,...,3.5} {\x, }| yields \foreach \x in {9,...,3.5} {\x, } + + There is a yet another special case for the |...| statement, in that it can + indicate an alphabetic character sequence: + + |\foreach \x in {a,...,m} {\x, }| yields \foreach \x in {a,...,m} {\x, } + + |\foreach \x in {Z,X,...,M} {\x, }| yields \foreach \x in {Z,X,...,M} {\x, } + + A final special case for the |...| statement is contextual replacement. If + the |...| is used in some context, for example, |sin(...)|, this context + will be interpreted correctly, provided that the list items prior to the + |...| statement have \emph{exactly} the same pattern, except that, instead + of dots, they have a number or a character: + + |\foreach \x in {2^1,2^...,2^7} {$\x$, }| yields \foreach \x in {2^1,2^...,2^7} {$\x$, } + + |\foreach \x in {0\pi,0.5\pi,...\pi,3\pi} {$\x$, }| yields \foreach \x in {0\pi,0.5\pi,...\pi,3\pi} {$\x$, } + + |\foreach \x in {A_1,..._1,H_1} {$\x$, }| yields \foreach \x in {A_1,..._1,H_1} {$\x$, } + + + \textbf{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: + % +\begin{codeexample}[] +\tikz + \foreach \position in {(0,0), (1,1), (2,0), (3,1)} + \draw \position rectangle +(.25,.5); +\end{codeexample} + + + \medskip + \textbf{Using the foreach-statement inside paths.} + \tikzname\ allows you to use |foreach| and |\foreach| (both have the same + effect) inside a path construction. In such a case, the \meta{commands} + must be path construction commands. Here are two examples: + % +\begin{codeexample}[] +\tikz + \draw (0,0) + foreach \x in {1,...,3} + { -- (\x,1) -- (\x,0) } + ; +\end{codeexample} + +\begin{codeexample}[] +\tikz \draw foreach \p in {1,...,3} {(\p,1)--(\p,3) (1,\p)--(3,\p)}; +\end{codeexample} + + Note that the |node| and |pic| path commands also support the |foreach| + statement in special ways. + + + \medskip + \textbf{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 \meta{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 \meta{variables} and the list items are lists of values, + each time the \meta{commands} are executed, each of the variables in + \meta{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 + \foreach \x / \y in {1/2,a/b} {``\x\ and \y''}. + + If some entry in the \meta{list} does not have ``enough'' slashes, the last + entry will be repeated. Here is an example: + % +\begin{codeexample}[] +\begin{tikzpicture} + \foreach \x/\xtext in {0,...,3,2.72 / e} + \draw (\x,0) node{$\xtext$}; +\end{tikzpicture} +\end{codeexample} + + Here are more useful examples: + % +\begin{codeexample}[] +\begin{tikzpicture} + % Define some coordinates: + \path[nodes={circle,fill=yellow!80!black,draw}] + (0,0) node(a) {a} + (2,0.55) node(b) {b} + (1,1.5) node(c) {c} + (2,1.75) node(d) {d}; + + % Draw some connections: + \foreach \source/\target in {a/b, b/c, c/a, c/d} + \draw (\source) .. controls +(.75cm,0pt) and +(-.75cm,0pt)..(\target); +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + % Let's draw circles at interesting points: + \foreach \x / \y / \r in {0 / 0 / 2mm, 1 / 1 / 3mm, 2 / 0 / 1mm} + \draw (\x,\y) circle (\r); + + % Same effect + \foreach \center/\r in {{(0,0)/2mm}, {(1,1)/3mm}, {(2,0)/1mm}} + \draw[yshift=2.5cm] \center circle (\r); +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture}[line cap=round,line width=3pt] + \filldraw [fill=yellow!80!black] (0,0) circle (2cm); + + \foreach \angle / \label in + {0/3, 30/2, 60/1, 90/12, 120/11, 150/10, 180/9, + 210/8, 240/7, 270/6, 300/5, 330/4} + { + \draw[line width=1pt] (\angle:1.8cm) -- (\angle:2cm); + \draw (\angle:1.4cm) node{\textsf{\label}}; + } + + \foreach \angle in {0,90,180,270} + \draw[line width=2pt] (\angle:1.6cm) -- (\angle:2cm); + + \draw (0,0) -- (120:0.8cm); % hour + \draw (0,0) -- (90:1cm); % minute +\end{tikzpicture}% +\end{codeexample} + +\begin{codeexample}[] +\tikz[shading=ball] + \foreach \x / \cola in {0/red,1/green,2/blue,3/yellow} + \foreach \y / \colb in {0/red,1/green,2/blue,3/yellow} + \shade[ball color=\cola!50!\colb] (\x,\y) circle (0.4cm); +\end{codeexample} + + + \medskip + \textbf{Options to customize the foreach-statement.} + + The keys described below can be used in the \meta{options} argument to the + |\foreach| command. They all have the path |/pgf/foreach/|, however, the + path is set automatically when \meta{options} are parsed, so it does not + have to be explicitly stated. + + \begin{key}{/pgf/foreach/var=\meta{variable}} + This key provides an alternative way to specify variables: + |\foreach [var=\x,var=\y]| is the same as |\foreach \x/\y|. If used, + this key should be used before the other keys. + \end{key} + + \begin{key}{/pgf/foreach/evaluate=\meta{variable}| |\opt{|as |\meta{macro}| using |\meta{formula}}} + By default, list items are not evaluated: |1+2|, yields |1+2|, not |3|. + This key allows a variable to be evaluated using the mathematical + engine. The variable must have been specified either using the |var| + key or in the \meta{variables} argument of the |foreach| command. By + default, the result of the evaluation will be stored in + \meta{variable}. However, the optional |as |\meta{macro} statement can + be used to store the result in \meta{macro}. + % +\begin{codeexample}[] +\foreach \x [evaluate=\x] in {2^0,2^...,2^8}{$\x$, } +\end{codeexample} + +\begin{codeexample}[] +\foreach \x [evaluate=\x as \xeval] in {2^0,2^...,2^8}{$\x=\xeval$, } +\end{codeexample} + + The optional |using |\meta{formula} statement means an evaluation does + not have to be explicitly stated for each item in \meta{list}. The + \meta{formula} should contain at least one reference to + \meta{variable}. + % +\begin{codeexample}[] +\tikz\foreach \x [evaluate=\x as \shade using \x*10] in {0,1,...,10} + \node [fill=red!\shade!yellow, minimum size=0.65cm] at (\x,0) {\x}; +\end{codeexample} + % + \end{key} + + \begin{key}{/pgf/foreach/remember=\meta{variable}| as |\meta{macro}| |\opt{|(initially |\meta{value}|)|}} + This key allows the item value stored in \meta{variable} to be + remembered during the next iteration, stored in \meta{macro}. If a + variable is evaluated, the result of this evaluation is remembered. By + default the value of \meta{variable} is zero for the first iteration, + however, the optional |(initially |\meta{value}|)| statement, allows + the \meta{macro} to be initially defined as \meta{value}. + % +\begin{codeexample}[] +\foreach \x [remember=\x as \lastx (initially A)] in {B,...,H}{$\overrightarrow{\lastx\x}$, } +\end{codeexample} + % + \end{key} + + \begin{key}{/pgf/foreach/count=\meta{macro}| |\opt{|from |\meta{value}}} + This key allows \meta{macro} to hold the position in the list of the + current item. The optional |from |\meta{value} statement allows the + counting to begin from \meta{value}. + % +\begin{codeexample}[] +\tikz[x=0.75cm,y=0.75cm] + \foreach \x [count=\xi] in {a,...,e} + \foreach \y [count=\yi] in {\x,...,e} + \node [draw, top color=white, bottom color=blue!50, minimum size=0.666cm] + at (\xi,-\yi) {$\mathstrut\x\y$}; +\end{codeexample} + % + \end{key} + + \begin{key}{/pgf/foreach/parse=\marg{boolean} (default false)} + If this key is set to true the upper bound in the loop will be + fed into |\pgfmathparse|. This allows to use complex expressions as + the upper bound. However, the expression must be safe for evaluation + in |\pgfmathparse|. It is known that internal \TeX\ registers can + cause trouble. + % +\begin{codeexample}[] +\foreach \x [parse=true] in {1,...,1.0e+1 - 1}{ \x } +\end{codeexample} + % + \end{key} + + \begin{key}{/pgf/foreach/expand list=\marg{boolean} (default false)} + If this key is set to true the contents of the list are fully expanded + with |\edef| before further processing. This allows using complex + macros which generate a list upon expansion without having to use an + intermediate macro. + % +\begin{codeexample}[] +\def\Iota#1#2{% + \ifnum\numexpr#1\relax<\numexpr#2\relax + \the\numexpr#1\relax,% + \expandafter\Iota\expandafter{\the\numexpr(#1)+1\relax}{#2}% + \else + \the\numexpr#2\relax + \fi} +\foreach [expand list=true] \x in {\Iota{1}{5}} { + \x +} +\end{codeexample} + % + \end{key} +\end{command} + +\begin{command}{\breakforeach} + If this command is given inside a |\foreach| command, no further executions + of the \meta{commands} will occur. However, the current execution of the + \meta{commands} is continued normally, so it is probably best to use this + command only at the end of a |\foreach| command. + % +\begin{codeexample}[] +\begin{tikzpicture} + \foreach \x in {1,...,4} + \foreach \y in {1,...,4} + { + \fill[red!50] (\x,\y) ellipse (3pt and 6pt); + + \ifnum \x<\y + \breakforeach + \fi + } +\end{tikzpicture} +\end{codeexample} + % +\end{command} |