% Copyright 2007 by Mark Wibrow
%
% 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{Additional Mathematical Commands}

\label{pgfmath-commands}

Instead of parsing and evaluating complex expressions, you can also
use the mathematical engine to evaluate a single mathematical
operation. The macros used for many of these computations are listed 
above in Section~\ref{pgfmath-functions}. \pgfname{} also provides 
some additional commands which are shown below:

\subsection{Basic arithmetic functions}

\label{pgfmath-commands-basic}

In addition to the commands described in 
Section~\ref{pgfmath-functions-basic}, the following command is
provided:

\begin{command}{\pgfmathreciprocal\marg{x}}         
	Defines |\pgfmathresult| as $1\div\meta{x}$. This provides 
	greatest accuracy when \mvar{x} is small.                  
\end{command}

\subsection{Comparison and logical functions}

In addition to the commands described in 
Section~\ref{pgfmath-functions-comparison}, 
the following command was provided by Christian Feuers\"anger:

\begin{command}{\pgfmathapproxequalto\marg{x}\marg{y}}       
	Defines |\pgfmathresult| 1.0 if $ \rvert \meta{x} - \meta{y} \lvert < 0.0001$, but 0.0 otherwise.                    
	As a side-effect, the global boolean |\ifpgfmathcomparison| will be set accordingly.
\end{command}

\subsection{Pseudo-Random Numbers}

\label{pgfmath-random}

In addition to the commands described in 
Section~\ref{pgfmath-functions-random}, 
the following commands are provided:

\begin{command}{\pgfmathgeneratepseudorandomnumber}
	Defines |\pgfmathresult| as a pseudo-random integer between 1 and 
	$2^{31}-1$. This uses a linear congruency generator, based on ideas
	of Erich Janka.
\end{command}

\begin{command}{\pgfmathrandominteger\marg{macro}\marg{minimum}\marg{maximum}}
	This defines \meta{macro} as a pseudo-randomly generated integer from 
	the range \meta{minimum} to \meta{maximum} (inclusive).
	
\begin{codeexample}[]
\begin{pgfpicture}
   \foreach \x in {1,...,50}{
      \pgfmathrandominteger{\a}{1}{50}
      \pgfmathrandominteger{\b}{1}{50}
      \pgfpathcircle{\pgfpoint{+\a pt}{+\b pt}}{+2pt}
      \color{blue!40!white}
      \pgfsetstrokecolor{blue!80!black}
      \pgfusepath{stroke, fill}
   }	  
\end{pgfpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfmathdeclarerandomlist\marg{list name}\{\marg{item-1}\marg{item 2}...\}}
	This creates a list of items with the name \meta{list name}.
\end{command}

\begin{command}{\pgfmathrandomitem\marg{macro}\marg{list name}}
	Select an item from a random list \meta{list name}. The
	selected item is placed in \meta{macro}.
\end{command}

\begin{codeexample}[]
\begin{pgfpicture}
   \pgfmathdeclarerandomlist{color}{{red}{blue}{green}{yellow}{white}}
   \foreach \a in {1,...,50}{
      \pgfmathrandominteger{\x}{1}{85}
      \pgfmathrandominteger{\y}{1}{85}
      \pgfmathrandominteger{\r}{5}{10}
      \pgfmathrandomitem{\c}{color}
      \pgfpathcircle{\pgfpoint{+\x pt}{+\y pt}}{+\r pt}
      \color{\c!40!white}
      \pgfsetstrokecolor{\c!80!black}
      \pgfusepath{stroke, fill}
   }	  
\end{pgfpicture}
\end{codeexample}

\begin{command}{\pgfmathsetseed\marg{integer}}
  Explicitly sets the seed for the pseudo-random number generator. By
  default it is set to the value of |\time|$\times$|\year|.
\end{command}


      
\subsection{Base Conversion}
	
\label{pgfmath-bases}

\pgfname{} provides limited support for conversion between 
\emph{representations} of numbers. Currently the numbers must be
positive integers in the range $0$ to $2^{31}-1$, and the bases in the
range $2$ to $36$. All digits representing numbers greater than 9 (in
base ten), are alphabetic, but may be upper or lower case. 

In addition to the commands described in 
Section~\ref{pgfmath-functions-base}, 
the following commands are provided:

\begin{command}{\pgfmathbasetodec\marg{macro}\marg{number}\marg{base}}
	Defines \meta{macro} as the result of converting \meta{number} from
	base \meta{base} to base 10. Alphabetic digits can be upper or lower
	case.

\medskip{\def\medskip{}

\begin{codeexample}[]
\pgfmathbasetodec\mynumber{107f}{16} \mynumber
\end{codeexample}
	
	\noindent Note that, as usual in \TeX, the braces around an argument can be omitted if the argument is just a single token (a macro name is a single token).


\begin{codeexample}[]
\pgfmathbasetodec\mynumber{33FC}{20} \mynumber
\end{codeexample}

}\medskip

\end{command}

\begin{command}{\pgfmathdectobase\marg{macro}\marg{number}\marg{base}}
	Defines \meta{macro} as the result of converting \meta{number} from
	base 10 to base \meta{base}. Any resulting alphabetic digits are in
	\emph{lower case}.
	
\begin{codeexample}[]
\pgfmathdectobase\mynumber{65535}{16} \mynumber
\end{codeexample}

\end{command}

\begin{command}{\pgfmathdectoBase\marg{macro}\marg{number}\marg{base}}
	Defines \meta{macro} as the result of converting \meta{number} from
	base 10 to base \meta{base}. Any resulting alphabetic digits are in
	\emph{upper case}.
	
\begin{codeexample}[]
\pgfmathdectoBase\mynumber{65535}{16} \mynumber
\end{codeexample}

\end{command}

\begin{command}{\pgfmathbasetobase\marg{macro}\marg{number}\marg{base-1}\marg{base-2}}
	Defines \meta{macro} as the result of converting \meta{number} from
	base \meta{base-1} to base \meta{base-2}. Alphabetic digits in 
	\meta{number} can be upper or lower case, but any resulting 
	alphabetic digits are in \emph{lower case}.
	
\begin{codeexample}[]
\pgfmathbasetobase\mynumber{11011011}{2}{16} \mynumber
\end{codeexample}

\end{command}

\begin{command}{\pgfmathbasetoBase\marg{macro}\marg{number}\marg{base-1}\marg{base-2}}
	Defines \meta{macro} as the result of converting \meta{number} from
	base \meta{base-1} to base \meta{base-2}. Alphabetic digits in 
	\meta{number} can be upper or lower case, but any resulting 
	alphabetic digits are in \emph{upper case}.
	
\begin{codeexample}[]
\pgfmathbasetoBase\mynumber{121212}{3}{12} \mynumber
\end{codeexample}

\end{command}


\begin{command}{\pgfmathsetbasenumberlength\marg{integer}}
	Sets the number of digits in the result of a base conversion to 
	\meta{integer}. If the result of a conversion has less digits
	than this number, it is prefixed with zeros.

\begin{codeexample}[]
\pgfmathsetbasenumberlength{8}
\pgfmathdectobase\mynumber{15}{2} \mynumber
\end{codeexample}
\end{command}

\begin{command}{\pgfmathtodigitlist\marg{macro}\marg{number}}

	This command converts \meta{number} into a comma-separated
	list of digits and stores the result in \meta{macro}. 
	The \marg{number} is \emph{not} parsed before processing.
	
\begin{codeexample}[]
\pgfmathsetbasenumberlength{8}
\begin{tikzpicture}[x=0.25cm, y=0.25cm]
  \foreach \n [count=\y] in {0, 60, 102, 102, 126, 102, 102, 102, 0}{
    \pgfmathdectobase{\binary}{\n}{2}
    \pgfmathtodigitlist{\digitlist}{\binary}
    \foreach \digit [count=\x, evaluate={\c=\digit*50+15;}] in \digitlist
      \fill [fill=black!\c] (\x, -\y) rectangle ++(1,1);
  }
\end{tikzpicture}
\end{codeexample}

\end{command}


\subsection{Angle Computations}

Unlike the rest of the math engine, which is a ``standalone'' package,
the following commands only work in conjunction with the core of
\pgfname.



\begin{command}{\pgfmathanglebetweenpoints\marg{p}\marg{q}}
  Returns the angle of a line from \meta{p} to \meta{q} relative to a
  line going straight right from \meta{p}.
  
\begin{codeexample}[]
\pgfmathanglebetweenpoints{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}}
\pgfmathresult
\end{codeexample}
\end{command}

\begin{command}{\pgfmathanglebetweenlines\marg{$p_1$}\marg{$q_1$}\marg{$p_2$}\marg{$q_2$}}
  Returns the clockwise angle between a line going through $p_1$ and
  $q_1$ and a line going through $p_2$ and $q_2$.
  
\begin{codeexample}[]
\pgfmathanglebetweenlines{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}}
                         {\pgfpoint{0cm}{1cm}}{\pgfpoint{1cm}{0cm}}  
\pgfmathresult
\end{codeexample}
\end{command}
