Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-math-commands.tex

raw
1 % Copyright 2018 by Mark Wibrow
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Additional Mathematical Commands}
12 \label{pgfmath-commands}
13
14 Instead of parsing and evaluating complex expressions, you can also use the
15 mathematical engine to evaluate a single mathematical operation. The macros
16 used for many of these computations are listed above in
17 Section~\ref{pgfmath-functions}. \pgfname{} also provides some additional
18 commands which are shown below:
19
20
21 \subsection{Basic arithmetic functions}
22 \label{pgfmath-commands-basic}
23
24 In addition to the commands described in Section~\ref{pgfmath-functions-basic},
25 the following command is provided:
26
27 \begin{command}{\pgfmathreciprocal\marg{x}}
28 Defines |\pgfmathresult| as $1\div\meta{x}$. This provides greatest
29 accuracy when \mvar{x} is small.
30 \end{command}
31
32
33 \subsection{Comparison and logical functions}
34
35 In addition to the commands described in
36 Section~\ref{pgfmath-functions-comparison}, the following command was provided
37 by Christian Feuers\"anger:
38
39 \begin{command}{\pgfmathapproxequalto\marg{x}\marg{y}}
40 Defines |\pgfmathresult| 1.0 if $ \rvert \meta{x} - \meta{y} \lvert <
41 0.0001$, but 0.0 otherwise. As a side-effect, the global boolean
42 |\ifpgfmathcomparison| will be set accordingly.
43 \end{command}
44
45
46 \subsection{Pseudo-Random Numbers}
47 \label{pgfmath-random}
48
49 In addition to the commands described in
50 Section~\ref{pgfmath-functions-random}, the following commands are provided:
51
52 \begin{command}{\pgfmathgeneratepseudorandomnumber}
53 Defines |\pgfmathresult| as a pseudo-random integer between 1 and
54 $2^{31}-1$. This uses a linear congruency generator, based on ideas of
55 Erich Janka.
56 \end{command}
57
58 \begin{command}{\pgfmathrandominteger\marg{macro}\marg{minimum}\marg{maximum}}
59 This defines \meta{macro} as a pseudo-randomly generated integer from the
60 range \meta{minimum} to \meta{maximum} (inclusive).
61 %
62 \begin{codeexample}[]
63 \begin{pgfpicture}
64 \foreach \x in {1,...,50}{
65 \pgfmathrandominteger{\a}{1}{50}
66 \pgfmathrandominteger{\b}{1}{50}
67 \pgfpathcircle{\pgfpoint{+\a pt}{+\b pt}}{+2pt}
68 \color{blue!40!white}
69 \pgfsetstrokecolor{blue!80!black}
70 \pgfusepath{stroke, fill}
71 }
72 \end{pgfpicture}
73 \end{codeexample}
74 %
75 \end{command}
76
77 \begin{command}{\pgfmathdeclarerandomlist\marg{list name}{\ttfamily\{}\marg{item-1}\marg{item-2}...{\ttfamily\}}}
78 This creates a list of items with the name \meta{list name}.
79 \end{command}
80
81 \begin{command}{\pgfmathrandomitem\marg{macro}\marg{list name}}
82 Select an item from a random list \meta{list name}. The
83 selected item is placed in \meta{macro}.
84 \end{command}
85
86 \begin{codeexample}[]
87 \begin{pgfpicture}
88 \pgfmathdeclarerandomlist{color}{{red}{blue}{green}{yellow}{white}}
89 \foreach \a in {1,...,50}{
90 \pgfmathrandominteger{\x}{1}{85}
91 \pgfmathrandominteger{\y}{1}{85}
92 \pgfmathrandominteger{\r}{5}{10}
93 \pgfmathrandomitem{\c}{color}
94 \pgfpathcircle{\pgfpoint{+\x pt}{+\y pt}}{+\r pt}
95 \color{\c!40!white}
96 \pgfsetstrokecolor{\c!80!black}
97 \pgfusepath{stroke, fill}
98 }
99 \end{pgfpicture}
100 \end{codeexample}
101
102 \begin{command}{\pgfmathsetseed\marg{integer}}
103 Explicitly sets the seed for the pseudo-random number generator. By default
104 it is set to the value of |\time|$\times$|\year|.
105 \end{command}
106
107
108 \subsection{Base Conversion}
109 \label{pgfmath-bases}
110
111 \pgfname{} provides limited support for conversion between
112 \emph{representations} of numbers. Currently the numbers must be positive
113 integers in the range $0$ to $2^{31}-1$, and the bases in the range $2$ to
114 $36$. All digits representing numbers greater than 9 (in base ten), are
115 alphabetic, but may be upper or lower case.
116
117 In addition to the commands described in Section~\ref{pgfmath-functions-base},
118 the following commands are provided:
119
120 \begin{command}{\pgfmathbasetodec\marg{macro}\marg{number}\marg{base}}
121 Defines \meta{macro} as the result of converting \meta{number} from base
122 \meta{base} to base 10. Alphabetic digits can be upper or lower case.
123
124 \medskip{\def\medskip{}
125
126 \begin{codeexample}[]
127 \pgfmathbasetodec\mynumber{107f}{16} \mynumber
128 \end{codeexample}
129
130 \noindent Note that, as usual in \TeX, the braces around an argument can be
131 omitted if the argument is just a single token (a macro name is a single
132 token).
133 %
134 \begin{codeexample}[]
135 \pgfmathbasetodec\mynumber{33FC}{20} \mynumber
136 \end{codeexample}
137
138 }\medskip
139 %
140 \end{command}
141
142 \begin{command}{\pgfmathdectobase\marg{macro}\marg{number}\marg{base}}
143 Defines \meta{macro} as the result of converting \meta{number} from base 10
144 to base \meta{base}. Any resulting alphabetic digits are in \emph{lower
145 case}.
146 %
147 \begin{codeexample}[]
148 \pgfmathdectobase\mynumber{65535}{16} \mynumber
149 \end{codeexample}
150 %
151 \end{command}
152
153 \begin{command}{\pgfmathdectoBase\marg{macro}\marg{number}\marg{base}}
154 Defines \meta{macro} as the result of converting \meta{number} from base 10
155 to base \meta{base}. Any resulting alphabetic digits are in \emph{upper
156 case}.
157 %
158 \begin{codeexample}[]
159 \pgfmathdectoBase\mynumber{65535}{16} \mynumber
160 \end{codeexample}
161 %
162 \end{command}
163
164 \begin{command}{\pgfmathbasetobase\marg{macro}\marg{number}\marg{base-1}\marg{base-2}}
165 Defines \meta{macro} as the result of converting \meta{number} from base
166 \meta{base-1} to base \meta{base-2}. Alphabetic digits in \meta{number} can
167 be upper or lower case, but any resulting alphabetic digits are in
168 \emph{lower case}.
169 %
170 \begin{codeexample}[]
171 \pgfmathbasetobase\mynumber{11011011}{2}{16} \mynumber
172 \end{codeexample}
173 %
174 \end{command}
175
176 \begin{command}{\pgfmathbasetoBase\marg{macro}\marg{number}\marg{base-1}\marg{base-2}}
177 Defines \meta{macro} as the result of converting \meta{number} from base
178 \meta{base-1} to base \meta{base-2}. Alphabetic digits in \meta{number} can
179 be upper or lower case, but any resulting alphabetic digits are in
180 \emph{upper case}.
181 %
182 \begin{codeexample}[]
183 \pgfmathbasetoBase\mynumber{121212}{3}{12} \mynumber
184 \end{codeexample}
185 %
186 \end{command}
187
188 \begin{command}{\pgfmathsetbasenumberlength\marg{integer}}
189 Sets the number of digits in the result of a base conversion to
190 \meta{integer}. If the result of a conversion has less digits than this
191 number, it is prefixed with zeros.
192 %
193 \begin{codeexample}[]
194 \pgfmathsetbasenumberlength{8}
195 \pgfmathdectobase\mynumber{15}{2} \mynumber
196 \end{codeexample}
197 %
198 \end{command}
199
200 \begin{command}{\pgfmathtodigitlist\marg{macro}\marg{number}}
201 This command converts \meta{number} into a comma-separated list of digits
202 and stores the result in \meta{macro}. The \marg{number} is \emph{not}
203 parsed before processing.
204 %
205 \begin{codeexample}[]
206 \pgfmathsetbasenumberlength{8}
207 \begin{tikzpicture}[x=0.25cm, y=0.25cm]
208 \foreach \n [count=\y] in {0, 60, 102, 102, 126, 102, 102, 102, 0}{
209 \pgfmathdectobase{\binary}{\n}{2}
210 \pgfmathtodigitlist{\digitlist}{\binary}
211 \foreach \digit [count=\x, evaluate={\c=\digit*50+15;}] in \digitlist
212 \fill [fill=black!\c] (\x, -\y) rectangle ++(1,1);
213 }
214 \end{tikzpicture}
215 \end{codeexample}
216 %
217 \end{command}
218
219
220 \subsection{Angle Computations}
221
222 Unlike the rest of the math engine, which is a ``standalone'' package, the
223 following commands only work in conjunction with the core of \pgfname.
224
225 \begin{command}{\pgfmathanglebetweenpoints\marg{p}\marg{q}}
226 Returns the angle of a line from \meta{p} to \meta{q} relative to a line
227 going straight right from \meta{p}.
228 %
229 \begin{codeexample}[]
230 \pgfmathanglebetweenpoints{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}}
231 \pgfmathresult
232 \end{codeexample}
233 %
234 \end{command}
235
236 \begin{command}{\pgfmathanglebetweenlines\marg{$p_1$}\marg{$q_1$}\marg{$p_2$}\marg{$q_2$}}
237 Returns the clockwise angle between a line going through $p_1$ and $q_1$
238 and a line going through $p_2$ and $q_2$.
239 %
240 \begin{codeexample}[]
241 \pgfmathanglebetweenlines{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}}
242 {\pgfpoint{0cm}{1cm}}{\pgfpoint{1cm}{0cm}}
243 \pgfmathresult
244 \end{codeexample}
245 %
246 \end{command}