summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex
blob: 9c3ef4832a8395be3b903b457f4d54b2c59e8604 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
% Copyright 2006 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 a further 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 a |\foreach| statement 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}

  \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=examplefill,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 / \diameter in {0 / 0 / 2mm, 1 / 1 / 3mm, 2 / 0 / 1mm}
    \draw (\x,\y) circle (\diameter);

  % Same effect
  \foreach \center/\diameter in {{(0,0)/2mm}, {(1,1)/3mm}, {(2,0)/1mm}}
    \draw[yshift=2.5cm] \center circle (\diameter);
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}[line cap=round,line width=3pt]
  \filldraw [fill=examplefill] (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 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}

\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}