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