% !TeX spellcheck = en_US
% !TeX root = tikz-ext-manual.tex
% Copyright 2022 by Qrrbrbirlbel
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%

\begin{tikzlibrary}{misc}
  This library adds miscelleaneos utilities to PGFmath, PGF or \tikzname.
\end{tikzlibrary}

\section{PGFmath}

\subsection{Postfix operator \texttt{R}}

Similar to |\segments[<num>]| in PSTricks, the postfix operator |R| allows the user
to use an arbitrary number of segments of a circle to be used instead of an angle.

\begin{key}{/tikz/full arc=\meta{num} (default |{}|)}
  The number \meta{num} of segments will be set up.
  Using |full arc| with an empty value disables the segmentation and |1R| equals $1^\circ$.
  
  The given value \meta{num} is evaluated when the key is used and doesn't change when
  \meta{num} contains variables that change.
\end{key}
The |R| operator can then be used.
\begin{math-operator}{R}{postfix}{fullarc}
  Multiplies \mvar{x} with $\frac{360}{\meta{num}}$.
\end{math-operator}

\subsection{Functions}

\begin{math-function}{strrepeat("\mvar{Text}", \mvar{x})}
\mathcommand
  Returns a string with \mvar{Text} repeated \mvar{x} times.

\begin{codeexample}[]
\pgfmathparse{strrepeat("foo", 5)} \pgfmathresult
\end{codeexample}
\end{math-function}

\begin{math-function}{isInString("\mvar{String}", "\mvar{Text}")}
\mathcommand
  Returns |1| (true) if \mvar{Text} contains \mvar{String},
  otherwise |0| (false).

\begin{codeexample}[]
\pgfmathparse{isInString("foo", "bar")} \pgfmathresult
\ and\ 
\pgfmathparse{isInString("foo", "foobar")} \pgfmathresult
\end{codeexample}
\end{math-function}

\begin{math-function}{strcat("\mvar{Text A}", "\mvar{Text B}", …)}
\mathcommand
  Returns the concatenation of all given parameters.

\begin{codeexample}[]
\pgfmathparse{strcat("blue!", int(7*3), "!green")} \pgfmathresult
\end{codeexample}
\end{math-function}


\begin{math-function}{isEmpty("\mvar{Text}")}
\mathcommand
  Returns |1| (true) if \mvar{Text} is empty, otherwise |0| (false).
  %
\begin{codeexample}[]
\pgfmathparse{isEmpty("foo")} \pgfmathresult\ and\ 
\pgfmathparse{isEmpty("")}    \pgfmathresult\ and\ 
\def\emptyText{}
\pgfmathparse{isEmpty("\emptyText")} \pgfmathresult
\end{codeexample}
\end{math-function}

\begin{math-function}{atanXY(\mvar{x},\mvar{y})}
\mathcommand
  Arctangent of $\mvar y\div \mvar x$ in degrees. This also takes into account the quadrant.
  This is just a argument-swapped version of |atan2| which makes it easier to use
  the |\p| commands of the |calc| library.
  \index{atan2@\protect\texttt{atan2} math function}%
  \index{Math functions!atan2@\protect\texttt{atan2}}%
  %
\begin{codeexample}[]
\pgfmathparse{atanXY(3,4)} \pgfmathresult
\end{codeexample}
\end{math-function}
\begin{math-function}{atanYX(\mvar{y},\mvar{x})}
\mathcommand
   Arctangent of $y\div x$ in degrees. This also takes into account the quadrant.
\begin{codeexample}[]
\pgfmathparse{atanYX(4,3)} \pgfmathresult
\end{codeexample}
\end{math-function}

\subsection{Functions: using coordinates}
The following functions can only be used with PGF and/or \tikzname.
Since the arguments are usually plain text (and not numbers) one has to wrap
them in |"|.
\begin{math-function}{anglebetween("\mvar{p1}", "\mvar{p2}")}\mathcommand
  Return the angle between the centers of the nodes \mvar{p1} and \mvar{p2}.
\end{math-function}
\begin{math-function}{qanglebetween("\mvar{p}")}\mathcommand
  Return the angle between the origin and the center of the node \mvar{p}.
\end{math-function}
\begin{math-function}{distancebetween("\mvar{p1}", "\mvar{p2}")}\mathcommand
  Return the distance (in pt) between the centers of the nodes \mvar{p1} and \mvar{p2}.
\end{math-function}
\begin{math-function}{qdistancebetween("\mvar{p}")}\mathcommand
  Return the distance (in pt) between the origin and the center of the node \mvar{p}.
\end{math-function}
\begin{codeexample}[width=6cm,preamble=\usetikzlibrary{calc,misc,through}]
\begin{tikzpicture}
\path (0,0) coordinate (A) + (0:4) coordinate (B) +(75:4) coordinate (C);
\draw (A) -- (B) -- (C) -- cycle;
\foreach \cnt in {1,...,4}{
  \pgfmathsetmacro\triA{distancebetween("B","C")}
  \pgfmathsetmacro\triB{distancebetween("C","A")}
  \pgfmathsetmacro\triC{distancebetween("A","B")}
  \path (barycentric cs:A=\triA,B=\triB,C=\triC) coordinate (M)
       node [draw, circle through=($(A)!(M)!(C)$)] (M) {};
  \draw ($(C)-(A)$) coordinate (vecB)
      (M.75-90) coordinate (@)
      (intersection of @--[shift=(vecB)]@ and B--C) coordinate (C) -- 
      (intersection of @--[shift=(vecB)]@ and B--A) coordinate (A);}
\end{tikzpicture}
\end{codeexample}
\section{PGFkeys}

\subsection{Conditionals}

\begin{key}{/utils/if=\meta{cond}\meta{true}\opt{\meta{false}}}
  This key checks the conditional \meta{cond} and applies the styles \meta{true}
  if \meta{cond} is true, otherwise \meta{false}.
  \meta{cond} can be anything that PGFmath understands.
  
  As a side effect on how PGFkeys parses argument, the \meta{false} argument is
  actually optional.
\end{key}

The following keys use \TeX' macros |\if|, |\ifx|, |\ifnum| and |\ifdim| for faster
executions.

\begin{key}{/utils/TeX/if=\meta{token A}\meta{token B}\meta{true}\opt{\meta{false}}}
  This key checks via |\if| if \meta{token A} matches \meta{token B}
  and applies the styles \meta{true} if it does, otherwise \meta{false}.
  
  As a side effect on how PGFkeys parses argument, the \meta{false} argument is
  actually optional.
\end{key}

\begin{key}{/utils/TeX/ifx=\meta{token A}\meta{token B}\meta{true}\opt{\meta{false}}}
  As above.
\end{key}

\begin{key}{/utils/TeX/ifnum=\meta{num cond}\meta{true}\\opt{\meta{false}}}
  This key checks |\ifnum|\meta{num cond}
  and applies the styles \meta{true} if true, otherwise \meta{false}.
  A delimiting |\relax| will be inserted after \meta{num cond}.
  
  As a side effect on how PGFkeys parses argument, the \meta{false} argument is
  actually optional.
\end{key}

\begin{key}{/utils/TeX/ifdim=\meta{dim cond}\meta{true}\opt{\meta{false}}}
  As above.
\end{key}

\begin{key}{/utils/TeX/ifempty=\meta{Text}\meta{true}\opt{\meta{false}}}
  This checks whether \meta{Text} is empty and applies styles \meta{true} if true,
  otherwise \meta{false}.
\end{key}


\subsection{Handlers}

While already a lot of values given to keys are evaluated by PGFmath at some point,
not all of them are.

\begin{handler}{{.pgfmath}|=|\meta{eval}}
  This handler evaluates \meta{eval} before it is handed to the key.
\end{handler}

\begin{handler}{{.pgfmath int}|=|\meta{eval}}
  As above but truncates the result.
\end{handler}

\begin{handler}{{.pgfmath strcat}|=|\meta{eval}}
  As above but uses the |strcat| function.
  
  In the example below, one could have used the |/pgf/foreach/evaluate| key from |\foreach|.
\begin{codeexample}[width=6cm,preamble=\usetikzlibrary{misc}]
\tikz\foreach \i in {0,10,...,100}
  \draw[line width=+.2cm, color/.pgfmath strcat={"red!",sqrt(\i)*10,"!blue"}]
    (0,\i/50) -- +(right:3);
\end{codeexample}
\end{handler}

\begin{handler}{{.List}|=|\meta{\meta{e1}, \meta{e2}, \dots, \meta{en}}}
  This handler evaluates the given list with |\foreach| and concatenates the element and
  the result is then given to the used key.
\begin{codeexample}[width=6cm,preamble=\usetikzlibrary{fit,misc}]
\begin{tikzpicture}[nodes={draw, dashed, inner sep=+10pt}]
  \foreach \point [count=\cnt] in {(0,0), (0,2), (2,0), (2,2), (3,3), (-1,-1)}
    \fill \point circle[radius=.1] coordinate (point-\cnt);
  \node[gray, fit/.List={(point-1),(point-...),(point-4)}] {}; 
  \node[red,  fit/.List={(point-1),(point-...),(point-5)}] {}; 
  \node[blue, fit/.List={(point-1),(point-...),(point-6)}] {};
\end{tikzpicture}
\end{codeexample}
\end{handler}
\begin{center}
\begin{codeexample}[width=10cm,preamble=\usetikzlibrary{graphs,graphdrawing} \usegdlibrary{force}]
\tikzset{
  mynode/.style={
    circle, minimum size=10mm, draw, densely dashdotted, thick,
    decide color/.expand once=#1},
  decide color/.style 2 args={
    /utils/TeX/if=c#1
      {/utils/TeX/ifnum={#2<5}{bluelight}{bluedark}}
      {/utils/TeX/ifnum={#2<8}{light}{dark}}},
  light/.style={fill=gray!20},  bluelight/.style={fill=blue!10},
  dark/.style ={fill=gray!60},  bluedark/.style ={fill=blue!30}}
\tikz\graph[
  spring electrical layout, vertical=c2 to p13,
  node distance=1.5cm, typeset=$n_{\tikzgraphnodetext}$,
  nodes={mynode=\tikzgraphnodetext}] {
  % outer ring
  c2 -- {p1, p11, p6};
    p1 -- {p8, c6, p11};
      p8 -- {p3, p10, c6};
       p3 -- {p13, p15, p10};
         p13 -- {p15, c7};
           c7  -- {c3, c4, p15};
           c3  -- {p14, c4};
           p14 -- {p7, c4};
         p7 -- {p9, p2, c4};
       p9 -- {c5, p12, p2};
     c5 -- {c1, p4, p12};
   c1 -- {p6, p4};
  p6 -- {p11, p4};
  % inner ring
  p11 -- {c6, p12, p4};
  p5 -- {c6 -- {p10, p12}, p10 -- p15, p15 -- c4, c4 -- p2, p2 -- p12, p12 -- p4};
};
\end{codeexample}
\end{center}

\section{PGFfor}

Instead of |\foreach \var in {start, start + delta, ..., end}| one can use
|\foreach \var[use int=start to end step delta]|.

\begin{key}{/pgf/foreach/use int=\meta{start}|to|\meta{end}\opt{|step|\meta{delta}}}
The values \meta{start}, \meta{end} and \meta{delta} are evaluates by PGFmath at initialization.
The part |step |\meta{delta} is optional (\meta{delta} = 1).
\end{key}

\begin{key}{/pgf/foreach/use float=\meta{start}| o|\meta{end}opt{|step|\meta{delta}}}
Same as above, however the results are not truncated.
\end{key}

%TODO: edges to and edges through
\endinput