diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex | 447 |
1 files changed, 219 insertions, 228 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex index 770f0c89dc3..a8ddbd9194a 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex @@ -11,42 +11,40 @@ \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: +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|. + 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{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} @@ -56,36 +54,34 @@ automatically by \tikzname, but not by \pgfname: \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: - + 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: - + 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} @@ -97,99 +93,96 @@ automatically by \tikzname, but not by \pgfname: \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: + \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: + \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) @@ -202,35 +195,35 @@ automatically by \tikzname, but not by \pgfname: \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: + 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} @@ -238,7 +231,8 @@ automatically by \tikzname, but not by \pgfname: \end{tikzpicture} \end{codeexample} - Here are more useful examples: + Here are more useful examples: + % \begin{codeexample}[] \begin{tikzpicture} % Define some coordinates: @@ -293,30 +287,30 @@ automatically by \tikzname, but not by \pgfname: \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}. + \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} @@ -325,38 +319,37 @@ automatically by \tikzname, but not by \pgfname: \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}. - + 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}. - + % + \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}. - + % + \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} @@ -364,18 +357,16 @@ automatically by \tikzname, but not by \pgfname: \node [draw, top color=white, bottom color=blue!50, minimum size=0.666cm] at (\xi,-\yi) {$\mathstrut\x\y$}; \end{codeexample} -\end{key} - + % + \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. - + 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} @@ -389,5 +380,5 @@ automatically by \tikzname, but not by \pgfname: } \end{tikzpicture} \end{codeexample} - + % \end{command} |