summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex285
1 files changed, 204 insertions, 81 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex
index 1d28cfa4fea..37df357e706 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex
@@ -13,14 +13,14 @@
The easiest way of using \pgfname's mathematical engine is to provide
a mathematical expression given in familiar infix notation, for
example, |1cm+4*2cm/5.5| or |2*3+3*sin(30)|. This expression can be
-parsed by the mathematical engine and the result be placed in a
+parsed by the mathematical engine and the result can be placed in a
dimension register, a counter, or a macro.
It should be noted that all
calculations must not exceed $\pm16383.99999$ at \emph{any} point,
because the underlying computations rely on \TeX{} dimensions. This
means that many of the underlying computations are necessarily
-approximate and that in addition, are not very fast. \TeX{} is,
+approximate and, in addition, not very fast. \TeX{} is,
after all, a typesetting language and not ideally
suited to relatively advanced mathematical operations. However, it
is possible to change the computations as described in
@@ -53,56 +53,77 @@ engine is the following:
\begin{itemize}
\item
- The result stored in the macro |\pgfmathresult| is a decimal
- \emph{without units}. This is true regardless of whether the
- \meta{expression} contains any unit specification. All numbers
- with units are converted to points first.
-
+ The result stored in the macro |\pgfmathresult| is a decimal
+ \emph{without units}. This is true regardless of whether the
+ \meta{expression} contains any unit specification. All numbers
+ with units are converted to points first.
+ You can check whether an expression contained a unit using
+ the following \TeX-if.
+ {\let\ifpgfmathunitsdeclared\relax
+ \begin{command}{\ifpgfmathunitsdeclared}
+ After a call of |\pgfmathparse| this if will be true exactly if
+ some unit was encountered in the expression. It is always set
+ globally in each call.
+ \end{command}
+ }
+
+ A special kind of units are \TeX's ``math units'' (|mu|). It will
+ be treated as if |pt| had been used, but you can
+ check whether an expression contained a math unit using the
+ following:
+ {\let\ifpgfmathmathunitsdeclared\relax
+ \begin{command}{\ifpgfmathmathunitsdeclared}
+ This \TeX-if is similar to |\ifpgfmathunitsdeclared|, but it
+ is only set when the unit |mu| is encountered at least
+ once. In this case, |\ifpgfmathunitsdeclared| will \emph{also}
+ be set to true.
+ \end{command}
+ }
\item
- You can check whether an expression contained a unit using
- the \TeX-if |\||ifpgfmathunitsdeclared|. After a call
- of |\pgfmathparse| this if will be true exactly if some unit was
- encountered in the expression.
-
+ The parser will recognize \TeX{} registers and box dimensions,
+ so |\mydimen|, |0.5\mydimen|, |\wd\mybox|, |0.5\dp\mybox|,
+ |\mycount\mydimen| and so on can be parsed.
+
\item
- The parser can recognize \TeX{} registers and box dimensions,
- so |\mydimen|, |0.5\mydimen|, |\wd\mybox|, |0.5\dp\mybox|,
- |\mycount\mydimen| and so on can be parsed.
-
+ The $\varepsilon$-TeX\ extensions |\dimexpr|, |\numexpr|, |\glueexpr|, and
+ |\muexpr| are recognized and evaluated. The values they
+ result in will be used in the further evaluation, as if you had
+ put |\the| before them.
+
\item
- Parenthesis can be used to change the order of the evaluation.
-
+ Parenthesis can be used to change the order of the evaluation.
+
\item
- Various functions are recognized, so it is possible to parse
- |sin(.5*pi r)*60|, which means ``the sine of $0.5$ times $\pi$
- radians, multiplied by 60''. The argument of functions can
- be any expression.
-
+ Various functions are recognized, so it is possible to parse
+ |sin(.5*pi r)*60|, which means ``the sine of $0.5$ times $\pi$
+ radians, multiplied by 60''. The argument of functions can
+ be any expression.
+
\item
- Scientific notation in the form |1.234e+4| is recognized (but
- the restriction on the range of values still applies). The exponent
- symbol can be upper or lower case (i.e., |E| or |e|).
-
+ Scientific notation in the form |1.234e+4| is recognized (but
+ the restriction on the range of values still applies). The exponent
+ symbol can be upper or lower case (i.e., |E| or |e|).
+
\item
- An integer with a zero-prefix (excluding, of course zero itself),
- is interpreted as an octal number and is automatically converted
- to base 10.
-
+ An integer with a zero-prefix (excluding, of course zero itself),
+ is interpreted as an octal number and is automatically converted
+ to base 10.
+
\item
- An integer with prefix |0x| or |0X| is interpreted as a hexadecimal
- number and is automatically converted to base 10. Alphabetic digits
- can be in uppercase or lowercase.
-
- \item
- An integer with prefix |0b| or |0B| is interpreted as a binary
- number and is automatically converted to base 10.
-
+ An integer with prefix |0x| or |0X| is interpreted as a hexadecimal
+ number and is automatically converted to base 10. Alphabetic digits
+ can be in uppercase or lowercase.
+
\item
- An expression (or part of an expression) surrounded with double
- quotes (i.e., the character |"|) will not be evaluated.
- Obviously this should be used with great care.
-
-\end{itemize}
+ An integer with prefix |0b| or |0B| is interpreted as a binary
+ number and is automatically converted to base 10.
+
+ \item
+ An expression (or part of an expression) surrounded with double
+ quotes (i.e., the character |"|) will not be evaluated.
+ Obviously this should be used with great care.
+
+ \end{itemize}
\end{command}
@@ -127,9 +148,9 @@ engine is the following:
At the end of the parse this command is executed, allowing some
custom action to be performed on the result of the parse. When this
- command is executed the macro |\pgfmathresult| will hold the result
- of the parse (as ever, without units). The result of the custom
- action should be to redefined |\pgfmathresult| appropriately.
+ command is executed, the macro |\pgfmathresult| will hold the result
+ of the parse (as always, without units). The result of the custom
+ action should be used to redefine |\pgfmathresult| appropriately.
By default, this command is equivalent to |\relax|. This differs
from previous versions, where, if the parsed expression contained
no units, the result of the parse was scaled according to the value
@@ -143,7 +164,7 @@ engine is the following:
\end{command}
-Instead of the |\pgfmathparse| macro you can also wrapper commands,
+Instead of the |\pgfmathparse| macro you can also use wrapper commands,
whose usage is very similar to their cousins in the \calcname{}
package. The only difference is that the expressions can be any
expression that is handled by |\pgfmathparse|.
@@ -152,15 +173,57 @@ For all of the following commands, if \meta{expression} starts with
using normal \TeX\ assignments or increments. This will be orders of
magnitude faster than calling the parser.
-\begin{command}{\pgfmathsetlength\marg{dimension register}\marg{expression}}
- Sets the length of the \TeX{} \meta{dimension register}, to the value
- (in points) specified by \meta{expression}. The \meta{expression}
- will be parsed using |\pgfmathparse|.
+The effect of the following commands is always local to the current
+\TeX\ scope.
+
+\begin{command}{\pgfmathsetlength\marg{register}\marg{expression}}
+ Basically, this command sets the length of the \TeX{}
+ \meta{register} to the value specified by
+ \meta{expression}. However, there is some fine print:
+
+ First, in case \meta{expression} starts with a |+|, a simple \TeX\
+ assignment is done. In particular, \meta{register} can be a glue
+ register and \meta{expression} be something like |+1pt plus 1fil|
+ and the \meta{register} will be assigned the expected value.
+
+ Second, when the \meta{expected} does not start with |+|, it is
+ first parsed using |\pgfmathparse|, resulting in a (dimensionless)
+ value |\pgfmathresult|. Now, if the parser encountered the unit |mu|
+ somewhere in the expression, it assumes that \meta{register} is a
+ |\muskip| register and will try to assign to \meta{register} the
+ value |\pgfmathresult| followed by |mu|. Otherwise, in case |mu| was
+ not encountered, it is assumed that \meta{register} is a dimension
+ register or a glue register and we assign |\pgfmathresult| followed
+ by |pt| to it.
+
+ The net effect of the above is that you can write things like
+\begin{codeexample}[]
+ \muskipdef\mymuskip=0
+ \pgfmathsetlength{\mymuskip}{1mu+3*4mu} \the\mymuskip
+\end{codeexample}
+\begin{codeexample}[]
+ \dimendef\mydimen=0
+ \pgfmathsetlength{\mydimen}{1pt+3*4pt} \the\mydimen
+\end{codeexample}
+\begin{codeexample}[]
+ \skipdef\myskip=0
+ \pgfmathsetlength{\myskip}{1pt+3*4pt} \the\myskip
+\end{codeexample}
+
+ One thing that will \emph{not} work is
+ |\pgfmathsetlength{\myskip}{1pt plus 1fil}| since the parser does
+ not support fill's. You can, however, use the |+| notation in this
+ case:
+\begin{codeexample}[]
+ \skipdef\myskip=0
+ \pgfmathsetlength{\myskip}{+1pt plus 1fil} \the\myskip
+\end{codeexample}
\end{command}
-\begin{command}{\pgfmathaddtolength\marg{dimension register}\marg{expression}}
- Adds the value (in points) of \meta{expression} to the \TeX{}
- \meta{dimension register}.
+\begin{command}{\pgfmathaddtolength\marg{register}\marg{expression}}
+ Adds the value of \meta{expression} to the \TeX{}
+ \meta{register}. All of the special consideration mentioned for
+ |\pgfmathsetlength| also apply here in the same way.
\end{command}
\begin{command}{\pgfmathsetcount\marg{count register}\marg{expression}}
@@ -174,7 +237,7 @@ magnitude faster than calling the parser.
\end{command}
\begin{command}{\pgfmathsetcounter\marg{counter}\marg{expression}}
- Sets the value of the \LaTeX{} \meta{counter}, to the \emph{truncated}
+ Sets the value of the \LaTeX{} \meta{counter} to the \emph{truncated}
value specified by \meta{expression}.
\end{command}
@@ -190,7 +253,7 @@ magnitude faster than calling the parser.
\begin{command}{\pgfmathsetlengthmacro\marg{macro}\marg{expression}}
Defines \meta{macro} as the value of \meta{expression}
- \LaTeX{}\emph{in points}.
+ \LaTeX{} \emph{in points}.
\end{command}
\begin{command}{\pgfmathtruncatemacro\marg{macro}\marg{expression}}
@@ -242,7 +305,7 @@ magnitude faster than calling the parser.
Raises \mvar{x} to the power \mvar{y}.
\end{math-operator}
-\begin{math-operator}{!}{postfix}{factorial}
+\begin{math-operator}{\protect\exclamationmarktext}{postfix}{factorial}
Calculates the factorial of \mvar{x}.
\end{math-operator}
@@ -272,7 +335,7 @@ magnitude faster than calling the parser.
Returns |1| if \mvar{x}$<$\mvar{y}, |0| otherwise.
\end{math-operator}
-\begin{math-operator}{!=}{infix}{notequal}
+\begin{math-operator}{\protect\exclamationmarktext=}{infix}{notequal}
Returns |1| if \mvar{x}$\neq$\mvar{y}, |0| otherwise.
\end{math-operator}
@@ -301,7 +364,7 @@ magnitude faster than calling the parser.
\end{math-operator}
}
-\begin{math-operator}{!}{prefix}{not}
+\begin{math-operator}{\protect\exclamationmarktext}{prefix}{not}
Returns |1| if \mvar{x} evaluates to zero, |0| otherwise.
\end{math-operator}
@@ -355,7 +418,7 @@ the array, an error will occur, and zero will be returned.
\pgfmathparse{\myarray[3]} \pgfmathresult
\end{codeexample}
-If the array is defined to have multiple dimensions then the array
+If the array is defined to have multiple dimensions, then the array
access operators can be immediately repeated.
\begin{codeexample}[]
@@ -368,7 +431,7 @@ access operators can be immediately repeated.
\end{math-operators}
-\begin{math-operators}{"}{"}{group}{}
+\begin{math-operators}{\char`\"}{\char`\"}{group}{}
These operators are used to quote \mvar{x}. However, as every
expression is expanded with |\edef| before it is parsed, macros
@@ -403,18 +466,18 @@ The following functions are recognized:
\foreach \f [count=\i from 0] in
{abs,acos,add,and,array,asin,atan,atan2,bin,ceil,cos,
cosec,cosh,cot,deg,depth,div,divide,e,equal,factorial, false,
- floor,frac,greater,height,hex,Hex,int,ifthenelse,
+ floor,frac,gcd,greater,height,hex,Hex,int,ifthenelse,iseven,isodd,isprime,
less,ln,log10,log2,max,min,mod,Mod,multiply,
neg,not,notequal,notgreater,notless,
oct,or,pi,pow,rad,rand,random,real,rnd,round,
sec,sin,sinh,sqrt,subtract,tan,tanh,true, veclen,width}
-\node [anchor=base west] at ({int(\i/11)*2.5cm},{-mod(\i,11)*1.1*\baselineskip}) {\mathlink{\f}};
+\node [anchor=base west] at ({int(\i/12)*2.5cm},{-mod(\i,12)*1.1*\baselineskip}) {\mathlink{\f}};
\end{tikzpicture}
\bigskip
Each function has a \pgfname{} command associated with it (which is
-also shown with the function below). In general the command
+also shown with the function below). In general, the command
is simply the name of the function prefixed with |\pgfmath|, for
example, |\pgfmathadd|, but there are some notable exceptions.
@@ -512,9 +575,9 @@ example, |\pgfmathadd|, but there are some notable exceptions.
\begin{math-function}{pow(\mvar{x},\mvar{y})}
\mathcommand
- Raises \mvar{x} to the power \mvar{y}. For greatest accuracy
- \mvar{y} should be an integer. If \mvar{y} is not an integer
- the actual calculation will be an approximation of $e^{yln(x)}$.
+ Raises \mvar{x} to the power \mvar{y}. For greatest accuracy,
+ \mvar{y} should be an integer. If \mvar{y} is not an integer,
+ the actual calculation will be an approximation of $e^{y\text{ln}(x)}$.
\begin{codeexample}[]
\pgfmathparse{pow(2,7)} \pgfmathresult
@@ -563,7 +626,7 @@ example, |\pgfmathadd|, but there are some notable exceptions.
\catcode`\^=7
An approximation for $\ln(\textrm{\mvar{x}})$.
- This uses an algorithm due to Rouben Rostamian, and coefficients
+ This uses an algorithm of Rouben Rostamian, and coefficients
suggested by Alain Matthes.
}
\begin{codeexample}[]
@@ -654,7 +717,7 @@ example, |\pgfmathadd|, but there are some notable exceptions.
Rounds \mvar{x} to the nearest integer. It uses ``asymmetric half-up''
rounding. So |1.5| is rounded to |2|, but |-1.5| is rounded to |-2|
- (\emph{not} |1|).
+ (\emph{not} |-1|).
\begin{codeexample}[]
\pgfmathparse{round(32.5/17)} \pgfmathresult
@@ -679,6 +742,9 @@ example, |\pgfmathadd|, but there are some notable exceptions.
\pgfmathparse{floor(398/12)} \pgfmathresult
\end{codeexample}
+\begin{codeexample}[]
+\pgfmathparse{floor(-398/12)} \pgfmathresult
+\end{codeexample}
\end{math-function}
\begin{math-function}{ceil(\mvar{x})}
@@ -694,6 +760,10 @@ example, |\pgfmathadd|, but there are some notable exceptions.
\pgfmathparse{ceil(398/12)} \pgfmathresult
\end{codeexample}
+\begin{codeexample}[]
+\pgfmathparse{ceil(-398/12)} \pgfmathresult
+\end{codeexample}
+
\end{math-function}
\begin{math-function}{int(\mvar{x})}
@@ -730,6 +800,58 @@ example, |\pgfmathadd|, but there are some notable exceptions.
\end{math-function}
+\subsubsection{Integer arithmetics functions}
+
+\label{pgfmath-functions-integerarithmetics}
+
+\begin{math-function}{gcd(\mvar{x},\mvar{y})}
+\mathcommand
+
+ Computes the greatest common divider of \mvar{x} and \mvar{y}.
+
+\begin{codeexample}[]
+\pgfmathparse{gcd(42,56)} \pgfmathresult
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{isodd(\mvar{x})}
+\mathcommand
+
+ Returns |1| if the integer part of \mvar{x} is odd. Otherwise, returns |0|.
+
+\begin{codeexample}[]
+\pgfmathparse{isodd(2)} \pgfmathresult,
+\pgfmathparse{isodd(3)} \pgfmathresult
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{iseven(\mvar{x})}
+\mathcommand
+
+ Returns |1| if the integer part of \mvar{x} is even. Otherwise, returns |0|.
+
+\begin{codeexample}[]
+\pgfmathparse{iseven(2)} \pgfmathresult,
+\pgfmathparse{iseven(3)} \pgfmathresult
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{isprime(\mvar{x})}
+\mathcommand
+
+ Returns |1| if the integer part of \mvar{x} is prime. Otherwise, returns |0|.
+
+\begin{codeexample}[]
+\pgfmathparse{isprime(1)} \pgfmathresult,
+\pgfmathparse{isprime(2)} \pgfmathresult,
+\pgfmathparse{isprime(31)} \pgfmathresult,
+\pgfmathparse{isprime(64)} \pgfmathresult
+\end{codeexample}
+
+\end{math-function}
\subsubsection{Trigonometric functions}
@@ -891,8 +1013,8 @@ example, |\pgfmathadd|, but there are some notable exceptions.
\end{math-function}
-\begin{math-function}{atan2(\mvar{x},\mvar{y})}
-\mathcommand[atantwo(\mvar{x},\mvar{y})]
+\begin{math-function}{atan2(\mvar{y},\mvar{x})}
+\mathcommand[atantwo(\mvar{y},\mvar{x})]
Arctangent of $y\div x$ in degrees. This also takes into account the
quadrants.
@@ -1050,7 +1172,7 @@ example, |\pgfmathadd|, but there are some notable exceptions.
\begin{math-function}{rnd}
\mathcommand
- Generates a pseudo-random number between 0 and 1.
+ Generates a pseudo-random number between $0$ and $1$ with a uniform distribution.
\begin{codeexample}[]
\foreach \x in {1,...,10}{\pgfmathparse{rnd}\pgfmathresult, }
@@ -1061,7 +1183,7 @@ example, |\pgfmathadd|, but there are some notable exceptions.
\begin{math-function}{rand}
\mathcommand
- Generates a pseudo-random number between -1 and 1.
+ Generates a pseudo-random number between $-1$ and $1$ with a uniform distribution.
\begin{codeexample}[]
\foreach \x in {1,...,10}{\pgfmathparse{rand}\pgfmathresult, }
@@ -1072,11 +1194,11 @@ example, |\pgfmathadd|, but there are some notable exceptions.
\begin{math-function}{random(\opt{\mvar{x},\mvar{y}})}
\mathcommand
This function takes zero, one or two arguments. If there are zero
- arguments, a random number between 0 and 1 is generated. If there is
- one argument \mvar{x}, a random integer between 1 and \mvar{x} is
+ arguments, a uniform random number between $0$ and $1$ is generated. If there is
+ one argument \mvar{x}, a random integer between $1$ and \mvar{x} is
generated. Finally, if there are two arguments, a random integer
between \mvar{x} and \mvar{y} is generated. If there are no
- arguments the \pgfname{} command should be called as follows:
+ arguments, the \pgfname{} command should be called as follows:
|\pgfmathrandom{}|.
\begin{codeexample}[]
@@ -1123,7 +1245,7 @@ example, |\pgfmathadd|, but there are some notable exceptions.
\begin{math-function}{oct(\mvar{x})}
\mathcommand
- Convert \mvar{x}{} (assumed to be an integer in base 10) to a
+ Convert \mvar{x}{} (assumed to be an integer in base 10) to an
octal representation.
No further calculation should be attempted with the result, as
the parser can only process numbers converted to base 10.
@@ -1183,8 +1305,7 @@ example, |\pgfmathadd|, but there are some notable exceptions.
\mathcommand
Calculates $\sqrt{\left(\textrm{\mvar{x}}^2+\textrm{\mvar{y}}^2\right)}$.
- This uses a polynomial approximation, based on ideas due
- to Rouben Rostamian
+ This uses a polynomial approximation, based on ideas of Rouben Rostamian
\begin{codeexample}[]
\pgfmathparse{veclen(12,5)} \pgfmathresult
\end{codeexample}
@@ -1249,7 +1370,7 @@ suggested by Martin Heller:
\mathcommand
Return the width of a \TeX{} (horizontal) box containing \mvar{x}.
- The quote characters are necessary to prevent \mvar{x}{} being
+ The quote characters are necessary to prevent \mvar{x}{} from being
parsed.
It is important to remember that any expression is expanded with
|\edef| before being parsed, so any macros (e.g., font commands
@@ -1259,6 +1380,8 @@ suggested by Martin Heller:
\begin{codeexample}[]
\pgfmathparse{width("Some Lovely Text")} \pgfmathresult
\end{codeexample}
+
+ Note that results of this method are provided in points.
\end{math-function}
\begin{math-function}{height("\mvar{x}")}