Debian Codegraph @

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

raw
1 % Copyright 2019 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{Mathematical Expressions}
12 \label{pgfmath-syntax}
13
14 The easiest way of using \pgfname's mathematical engine is to provide a
15 mathematical expression given in familiar infix notation, for example,
16 |1cm+4*2cm/5.5| or |2*3+3*sin(30)|. This expression can be parsed by the
17 mathematical engine and the result can be placed in a dimension register, a
18 counter, or a macro.
19
20 It should be noted that all calculations must not exceed $\pm16383.99999$ at
21 \emph{any} point, because the underlying computations rely on \TeX{}
22 dimensions. This means that many of the underlying computations are necessarily
23 approximate and, in addition, not very fast. \TeX{} is, after all, a
24 typesetting language and not ideally suited to relatively advanced mathematical
25 operations. However, it is possible to change the computations as described in
26 Section~\ref{pgfmath-reimplement}.
27
28 In the present section, the high-level macros for parsing an expression are
29 explained first, then the syntax for expression is explained.
30
31
32 \subsection{Parsing Expressions}
33 \label{pgfmath-registers}
34 \label{pgfmath-parsing}
35
36 \subsubsection{Commands}
37
38 The \todosp{why 2 labels?}basic command for invoking the parser of \pgfname's
39 mathematical engine is the following:
40
41 \begin{command}{\pgfmathparse\marg{expression}}
42 This macro parses \meta{expression} and returns the result without units in
43 the macro |\pgfmathresult|.
44
45 \example |\pgfmathparse{2pt+3.5pt}| will set |\pgfmathresult| to the text
46 |5.5|.
47
48 In the following, the special properties of this command are explained. The
49 exact syntax of mathematical expressions is explained in Sections
50 \ref{pgfmath-operators} and~\ref{pgfmath-functions}.
51 %
52 \begin{itemize}
53 \item The result stored in the macro |\pgfmathresult| is a decimal
54 \emph{without units}. This is true regardless of whether the
55 \meta{expression} contains any unit specification. All numbers with
56 units are converted to points first. See
57 Section~\ref{pgfmath-units} for details on units.
58 \item The parser will recognize \TeX{} registers and box dimensions, so
59 |\mydimen|, |0.5\mydimen|, |\wd\mybox|, |0.5\dp\mybox|,
60 |\mycount\mydimen| and so on can be parsed.
61 \item The $\varepsilon$-TeX\ extensions |\dimexpr|, |\numexpr|,
62 |\glueexpr|, and |\muexpr| are recognized and evaluated. The values
63 they result in will be used in the further evaluation, as if you
64 had put |\the| before them.
65 \item Parenthesis can be used to change the order of the evaluation.
66 \item Various functions are recognized, so it is possible to parse
67 |sin(.5*pi r)*60|, which means ``the sine of $0.5$ times $\pi$
68 radians, multiplied by 60''. The argument of functions can be any
69 expression.
70 \item Scientific notation in the form |1.234e+4| is recognized (but the
71 restriction on the range of values still applies). The exponent
72 symbol can be upper or lower case (i.e., |E| or |e|).
73 \item An integer with a zero-prefix (excluding, of course zero itself),
74 is interpreted as an octal number and is automatically converted to
75 base 10.
76 \item An integer with prefix |0x| or |0X| is interpreted as a
77 hexadecimal number and is automatically converted to base 10.
78 Alphabetic digits can be in uppercase or lowercase.
79 \item An integer with prefix |0b| or |0B| is interpreted as a binary
80 number and is automatically converted to base 10.
81 \item An expression (or part of an expression) surrounded with double
82 quotes (i.e., the character |"|) will not be evaluated. Obviously
83 this should be used with great care.
84 \end{itemize}
85 \end{command}
86
87 \begin{command}{\pgfmathqparse\marg{expression}}
88 This macro is similar to |\pgfmathparse|: it parses \meta{expression} and
89 returns the result in the macro |\pgfmathresult|. It differs in two
90 respects. Firstly, |\pgfmathqparse| does not parse functions, scientific
91 notation, the prefixes for binary octal, or hexadecimal numbers, nor does
92 it accept the special use of |"|, |?| or |:| characters. Secondly, numbers
93 in \meta{expression} \emph{must} specify a \TeX{} unit (except in such
94 instances as |0.5\pgf@x|), which greatly simplifies the problem of parsing
95 real numbers. As a result of these restrictions |\pgfmathqparse| is about
96 twice as fast as |\pgfmathparse|. Note that the result will still be a
97 number without units.
98 \end{command}
99
100 \begin{command}{\pgfmathpostparse}
101 At the end of the parse this command is executed, allowing some custom
102 action to be performed on the result of the parse. When this command is
103 executed, the macro |\pgfmathresult| will hold the result of the parse (as
104 always, without units). The result of the custom action should be used to
105 redefine |\pgfmathresult| appropriately. By default, this command is
106 equivalent to |\relax|. This differs from previous versions, where, if the
107 parsed expression contained no units, the result of the parse was scaled
108 according to the value in |\pgfmathresultunitscale| (which by default was
109 |1|).
110
111 This scaling can be turned on again using:
112 |\let\pgfmathpostparse=\pgfmathscaleresult|. Note, however that by scaling
113 the result, the base conversion functions will not work, and the |"|
114 character should not be used to quote parts of an expression.
115 \end{command}
116
117 Instead of the |\pgfmathparse| macro you can also use wrapper commands, whose
118 usage is very similar to their cousins in the \calcname{} package. The only
119 difference is that the expressions can be any expression that is handled by
120 |\pgfmathparse|. For all of the following commands, if \meta{expression} starts
121 with |+|, no parsing is done and a simple assignment or increment is done using
122 normal \TeX\ assignments or increments. This will be orders of magnitude faster
123 than calling the parser.
124
125 The effect of the following commands is always local to the current \TeX\
126 scope.
127
128 \begin{command}{\pgfmathsetlength\marg{register}\marg{expression}}
129 Basically, this command sets the length of the \TeX{} \meta{register} to
130 the value specified by \meta{expression}. However, there is some fine
131 print:
132
133 First, in case \meta{expression} starts with a |+|, a simple \TeX\
134 assignment is done. In particular, \meta{register} can be a glue register
135 and \meta{expression} be something like |+1pt plus 1fil| and the
136 \meta{register} will be assigned the expected value.
137
138 Second, when the \meta{expression} does not start with |+|, it is first
139 parsed using |\pgfmathparse|, resulting in a (dimensionless) value
140 |\pgfmathresult|. Now, if the parser encountered the unit |mu| somewhere in
141 the expression, it assumes that \meta{register} is a |\muskip| register and
142 will try to assign to \meta{register} the value |\pgfmathresult| followed
143 by |mu|. Otherwise, in case |mu| was not encountered, it is assumed that
144 \meta{register} is a dimension register or a glue register and we assign
145 |\pgfmathresult| followed by |pt| to it.
146
147 The net effect of the above is that you can write things like
148 %
149 \begin{codeexample}[]
150 \muskipdef\mymuskip=0
151 \pgfmathsetlength{\mymuskip}{1mu+3*4mu} \the\mymuskip
152 \end{codeexample}
153 %
154 \begin{codeexample}[]
155 \dimendef\mydimen=0
156 \pgfmathsetlength{\mydimen}{1pt+3*4pt} \the\mydimen
157 \end{codeexample}
158 %
159 \begin{codeexample}[]
160 \skipdef\myskip=0
161 \pgfmathsetlength{\myskip}{1pt+3*4pt} \the\myskip
162 \end{codeexample}
163
164 One thing that will \emph{not} work is
165 |\pgfmathsetlength{\myskip}{1pt plus 1fil}| since the parser does not
166 support fill's. You can, however, use the |+| notation in this case:
167 %
168 \begin{codeexample}[]
169 \skipdef\myskip=0
170 \pgfmathsetlength{\myskip}{+1pt plus 1fil} \the\myskip
171 \end{codeexample}
172 %
173 \end{command}
174
175 \begin{command}{\pgfmathaddtolength\marg{register}\marg{expression}}
176 Adds the value of \meta{expression} to the \TeX{} \meta{register}. All of
177 the special consideration mentioned for |\pgfmathsetlength| also apply here
178 in the same way.
179 \end{command}
180
181 \begin{command}{\pgfmathsetcount\marg{count register}\marg{expression}}
182 Sets the value of the \TeX{} \meta{count register}, to the \emph{truncated}
183 value specified by \meta{expression}.
184 \end{command}
185
186 \begin{command}{\pgfmathaddtocount\marg{count register}\marg{expression}}
187 Adds the \emph{truncated} value of \meta{expression} to the \TeX{}
188 \meta{count register}.
189 \end{command}
190
191 \begin{command}{\pgfmathsetcounter\marg{counter}\marg{expression}}
192 Sets the value of the \LaTeX{} \meta{counter} to the \emph{truncated} value
193 specified by \meta{expression}.
194 \end{command}
195
196 \begin{command}{\pgfmathaddtocounter\marg{counter}\marg{expression}}
197 Adds the \emph{truncated} value of \meta{expression} to \meta{counter}.
198 \end{command}
199
200 \begin{command}{\pgfmathsetmacro\marg{macro}\marg{expression}}
201 Defines \meta{macro} as the value of \meta{expression}. The result is a
202 decimal without units.
203 \end{command}
204
205 \begin{command}{\pgfmathsetlengthmacro\marg{macro}\marg{expression}}
206 Defines \meta{macro} as the value of \meta{expression} \emph{in points}.
207 \end{command}
208
209 \begin{command}{\pgfmathtruncatemacro\marg{macro}\marg{expression}}
210 Defines \meta{macro} as the truncated value of \meta{expression}.
211 \end{command}
212
213
214 \subsubsection{Considerations Concerning Units}
215 \label{pgfmath-units}
216
217 As was explained earlier, the parser commands like |\pgfmathparse| will always
218 return a result without units in it and all dimensions that have a unit like
219 |10pt| or |1in| will first be converted to \TeX\ points (|pt|) and, then, the
220 unit is dropped.
221
222 Sometimes it is useful, nevertheless, to find out whether an expression or not.
223 For this, you can use the following commands:
224
225 {\let\ifpgfmathunitsdeclared\relax
226 \begin{command}{\ifpgfmathunitsdeclared}
227 After a call of |\pgfmathparse| this if will be true exactly if
228 some unit was encountered in the expression. It is always set
229 globally in each call.
230
231 Note that \emph{any} ``mentioning'' of a unit inside an
232 expression will set this \TeX-if to true. In particular, even an
233 expressionlike |2pt/1pt|, which arguably should be considered
234 ``scalar'' or ``unit-free'' will still have this \TeX-if set to
235 true. However, see the |scalar| function for a way to change
236 this.
237 \end{command}
238 }
239
240 \begin{math-function}{scalar(\mvar{value})}
241 \mathcommand
242 This function is the identity function on its input, but it will reset the
243 \TeX-if |\ifpgfmathunitsdeclared|. Thus, it can be used to indicate that
244 the given \meta{value} should be considered as a ``scalar'' even when it
245 contains units; but note that it will work even when the \meta{value} is a
246 string or something else. The only effect of this function is to clear the
247 unit declaration.
248 %
249 \begin{codeexample}[]
250 \pgfmathparse{scalar(1pt/2pt)} \pgfmathresult\
251 \ifpgfmathunitsdeclared with \else without \fi unit
252 \end{codeexample}
253
254 Note, however, that this command (currently) really just clears the \TeX-if
255 as the input is scanned from left-to-right. Thus, even if there is a use of
256 a unit before the |scalar| function is used, the \TeX-if will be cleared:
257 %
258 \begin{codeexample}[]
259 \pgfmathparse{1pt+scalar(1pt)} \pgfmathresult\
260 \ifpgfmathunitsdeclared with \else without \fi unit
261 \end{codeexample}
262
263 The other way round, a use of a unit after the |scalar| function will set
264 the units once more.
265 %
266 \begin{codeexample}[]
267 \pgfmathparse{scalar(1pt)+1pt} \pgfmathresult\
268 \ifpgfmathunitsdeclared with \else without \fi unit
269 \end{codeexample}
270
271 For these reasons, you should use the function only on the outermost level
272 of an expression.
273
274 A typical use of this function is the following:
275 %
276 \begin{codeexample}[preamble={\usetikzlibrary{calc,quotes}}]
277 \tikz{
278 \coordinate["$A$"] (A) at (2,2);
279 \coordinate["$B$" below] (B) at (0,0);
280 \coordinate["$C$" below] (C) at (3,0);
281 \draw (A) -- (B) -- (C) -- cycle;
282 \path
283 let \p1 =($(A)-(B)$), \p2 =($(A)-(C)$),
284 \n1 = {veclen(\x1,\y1)}, \n2 = {veclen(\x2,\y2)}
285 in coordinate ["$D$" below] (D) at ($ (B)!scalar(\n1/(\n1+\n2))!(C) $);
286 \draw (A) -- (D);
287 }
288 \end{codeexample}
289 %
290 \end{math-function}
291
292 A special kind of units are \TeX's ``math units'' (|mu|). It will be treated as
293 if |pt| had been used, but you can check whether an expression contained a math
294 unit using the following:
295 %
296 {\let\ifpgfmathmathunitsdeclared\relax
297 \begin{command}{\ifpgfmathmathunitsdeclared}
298 This \TeX-if is similar to |\ifpgfmathunitsdeclared|, but it
299 is only set when the unit |mu| is encountered at least
300 once. In this case, |\ifpgfmathunitsdeclared| will \emph{also}
301 be set to true. The |scalar| function has no effect on this \TeX-if.
302 \end{command}
303 }
304
305
306 \subsection{Syntax for Mathematical Expressions: Operators}
307
308 The syntax for the expressions recognized by |\pgfmathparse| and friends is
309 rather straightforward. Let us start with the operators.
310
311 \label{pgfmath-operators}
312
313 The following operators (presented in the context in which they are used) are
314 recognized:
315 %
316 \begin{math-operator}{+}{infix}{add}
317 Adds \mvar{x} to \mvar{y}.
318 \end{math-operator}
319
320 \begin{math-operator}{-}{infix}{subtract}
321 Subtracts \mvar{y} from \mvar{x}.
322 \end{math-operator}
323
324 \begin{math-operator}{-}{prefix}{neg}
325 Reverses the sign of \mvar{x}.
326 \end{math-operator}
327
328 \begin{math-operator}{*}{infix}{multiply}
329 Multiplies \mvar{x} by \mvar{y}.
330 \end{math-operator}
331
332 \begin{math-operator}{/}{infix}{divide}
333 Divides \mvar{x} by \mvar{y}. An error will result if \mvar{y} is 0, or if
334 the result of the division is too big for the mathematical engine. Please
335 remember when using this command that accurate (and reasonably quick)
336 division of real numbers that are not integers is particularly tricky in
337 \TeX.
338 \end{math-operator}
339
340 \begin{math-operator}{\char`\^}{infix}{pow}
341 Raises \mvar{x} to the power \mvar{y}.
342 \end{math-operator}
343
344 \begin{math-operator}{\protect\exclamationmarktext}{postfix}{factorial}
345 Calculates the factorial of \mvar{x}.
346 \end{math-operator}
347
348 \begin{math-operator}{r}{postfix}{deg}
349 Converts \mvar{x} to degrees (\mvar{x} is assumed to be in radians). This
350 operator has the same precedence as multiplication.
351 \end{math-operator}
352
353 \begin{math-operators}{?}{:}{conditional}{ifthenelse}
354 |?| and |:| are special operators which can be used as a shorthand for |if|
355 \mvar{x} |then| \mvar{y} |else| \mvar{z} inside the parser. The expression
356 \mvar{x} is taken to be true if it evaluates to any non-zero value.
357 \end{math-operators}
358
359 \begin{math-operator}{==}{infix}{equal}
360 Returns |1| if \mvar{x}$=$\mvar{y}, |0| otherwise.
361 \end{math-operator}
362
363 \begin{math-operator}{>}{infix}{greater}
364 Returns |1| if \mvar{x}$>$\mvar{y}, |0| otherwise.
365 \end{math-operator}
366
367 \begin{math-operator}{<}{infix}{less}
368 Returns |1| if \mvar{x}$<$\mvar{y}, |0| otherwise.
369 \end{math-operator}
370
371 \begin{math-operator}{\protect\exclamationmarktext=}{infix}{notequal}
372 Returns |1| if \mvar{x}$\neq$\mvar{y}, |0| otherwise.
373 \end{math-operator}
374
375 \begin{math-operator}{>=}{infix}{notless}
376 Returns |1| if \mvar{x}$\geq$\mvar{y}, |0| otherwise.
377 \end{math-operator}
378
379 \begin{math-operator}{<=}{infix}{notgreater}
380 Returns |1| if \mvar{x}$\leq$\mvar{y}, |0| otherwise.
381 \end{math-operator}
382
383 \begin{math-operator}{{\char`\&}{\char`\&}}{infix}{and}
384 Returns |1| if both \mvar{x} and \mvar{y} evaluate to some non-zero value.
385 Both arguments are evaluated.
386 \end{math-operator}
387
388 {
389 \catcode`\|=12
390 \begin{math-operator}[no index]{||}{infix}{or}
391 \index{*pgfmanualvbarvbarr@\protect\texttt{\protect\pgfmanualvbarvbar} math operator}%
392 \index{Math operators!*pgfmanualvbarvbar@\protect\texttt{\protect\pgfmanualvbarvbar}}%
393 Returns {\tt 1} if either \mvar{x} or \mvar{y} evaluate to some non-zero
394 value.
395 \end{math-operator}
396 }
397
398 \begin{math-operator}{\protect\exclamationmarktext}{prefix}{not}
399 Returns |1| if \mvar{x} evaluates to zero, |0| otherwise.
400 \end{math-operator}
401
402 \begin{math-operators}{(}{)}{group}{}
403 These operators act in the usual way, that is, to control the order in
404 which operators are executed, for example, |(1+2)*3|. This includes the
405 grouping of arguments for functions, for example, |sin(30*10)| or
406 |mod(72,3)| (the comma character is also treated as an operator).
407
408 Parentheses for functions with one argument are not always necessary,
409 |sin 30| (note the space) is the same as |sin(30)|. However, functions have
410 the highest precedence so, |sin 30*10| is the same as |sin(30)*10|.
411 \end{math-operators}
412
413 \begin{math-operators}{\char`\{}{\char`\}}{array}{}
414 These operators are used to process array-like structures (within an
415 expression these characters do not act like \TeX{} grouping tokens). The
416 \meta{array specification} consists of comma separated elements, for
417 example, |{1, 2, 3, 4, 5}|. Each element in the array will be evaluated as
418 it is parsed, so expressions can be used. In addition, an element of an
419 array can be an array itself, allowing multiple dimension arrays to be
420 simulated: |{1, {2,3}, {4,5}, 6}|. When storing an array in a macro, do not
421 forget the surrounding braces: |\def\myarray{{1,2,3}}| not
422 |\def\myarray{1,2,3}|.
423 %
424 \begin{codeexample}[]
425 \def\myarray{{1,"two",2+1,"IV","cinq","sechs",sin(\i*5)*14}}
426 \foreach \i in {0,...,6}{\pgfmathparse{\myarray[\i]}\pgfmathresult, }
427 \end{codeexample}
428 %
429 \end{math-operators}
430
431 \chardef\lbrack=`\[
432 \chardef\rbrack=`\]
433 \begin{math-operators}{\lbrack}{\rbrack}{array access}{array}
434 |[| and |]| are two operators used in one particular circumstance: to
435 access an array (specified using the |{| and |}| operators) using the index
436 \mvar{x}. Indexing starts from zero, so, if the index is greater than, or
437 equal to, the number of values in the array, an error will occur, and zero
438 will be returned.
439 %
440 \begin{codeexample}[]
441 \def\myarray{{7,-3,4,-9,11}}
442 \pgfmathparse{\myarray[3]} \pgfmathresult
443 \end{codeexample}
444
445 If the array is defined to have multiple dimensions, then the array access
446 operators can be immediately repeated.
447 %
448 \begin{codeexample}[]
449 \def\print#1{\pgfmathparse{#1}\pgfmathresult}
450 \def\identitymatrix{{{1,0,0},{0,1,0},{0,0,1}}}
451 \tikz[x=0.5cm,y=0.5cm]\foreach \i in {0,1,2} \foreach \j in {0,1,2}
452 \node at (\j,-\i) [anchor=base] {\print{\identitymatrix[\i][\j]}};
453 \end{codeexample}
454 %
455 \end{math-operators}
456
457 \begin{math-operators}{\char`\"}{\char`\"}{group}{}
458 These operators are used to quote \mvar{x}. However, as every expression is
459 expanded with |\edef| before it is parsed, macros (e.g., font commands like
460 |\tt| or |\Huge|) may need to be ``protected'' from this expansion (e.g.,
461 |\noexpand\Huge|). Ideally, you should avoid such macros anyway. Obviously,
462 these operators should be used with great care as further calculations are
463 unlikely to be possible with the result.
464 %
465 \begin{codeexample}[]
466 \def\x{5}
467 \foreach \y in {0,10}{
468 \pgfmathparse{\x > \y ? "\noexpand\Large Bigger" : "\noexpand\tiny smaller"}
469 \x\ is \pgfmathresult\ than \y.
470 }
471 \end{codeexample}
472 %
473 \end{math-operators}
474
475
476 \subsection{Syntax for Mathematical Expressions: Functions}
477 \label{pgfmath-functions}
478
479 The following functions are recognized:
480
481 \medskip
482 \def\mathlink#1{\hyperlink{math:#1}{\tt#1}}
483 \begin{tikzpicture}
484 \foreach \f [count=\i from 0] in
485 {abs,acos,add,and,array,asin,atan,atan2,bin,ceil,cos,
486 cosec,cosh,cot,deg,depth,dim,div,divide,e,equal,factorial, false,
487 floor,frac,gcd,greater,height,hex,Hex,int,ifthenelse,iseven,isodd,isprime,
488 less,ln,log10,log2,max,min,mod,Mod,multiply,
489 neg,not,notequal,notgreater,notless,
490 oct,or,pi,pow,rad,rand,random,real,rnd,round,
491 scalar,sec,sign,sin,sinh,sqrt,subtract,tan,tanh,true, veclen,width}
492 \node [anchor=base west] at ({int(\i/12)*2.5cm},{-mod(\i,12)*1.1*\baselineskip}) {\mathlink{\f}};
493 \end{tikzpicture}
494 \bigskip
495
496 Each function has a \pgfname{} command associated with it (which is also shown
497 with the function below). In general, the command is simply the name of the
498 function prefixed with |\pgfmath|, for example, |\pgfmathadd|, but there are
499 some notable exceptions.
500
501
502 \subsubsection{Basic arithmetic functions}
503 \label{pgfmath-functions-basic}
504
505 \begin{math-function}{add(\mvar{x},\mvar{y})}
506 \mathcommand
507 Adds $x$ and $y$.
508 %
509 \begin{codeexample}[]
510 \pgfmathparse{add(75,6)} \pgfmathresult
511 \end{codeexample}
512 %
513 \end{math-function}
514
515 \begin{math-function}{subtract(\mvar{x},\mvar{y})}
516 \mathcommand
517 Subtract $y$ from $x$.
518 %
519 \begin{codeexample}[]
520 \pgfmathparse{subtract(75,6)} \pgfmathresult
521 \end{codeexample}
522 %
523 \end{math-function}
524
525 \begin{math-function}{neg(\mvar{x})}
526 \mathcommand
527 This returns $-\mvar{x}$.
528 %
529 \begin{codeexample}[]
530 \pgfmathparse{neg(50)} \pgfmathresult
531 \end{codeexample}
532 %
533 \end{math-function}
534
535 \begin{math-function}{multiply(\mvar{x},\mvar{y})}
536 \mathcommand
537 Multiply $x$ by $y$.
538 %
539 \begin{codeexample}[]
540 \pgfmathparse{multiply(75,6)} \pgfmathresult
541 \end{codeexample}
542 %
543 \end{math-function}
544
545 \begin{math-function}{divide(\mvar{x},\mvar{y})}
546 \mathcommand
547 Divide $x$ by $y$.
548 %
549 \begin{codeexample}[]
550 \pgfmathparse{divide(75,6)} \pgfmathresult
551 \end{codeexample}
552 %
553 \end{math-function}
554
555 \begin{math-function}{div(\mvar{x},\mvar{y})}
556 \mathcommand
557 Divide $x$ by $y$ and return the integer part of the result.
558 %
559 \begin{codeexample}[]
560 \pgfmathparse{div(75,9)} \pgfmathresult
561 \end{codeexample}
562 %
563 \end{math-function}
564
565 \begin{math-function}{factorial(\mvar{x})}
566 \mathcommand
567 Return \mvar{x}!.
568 %
569 \begin{codeexample}[]
570 \pgfmathparse{factorial(5)} \pgfmathresult
571 \end{codeexample}
572 %
573 \end{math-function}
574
575 \begin{math-function}{sqrt(\mvar{x})}
576 \mathcommand
577 Calculates $\sqrt{\textrm{\mvar{x}}}$.
578 %
579 \begin{codeexample}[]
580 \pgfmathparse{sqrt(10)} \pgfmathresult
581 \end{codeexample}
582
583 \begin{codeexample}[]
584 \pgfmathparse{sqrt(8765.432)} \pgfmathresult
585 \end{codeexample}
586 %
587 \end{math-function}
588
589 \begin{math-function}{pow(\mvar{x},\mvar{y})}
590 \mathcommand
591 Raises \mvar{x} to the power \mvar{y}. For greatest accuracy, \mvar{y}
592 should be an integer. If \mvar{y} is not an integer, the actual calculation
593 will be an approximation of $e^{y \ln(x)}$.
594 %
595 \begin{codeexample}[]
596 \pgfmathparse{pow(2,7)} \pgfmathresult
597 \end{codeexample}
598 %
599 \end{math-function}
600
601 \begin{math-function}{e}
602 \mathcommand
603 Returns the value 2.718281828.
604 %
605 {
606 \catcode`\^=7
607 \begin{codeexample}[]
608 \pgfmathparse{(e^2-e^-2)/2} \pgfmathresult
609 \end{codeexample}
610 }
611 \end{math-function}
612
613 \begin{math-function}{exp(\mvar{x})}
614 \mathcommand
615 { \catcode`\^=7
616
617 Maclaurin series for $e^x$.
618 }
619 \begin{codeexample}[]
620 \pgfmathparse{exp(1)} \pgfmathresult
621 \end{codeexample}
622
623 \begin{codeexample}[]
624 \pgfmathparse{exp(2.34)} \pgfmathresult
625 \end{codeexample}
626 %
627 \end{math-function}
628
629 \begin{math-function}{ln(\mvar{x})}
630 \mathcommand
631 { \catcode`\^=7
632 An approximation for $\ln(\textrm{\mvar{x}})$. This uses an algorithm of
633 Rouben Rostamian, and coefficients suggested by Alain Matthes.
634 }
635 \begin{codeexample}[]
636 \pgfmathparse{ln(10)} \pgfmathresult
637 \end{codeexample}
638
639 \begin{codeexample}[]
640 \pgfmathparse{ln(exp(5))} \pgfmathresult
641 \end{codeexample}
642 %
643 \end{math-function}
644
645 \begin{math-function}{log10(\mvar{x})}
646 \mathcommand[logten(\mvar{x})]
647 An approximation for $\log_{10}(\textrm{\mvar{x}})$.
648 %
649 \begin{codeexample}[]
650 \pgfmathparse{log10(100)} \pgfmathresult
651 \end{codeexample}
652 %
653 \end{math-function}
654
655 \begin{math-function}{log2(\mvar{x})}
656 \mathcommand[logtwo(\mvar{x})]
657 An approximation for $\log_2(\textrm{\mvar{x}})$.
658 %
659 \begin{codeexample}[]
660 \pgfmathparse{log2(128)} \pgfmathresult
661 \end{codeexample}
662 %
663 \end{math-function}
664
665 \begin{math-function}{abs(\mvar{x})}
666 \mathcommand
667 Evaluates the absolute value of $x$.
668 %
669 \begin{codeexample}[]
670 \pgfmathparse{abs(-5)} \pgfmathresult
671 \end{codeexample}
672
673 \begin{codeexample}[]
674 \pgfmathparse{-abs(4*-3)} \pgfmathresult
675 \end{codeexample}
676 %
677 \end{math-function}
678
679 \begin{math-function}{mod(\mvar{x},\mvar{y})}
680 \mathcommand
681 This evaluates \mvar{x} modulo \mvar{y}, using truncated division. The sign
682 of the result is the same as the sign of
683 $\frac{\textrm{\mvar{x}}}{\textrm{\mvar{y}}}$.
684 %
685 \begin{codeexample}[]
686 \pgfmathparse{mod(20,6)} \pgfmathresult
687 \end{codeexample}
688
689 \begin{codeexample}[]
690 \pgfmathparse{mod(-100,30)} \pgfmathresult
691 \end{codeexample}
692 %
693 \end{math-function}
694
695 \begin{math-function}{Mod(\mvar{x},\mvar{y})}
696 \mathcommand
697 This evaluates \mvar{x} modulo \mvar{y}, using floored division. The sign
698 of the result is never negative.
699 %
700 \begin{codeexample}[]
701 \pgfmathparse{Mod(-100,30)} \pgfmathresult
702 \end{codeexample}
703 %
704 \end{math-function}
705
706 \begin{math-function}{sign(\mvar{x})}
707 \mathcommand
708 Returns the sign of $x$.
709 %
710 \begin{codeexample}[]
711 \pgfmathparse{sign(-5)} \pgfmathresult
712 \end{codeexample}
713
714 \begin{codeexample}[]
715 \pgfmathparse{sign(0)} \pgfmathresult
716 \end{codeexample}
717
718 \begin{codeexample}[]
719 \pgfmathparse{sign(5)} \pgfmathresult
720 \end{codeexample}
721 %
722 \end{math-function}
723
724
725 \subsubsection{Rounding functions}
726 \label{pgfmath-functions-rounding}
727
728 \begin{math-function}{round(\mvar{x})}
729 \mathcommand
730 Rounds \mvar{x} to the nearest integer. It uses ``asymmetric half-up''
731 rounding. So |1.5| is rounded to |2|, but |-1.5| is rounded to |-2|
732 (\emph{not} |-1|).
733 %
734 \begin{codeexample}[]
735 \pgfmathparse{round(32.5/17)} \pgfmathresult
736 \end{codeexample}
737
738 \begin{codeexample}[]
739 \pgfmathparse{round(398/12)} \pgfmathresult
740 \end{codeexample}
741 %
742 \end{math-function}
743
744 \begin{math-function}{floor(\mvar{x})}
745 \mathcommand
746 Rounds \mvar{x} down to the nearest integer.
747 %
748 \begin{codeexample}[]
749 \pgfmathparse{floor(32.5/17)} \pgfmathresult
750 \end{codeexample}
751
752 \begin{codeexample}[]
753 \pgfmathparse{floor(398/12)} \pgfmathresult
754 \end{codeexample}
755
756 \begin{codeexample}[]
757 \pgfmathparse{floor(-398/12)} \pgfmathresult
758 \end{codeexample}
759 %
760 \end{math-function}
761
762 \begin{math-function}{ceil(\mvar{x})}
763 \mathcommand
764 Rounds \mvar{x} up to the nearest integer.
765 %
766 \begin{codeexample}[]
767 \pgfmathparse{ceil(32.5/17)} \pgfmathresult
768 \end{codeexample}
769
770 \begin{codeexample}[]
771 \pgfmathparse{ceil(398/12)} \pgfmathresult
772 \end{codeexample}
773
774 \begin{codeexample}[]
775 \pgfmathparse{ceil(-398/12)} \pgfmathresult
776 \end{codeexample}
777 %
778 \end{math-function}
779
780 \begin{math-function}{int(\mvar{x})}
781 \mathcommand
782 Returns the integer part of \mvar{x}.
783 %
784 \begin{codeexample}[]
785 \pgfmathparse{int(32.5/17)} \pgfmathresult
786 \end{codeexample}
787 %
788 \end{math-function}
789
790 \begin{math-function}{frac(\mvar{x})}
791 \mathcommand
792 Returns the fractional part of \mvar{x}.
793 %
794 \begin{codeexample}[]
795 \pgfmathparse{frac(32.5/17)} \pgfmathresult
796 \end{codeexample}
797 %
798 \end{math-function}
799
800 \begin{math-function}{real(\mvar{x})}
801 \mathcommand
802 Ensures \mvar{x} contains a decimal point.
803 %
804 \begin{codeexample}[]
805 \pgfmathparse{real(4)} \pgfmathresult
806 \end{codeexample}
807 %
808 \end{math-function}
809
810
811 \subsubsection{Integer arithmetic functions}
812 \label{pgfmath-functions-integerarithmetic}
813
814 \begin{math-function}{gcd(\mvar{x},\mvar{y})}
815 \mathcommand
816 Computes the greatest common divider of \mvar{x} and \mvar{y}.
817 %
818 \begin{codeexample}[]
819 \pgfmathparse{gcd(42,56)} \pgfmathresult
820 \end{codeexample}
821 %
822 \end{math-function}
823
824 \begin{math-function}{isodd(\mvar{x})}
825 \mathcommand
826 Returns |1| if the integer part of \mvar{x} is odd. Otherwise, returns |0|.
827 %
828 \begin{codeexample}[]
829 \pgfmathparse{isodd(2)} \pgfmathresult,
830 \pgfmathparse{isodd(3)} \pgfmathresult
831 \end{codeexample}
832 %
833 \end{math-function}
834
835 \begin{math-function}{iseven(\mvar{x})}
836 \mathcommand
837 Returns |1| if the integer part of \mvar{x} is even. Otherwise, returns |0|.
838 %
839 \begin{codeexample}[]
840 \pgfmathparse{iseven(2)} \pgfmathresult,
841 \pgfmathparse{iseven(3)} \pgfmathresult
842 \end{codeexample}
843 %
844 \end{math-function}
845
846 \begin{math-function}{isprime(\mvar{x})}
847 \mathcommand
848 Returns |1| if the integer part of \mvar{x} is prime. Otherwise, returns |0|.
849 %
850 \begin{codeexample}[]
851 \pgfmathparse{isprime(1)} \pgfmathresult,
852 \pgfmathparse{isprime(2)} \pgfmathresult,
853 \pgfmathparse{isprime(31)} \pgfmathresult,
854 \pgfmathparse{isprime(64)} \pgfmathresult
855 \end{codeexample}
856 %
857 \end{math-function}
858
859
860 \subsubsection{Trigonometric functions}
861 \label{pgfmath-functions-trigonometric}
862
863 \begin{math-function}{pi}
864 \mathcommand
865 Returns the value $\pi=3.141592654$.
866 %
867 \begin{codeexample}[]
868 \pgfmathparse{pi} \pgfmathresult
869 \end{codeexample}
870
871 \begin{codeexample}[]
872 \pgfmathparse{pi r} \pgfmathresult
873 \end{codeexample}
874 %
875 \end{math-function}
876
877 \begin{math-function}{rad(\mvar{x})}
878 \mathcommand
879 Convert \mvar{x} to radians. \mvar{x} is assumed to be in degrees.
880 %
881 \begin{codeexample}[]
882 \pgfmathparse{rad(90)} \pgfmathresult
883 \end{codeexample}
884 %
885 \end{math-function}
886
887 \begin{math-function}{deg(\mvar{x})}
888 \mathcommand
889 Convert \mvar{x} to degrees. \mvar{x} is assumed to be in radians.
890 %
891 \begin{codeexample}[]
892 \pgfmathparse{deg(3*pi/2)} \pgfmathresult
893 \end{codeexample}
894 %
895 \end{math-function}
896
897 \begin{math-function}{sin(\mvar{x})}
898 \mathcommand
899 %
900 Sine of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
901 radians.
902 %
903 \begin{codeexample}[]
904 \pgfmathparse{sin(60)} \pgfmathresult
905 \end{codeexample}
906
907 \begin{codeexample}[]
908 \pgfmathparse{sin(pi/3 r)} \pgfmathresult
909 \end{codeexample}
910 %
911 \end{math-function}
912
913 \begin{math-function}{cos(\mvar{x})}
914 \mathcommand
915 Cosine of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
916 radians.
917 %
918 \begin{codeexample}[]
919 \pgfmathparse{cos(60)} \pgfmathresult
920 \end{codeexample}
921
922 \begin{codeexample}[]
923 \pgfmathparse{cos(pi/3 r)} \pgfmathresult
924 \end{codeexample}
925 %
926 \end{math-function}
927
928 \begin{math-function}{tan(\mvar{x})}
929 \mathcommand
930 Tangent of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
931 radians.
932 %
933 \begin{codeexample}[]
934 \pgfmathparse{tan(45)} \pgfmathresult
935 \end{codeexample}
936
937 \begin{codeexample}[]
938 \pgfmathparse{tan(2*pi/8 r)} \pgfmathresult
939 \end{codeexample}
940 %
941 \end{math-function}
942
943 \begin{math-function}{sec(\mvar{x})}
944 \mathcommand
945 Secant of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
946 radians.
947 %
948 \begin{codeexample}[]
949 \pgfmathparse{sec(45)} \pgfmathresult
950 \end{codeexample}
951 %
952 \end{math-function}
953
954 \begin{math-function}{cosec(\mvar{x})}
955 \mathcommand
956 Cosecant of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
957 radians.
958 %
959 \begin{codeexample}[]
960 \pgfmathparse{cosec(30)} \pgfmathresult
961 \end{codeexample}
962 %
963 \end{math-function}
964
965 \begin{math-function}{cot(\mvar{x})}
966 \mathcommand
967 Cotangent of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
968 radians.
969 %
970 \begin{codeexample}[]
971 \pgfmathparse{cot(15)} \pgfmathresult
972 \end{codeexample}
973 %
974 \end{math-function}
975
976 \begin{math-function}{asin(\mvar{x})}
977 \mathcommand
978 Arcsine of \mvar{x}. The result is in degrees and in the range $\pm90^\circ$.
979 %
980 \begin{codeexample}[]
981 \pgfmathparse{asin(0.7071)} \pgfmathresult
982 \end{codeexample}
983 %
984 \end{math-function}
985
986 \begin{math-function}{acos(\mvar{x})}
987 \mathcommand
988 Arccosine of \mvar{x} in degrees. The result is in the range $[0^\circ,180^\circ]$.
989 %
990 \begin{codeexample}[]
991 \pgfmathparse{acos(0.5)} \pgfmathresult
992 \end{codeexample}
993 %
994 \end{math-function}
995
996 \begin{math-function}{atan(\mvar{x})}
997 \mathcommand
998 Arctangent of $x$ in degrees.
999 %
1000 \begin{codeexample}[]
1001 \pgfmathparse{atan(1)} \pgfmathresult
1002 \end{codeexample}
1003 %
1004 \end{math-function}
1005
1006 \begin{math-function}{atan2(\mvar{y},\mvar{x})}
1007 \mathcommand[atantwo(\mvar{y},\mvar{x})]
1008 Arctangent of $y\div x$ in degrees. This also takes into account the
1009 quadrants.
1010 %
1011 \begin{codeexample}[]
1012 \pgfmathparse{atan2(-4,3)} \pgfmathresult
1013 \end{codeexample}
1014 %
1015 \end{math-function}
1016
1017 \begin{key}{/pgf/trig format=\mchoice{deg,rad} (initially deg)}
1018 Allows to define whether trigonometric math functions (i.e.\ all in this
1019 subsection) operate with degrees or with radians.
1020 %
1021 \begin{codeexample}[]
1022 \pgfmathparse{cos(45)} \pgfmathresult
1023 \end{codeexample}
1024 \begin{codeexample}[]
1025 \pgfkeys{/pgf/trig format=rad}
1026 \pgfmathparse{cos(pi/2)} \pgfmathresult
1027 \end{codeexample}
1028
1029 The initial configuration |trig format=deg| is the base of \pgfname: almost
1030 all of it is based on degrees.
1031
1032 Specifying |trig format=rad| is most useful for data visualization where
1033 the angles are typically given in radians. However, it is applied to all
1034 trigonometric functions for which the option applies, including any drawing
1035 instructions which operate on angles.
1036 %
1037 \begin{codeexample}[]
1038 \begin{tikzpicture}
1039 \draw[-stealth]
1040 (0:1) -- (45:1) -- (90:1) -- (135:1) -- (180:1);
1041
1042 \draw[-stealth,trig format=rad,red]
1043 (pi:1) -- (5/4*pi:1) -- (6/4*pi:1) -- (7/4*pi:1) -- (2*pi:1);
1044 \end{tikzpicture}
1045 \end{codeexample}
1046
1047 \paragraph{Warning:}
1048 At the time of this writing, this feature is ``experimental''. Please
1049 handle it with care: there may be path instructions or libraries in
1050 \pgfname\ which rely on |trig format=deg|. The intended usage of
1051 |trig format=rad| is for local scopes -- and as option for data
1052 visualization.
1053 \end{key}
1054
1055
1056 \subsubsection{Comparison and logical functions}
1057 \label{pgfmath-functions-comparison}
1058
1059 \begin{math-function}{equal(\mvar{x},\mvar{y})}
1060 \mathcommand
1061 This returns |1| if $\mvar{x}=\mvar{y}$ and |0| otherwise.
1062 %
1063 \begin{codeexample}[]
1064 \pgfmathparse{equal(20,20)} \pgfmathresult
1065 \end{codeexample}
1066 %
1067 \end{math-function}
1068
1069 \begin{math-function}{greater(\mvar{x},\mvar{y})}
1070 \mathcommand
1071 This returns |1| if $\mvar{x}>\mvar{y}$ and |0| otherwise.
1072 %
1073 \begin{codeexample}[]
1074 \pgfmathparse{greater(20,25)} \pgfmathresult
1075 \end{codeexample}
1076 %
1077 \end{math-function}
1078
1079 \begin{math-function}{less(\mvar{x},\mvar{y})}
1080 \mathcommand
1081 This returns |1| if $\mvar{x}<\mvar{y}$ and |0| otherwise.
1082 %
1083 \begin{codeexample}[]
1084 \pgfmathparse{less(20,25)} \pgfmathresult
1085 \end{codeexample}
1086 %
1087 \end{math-function}
1088
1089 \begin{math-function}{notequal(\mvar{x},\mvar{y})}
1090 \mathcommand
1091 This returns |0| if $\mvar{x}=\mvar{y}$ and |1| otherwise.
1092 %
1093 \begin{codeexample}[]
1094 \pgfmathparse{notequal(20,25)} \pgfmathresult
1095 \end{codeexample}
1096 %
1097 \end{math-function}
1098
1099 \begin{math-function}{notgreater(\mvar{x},\mvar{y})}
1100 \mathcommand
1101 This returns |1| if $\mvar{x}\leq\mvar{y}$ and |0| otherwise.
1102 %
1103 \begin{codeexample}[]
1104 \pgfmathparse{notgreater(20,25)} \pgfmathresult
1105 \end{codeexample}
1106 %
1107 \end{math-function}
1108
1109 \begin{math-function}{notless(\mvar{x},\mvar{y})}
1110 \mathcommand
1111 This returns |1| if $\mvar{x}\geq\mvar{y}$ and |0| otherwise.
1112 %
1113 \begin{codeexample}[]
1114 \pgfmathparse{notless(20,25)} \pgfmathresult
1115 \end{codeexample}
1116 %
1117 \end{math-function}
1118
1119 \begin{math-function}{and(\mvar{x},\mvar{y})}
1120 \mathcommand
1121 This returns |1| if \mvar{x} and \mvar{y} both evaluate to non-zero values.
1122 Otherwise |0| is returned.
1123 %
1124 \begin{codeexample}[]
1125 \pgfmathparse{and(5>4,6>7)} \pgfmathresult
1126 \end{codeexample}
1127 %
1128 \end{math-function}
1129
1130 \begin{math-function}{or(\mvar{x},\mvar{y})}
1131 \mathcommand
1132 This returns |1| if either \mvar{x} or \mvar{y} evaluate to non-zero
1133 values. Otherwise |0| is returned.
1134 %
1135 \begin{codeexample}[]
1136 \pgfmathparse{or(5>4,6>7)} \pgfmathresult
1137 \end{codeexample}
1138 %
1139 \end{math-function}
1140
1141 \begin{math-function}{not(\mvar{x})}
1142 \mathcommand
1143 This returns |1| if $\mvar{x}=0$, otherwise |0|.
1144 %
1145 \begin{codeexample}[]
1146 \pgfmathparse{not(true)} \pgfmathresult
1147 \end{codeexample}
1148 %
1149 \end{math-function}
1150
1151 \begin{math-function}{ifthenelse(\mvar{x},\mvar{y},\mvar{z})}
1152 \mathcommand
1153 This returns \mvar{y} if \mvar{x} evaluates to some non-zero value,
1154 otherwise \mvar{z} is returned.
1155 %
1156 \begin{codeexample}[]
1157 \pgfmathparse{ifthenelse(5==4,"yes","no")} \pgfmathresult
1158 \end{codeexample}
1159 %
1160 \end{math-function}
1161
1162 \begin{math-function}{true}
1163 \mathcommand
1164 This evaluates to |1|.
1165 %
1166 \begin{codeexample}[]
1167 \pgfmathparse{true ? "yes" : "no"} \pgfmathresult
1168 \end{codeexample}
1169 %
1170 \end{math-function}
1171
1172 \begin{math-function}{false}
1173 \mathcommand
1174 This evaluates to |0|.
1175 %
1176 \begin{codeexample}[]
1177 \pgfmathparse{false ? "yes" : "no"} \pgfmathresult
1178 \end{codeexample}
1179 %
1180 \end{math-function}
1181
1182
1183 \subsubsection{Pseudo-random functions}
1184 \label{pgfmath-functions-random}
1185
1186 \begin{math-function}{rnd}
1187 \mathcommand
1188 Generates a pseudo-random number between $0$ and $1$ with a uniform
1189 distribution.
1190 %
1191 \begin{codeexample}[pre={\pgfmathsetseed{1}}]
1192 \foreach \x in {1,...,10}{\pgfmathparse{rnd}\pgfmathresult, }
1193 \end{codeexample}
1194 %
1195 \end{math-function}
1196
1197 \begin{math-function}{rand}
1198 \mathcommand
1199 Generates a pseudo-random number between $-1$ and $1$ with a uniform
1200 distribution.
1201 %
1202 \begin{codeexample}[pre={\pgfmathsetseed{1}}]
1203 \foreach \x in {1,...,10}{\pgfmathparse{rand}\pgfmathresult, }
1204 \end{codeexample}
1205 %
1206 \end{math-function}
1207
1208 \begin{math-function}{random(\opt{\mvar{x},\mvar{y}})}
1209 \mathcommand
1210 This function takes zero, one or two arguments. If there are zero
1211 arguments, a uniform random number between $0$ and $1$ is generated. If
1212 there is one argument \mvar{x}, a random integer between $1$ and \mvar{x}
1213 is generated. Finally, if there are two arguments, a random integer between
1214 \mvar{x} and \mvar{y} is generated. If there are no arguments, the
1215 \pgfname{} command should be called as follows: |\pgfmathrandom{}|.
1216 %
1217 \begin{codeexample}[pre={\pgfmathsetseed{1}}]
1218 \foreach \x in {1,...,10}{\pgfmathparse{random()}\pgfmathresult, }
1219 \end{codeexample}
1220
1221 \begin{codeexample}[pre={\pgfmathsetseed{1}}]
1222 \foreach \x in {1,...,10}{\pgfmathparse{random(100)}\pgfmathresult, }
1223 \end{codeexample}
1224
1225 \begin{codeexample}[pre={\pgfmathsetseed{1}}]
1226 \foreach \x in {1,...,10}{\pgfmathparse{random(232,762)}\pgfmathresult, }
1227 \end{codeexample}
1228 %
1229 \end{math-function}
1230
1231
1232 \subsubsection{Base conversion functions}
1233 \label{pgfmath-functions-base}
1234
1235 \begin{math-function}{hex(\mvar{x})}
1236 \mathcommand
1237 Convert \mvar{x}{} (assumed to be an integer in base 10) to a hexadecimal
1238 representation, using lower case alphabetic digits. No further calculation
1239 will be possible with the result.
1240 %
1241 \begin{codeexample}[]
1242 \pgfmathparse{hex(65535)} \pgfmathresult
1243 \end{codeexample}
1244 %
1245 \end{math-function}
1246
1247 \begin{math-function}{Hex(\mvar{x})}
1248 \mathcommand
1249 Convert \mvar{x}{} (assumed to be an integer in base 10) to a hexadecimal
1250 representation, using upper case alphabetic digits. No further calculation
1251 will be possible with the result.
1252 %
1253 \begin{codeexample}[]
1254 \pgfmathparse{Hex(65535)} \pgfmathresult
1255 \end{codeexample}
1256 %
1257 \end{math-function}
1258
1259 \begin{math-function}{oct(\mvar{x})}
1260 \mathcommand
1261 Convert \mvar{x}{} (assumed to be an integer in base 10) to an octal
1262 representation. No further calculation should be attempted with the result,
1263 as the parser can only process numbers converted to base 10.
1264 %
1265 \begin{codeexample}[]
1266 \pgfmathparse{oct(63)} \pgfmathresult
1267 \end{codeexample}
1268 %
1269 \end{math-function}
1270
1271 \begin{math-function}{bin(\mvar{x})}
1272 \mathcommand
1273 Convert \mvar{x}{} (assumed to be an integer in base 10) to a binary
1274 representation. No further calculation should be attempted with the result,
1275 as the parser can only process numbers converted to base 10.
1276 %
1277 \begin{codeexample}[]
1278 \pgfmathparse{bin(185)} \pgfmathresult
1279 \end{codeexample}
1280 %
1281 \end{math-function}
1282
1283
1284 \subsubsection{Miscellaneous functions}
1285 \label{pgfmath-functions-misc}
1286
1287 \begin{math-function}{min(\mvar{x$_1$},\mvar{x$_2$},\ldots,\mvar{x$_n$})}
1288 \mathcommand[min({\mvar{x$_1$},\mvar{x$_2$},\ldots},{\ldots,\mvar{x$_{n-1}$},\mvar{x$_n$}})]
1289 Return the minimum value from \mvar{x$_1$}\ldots\mvar{x$_n$}. For
1290 historical reasons, the command |\pgfmathmin| takes two arguments, but each
1291 of these can contain an arbitrary number of comma separated values.
1292 %
1293 \begin{codeexample}[]
1294 \pgfmathparse{min(3,4,-2,250,-8,100)} \pgfmathresult
1295 \end{codeexample}
1296 %
1297 \end{math-function}
1298
1299 \begin{math-function}{max(\mvar{x$_1$},\mvar{x$_2$},\ldots,\mvar{x$_n$})}
1300 \mathcommand[max({\mvar{x$_1$},\mvar{x$_2$},\ldots},{\ldots,\mvar{x$_{n-1}$},\mvar{x$_n$}})]
1301 Return the maximum value from \mvar{x$_1$}\ldots\mvar{x$_n$}. Again, for
1302 historical reasons, the command |\pgfmathmax| takes two arguments, but each
1303 of these can contain an arbitrary number of comma separated values.
1304 %
1305 \begin{codeexample}[]
1306 \pgfmathparse{max(3,4,-2,250,-8,100)} \pgfmathresult
1307 \end{codeexample}
1308 %
1309 \end{math-function}
1310
1311 \begin{math-function}{veclen(\mvar{x},\mvar{y})}
1312 \mathcommand
1313 Calculates $\sqrt{\left(\textrm{\mvar{x}}^2+\textrm{\mvar{y}}^2\right)}$.
1314 This uses a polynomial approximation, based on ideas of Rouben Rostamian
1315 %
1316 \begin{codeexample}[]
1317 \pgfmathparse{veclen(12,5)} \pgfmathresult
1318 \end{codeexample}
1319 %
1320 \end{math-function}
1321
1322 \begin{math-function}{array(\mvar{x},\mvar{y})}
1323 \mathcommand
1324 This accesses the array \mvar{x} at the index \mvar{y}. The array must
1325 begin and end with braces (e.g., |{1,2,3,4}|) and array indexing starts at
1326 |0|.
1327 %
1328 \begin{codeexample}[]
1329 \pgfmathparse{array({9,13,17,21},2)} \pgfmathresult
1330 \end{codeexample}
1331 %
1332 \end{math-function}
1333
1334 \begin{math-function}{dim(\mvar{x})}
1335 \mathcommand
1336 This returns the dimension of the array \mvar{x}. The array must begin and
1337 end with braces (e.g., |{1,2,3,4}|).
1338 %
1339 \begin{codeexample}[]
1340 \pgfmathparse{dim({1,2,3,4})} \pgfmathresult
1341 \end{codeexample}
1342 %
1343 \end{math-function}
1344
1345 The following hyperbolic functions were adapted from code suggested by Martin
1346 Heller:
1347
1348 \begin{math-function}{sinh(\mvar{x})}
1349 \mathcommand
1350 The hyperbolic sine of \mvar{x}
1351 %
1352 \begin{codeexample}[]
1353 \pgfmathparse{sinh(0.5)} \pgfmathresult
1354 \end{codeexample}
1355 %
1356 \end{math-function}
1357
1358 \begin{math-function}{cosh(\mvar{x})}
1359 \mathcommand
1360 The hyperbolic cosine of \mvar{x}
1361 %
1362 \begin{codeexample}[]
1363 \pgfmathparse{cosh(0.5)} \pgfmathresult
1364 \end{codeexample}
1365 %
1366 \end{math-function}
1367
1368 \begin{math-function}{tanh(\mvar{x})}
1369 \mathcommand
1370 The hyperbolic tangent of \mvar{x}
1371 %
1372
1373 \begin{codeexample}[]
1374 \pgfmathparse{tanh(0.5)} \pgfmathresult
1375 \end{codeexample}
1376 %
1377 \end{math-function}
1378
1379 \begin{math-function}{width("\mvar{x}")}
1380 \mathcommand
1381 Return the width of a \TeX{} (horizontal) box containing \mvar{x}. The
1382 quote characters are necessary to prevent \mvar{x}{} from being parsed. It
1383 is important to remember that any expression is expanded with |\edef|
1384 before being parsed, so any macros (e.g., font commands like |\tt| or
1385 |\Huge|) will need to be ``protected'' (e.g., |\noexpand\Huge| is usually
1386 sufficient).
1387 %
1388 \begin{codeexample}[]
1389 \pgfmathparse{width("Some Lovely Text")} \pgfmathresult
1390 \end{codeexample}
1391
1392 Note that results of this method are provided in points.
1393 \end{math-function}
1394
1395 \begin{math-function}{height("\mvar{x}")}
1396 \mathcommand
1397 Return the height of a box containing \mvar{x}.
1398 %
1399 \begin{codeexample}[]
1400 \pgfmathparse{height("Some Lovely Text")} \pgfmathresult
1401 \end{codeexample}
1402 %
1403 \end{math-function}
1404
1405 \begin{math-function}{depth("\mvar{x}")}
1406 \mathcommand
1407 Returns the depth of a box containing \mvar{x}.
1408 %
1409 \begin{codeexample}[]
1410 \pgfmathparse{depth("Some Lovely Text")} \pgfmathresult
1411 \end{codeexample}
1412 %
1413 \end{math-function}