summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex660
1 files changed, 343 insertions, 317 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex
index 7177e771b95..bdc58135ef0 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex
@@ -9,183 +9,197 @@
\section{Floating Point Unit Library}
-{\noindent {\emph{by Christian Feuers\"anger}}}
\label{pgfmath-floatunit}
\label{section-library-fpu}
+{\noindent {\emph{by Christian Feuersänger}}}
+
\begingroup
\pgfqkeys{/pgf/number format}{sci}
\pgfkeys{/pgf/fpu}
\begin{pgflibrary}{fpu}
- The floating point unit (fpu) allows the full data range of
- scientific computing for use in \pgfname. Its core is the \pgfname\
- math routines for mantissa operations, leading to a reasonable
- trade--of between speed and accuracy. It does not require any
- third--party packages or external programs.
+ The floating point unit (fpu) allows the full data range of scientific
+ computing for use in \pgfname. Its core is the \pgfname\ math routines for
+ mantissa operations, leading to a reasonable trade--of between speed and
+ accuracy. It does not require any third--party packages or external
+ programs.
\end{pgflibrary}
+
\subsection{Overview}
-The fpu provides a replacement set of math commands which can be
-installed in isolated placed to achieve large data ranges at
-reasonable accuracy. It provides at least\footnote{To be more precise,
- the FPU's exponent is currently a 32 bit integer. That means it
- supports a significantly larger data range than an IEEE double
- precision number -- but if a future \TeX\ version may provide
- lowlevel access to doubles, this may change.} the IEEE double
-precision data range, $\pgfmathprintnumber{-1e+324}, \dotsc,
-\pgfmathprintnumber{+1e324}$. The absolute smallest number bigger than
-zero is $\pgfmathprintnumber{1e-324}$. The FPU's relative precision is
-at least $\pgfmathprintnumber{1e-4}$ although operations like addition
-have a relative precision of $\pgfmathprintnumber{1e-6}$.
-
-Note that the library has not really been tested together with any
-drawing operations. It should be used to work with arbitrary input
-data which is then transformed somehow into \pgfname\ precision. This,
-in turn, can be processed by \pgfname.
+
+The fpu provides a replacement set of math commands which can be installed in
+isolated placed to achieve large data ranges at reasonable accuracy. It
+provides at least%
+ \footnote{To be more precise, the FPU's exponent is currently a 32 bit
+ integer. That means it supports a significantly larger data range than an
+ IEEE double precision number -- but if a future \TeX\ version may provide
+ low-level access to doubles, this may change.}%
+the IEEE double precision data range, $\pgfmathprintnumber{-1e+324}, \dotsc,
+\pgfmathprintnumber{+1e324}$. The absolute smallest number bigger than zero is
+$\pgfmathprintnumber{1e-324}$. The FPU's relative precision is at least
+$\pgfmathprintnumber{1e-4}$ although operations like addition have a relative
+precision of $\pgfmathprintnumber{1e-6}$.
+
+Note that the library has not really been tested together with any drawing
+operations. It should be used to work with arbitrary input data which is then
+transformed somehow into \pgfname\ precision. This, in turn, can be processed
+by \pgfname.
+
\subsection{Usage}
-\begin{key}{/pgf/fpu=\marg{boolean} (default true)}
- This key installs or uninstalls the FPU. The installation exchanges
- any routines of the standard math parser with those of the FPU:
- |\pgfmathadd| will be replaced with |\pgfmathfloatadd| and so
- on. Furthermore, any number will be parsed with
- |\pgfmathfloatparsenumber|.
+\begin{key}{/pgf/fpu=\marg{boolean} (default true)}
+ This key installs or uninstalls the FPU. The installation exchanges any
+ routines of the standard math parser with those of the FPU: |\pgfmathadd|
+ will be replaced with |\pgfmathfloatadd| and so on. Furthermore, any number
+ will be parsed with |\pgfmathfloatparsenumber|.
+ %
\begin{codeexample}[]
\pgfkeys{/pgf/fpu}
\pgfmathparse{1+1}\pgfmathresult
\end{codeexample}
- \noindent The FPU uses a lowlevel number representation consisting
- of flags, mantissa and exponent\footnote{Users should \emph{always}
- use high level routines to manipulate floating point numbers as
- the format may change in a future release.}. To avoid unnecessary
- format conversions, |\pgfmathresult| will usually contain such a
- cryptic number. Depending on the context, the result may need to be
- converted into something which is suitable for \pgfname\ processing
- (like coordinates) or may need to be typeset. The FPU provides such
- methods as well.
+ %
+ \noindent The FPU uses a low-level number representation consisting of
+ flags, mantissa and exponent%
+ \footnote{Users should \emph{always} use high
+ level routines to manipulate floating point numbers as the format may
+ change in a future release.}.%
+ To avoid unnecessary format conversions, |\pgfmathresult| will usually
+ contain such a cryptic number. Depending on the context, the result may
+ need to be converted into something which is suitable for \pgfname\
+ processing (like coordinates) or may need to be typeset. The FPU provides
+ such methods as well.
%--------------------------------------------------
% \begin{codeexample}[]
% \begin{tikzpicture}
-% \fill[red,fpu,/pgf/fpu/scale results=1e-10] (*1.234e10,*1e10) -- (*2e10,*2e10);
+% \fill[red,fpu,/pgf/fpu/scale results=1e-10] (*1.234e10,*1e10) -- (*2e10,*2e10);
% \end{tikzpicture}
% \end{codeexample}
%--------------------------------------------------
- Use |fpu=false| to deactivate the FPU. This will restore any
- change. Please note that this is not necessary if the FPU is used
- inside of a \TeX\ group -- it will be deactivated afterwards
- anyway.
+ Use |fpu=false| to deactivate the FPU. This will restore any change. Please
+ note that this is not necessary if the FPU is used inside of a \TeX\ group
+ -- it will be deactivated afterwards anyway.
- It does not hurt to call |fpu=true| or |fpu=false| multiple times.
+ It does not hurt to call |fpu=true| or |fpu=false| multiple times.
- Please note that if the |fixed point arithmetics| library of
- \pgfname\ will be activated after the FPU, the FPU will be
- deactivated automatically.
+ Please note that if the |fixed point arithmetics| library of \pgfname\ will
+ be activated after the FPU, the FPU will be deactivated automatically.
\end{key}
\begin{key}{/pgf/fpu/output format=\mchoice{float,sci,fixed} (initially float)}
- This key allows to change the number format in which the FPU assigns
- |\pgfmathresult|.
-
- The predefined choice |float| uses the low-level format used by the
- FPU. This is useful for further processing inside of any library.
+ This key allows to change the number format in which the FPU assigns
+ |\pgfmathresult|.
+
+ The predefined choice |float| uses the low-level format used by the FPU.
+ This is useful for further processing inside of any library.
+ %
\begin{codeexample}[]
\pgfkeys{/pgf/fpu,/pgf/fpu/output format=float}
\pgfmathparse{exp(50)*42}\pgfmathresult
\end{codeexample}
- The choice |sci| returns numbers in the format
- \meta{mantissa}|e|\meta{exponent}. It provides almost no
- computational overhead.
+ The choice |sci| returns numbers in the format
+ \meta{mantissa}|e|\meta{exponent}. It provides almost no computational
+ overhead.
+ %
\begin{codeexample}[]
\pgfkeys{/pgf/fpu,/pgf/fpu/output format=sci}
\pgfmathparse{4.22e-8^-2}\pgfmathresult
\end{codeexample}
- The choice |fixed| returns normal fixed point numbers and provides
- the highest compatibility with the \pgfname\ engine. It is activated
- automatically in case the FPU scales results.
+ The choice |fixed| returns normal fixed point numbers and provides the
+ highest compatibility with the \pgfname\ engine. It is activated
+ automatically in case the FPU scales results.
+ %
\begin{codeexample}[]
\pgfkeys{/pgf/fpu,/pgf/fpu/output format=fixed}
\pgfmathparse{sqrt(1e-12)}\pgfmathresult
\end{codeexample}
+ %
\end{key}
\begin{key}{/pgf/fpu/scale results=\marg{scale}}
- A feature which allows semi-automatic result scaling. Setting this
- key has two effects: first, the output format for \emph{any}
- computation will be set to |fixed| (assuming results will be
- processed by \pgfname's kernel). Second, any expression which starts
- with a star, |*|, will be multiplied with \meta{scale}.
+ A feature which allows semi-automatic result scaling. Setting this key has
+ two effects: first, the output format for \emph{any} computation will be
+ set to |fixed| (assuming results will be processed by \pgfname's kernel).
+ Second, any expression which starts with a star, |*|, will be multiplied
+ with \meta{scale}.
\end{key}
\begin{keylist}{
/pgf/fpu/scale file plot x=\marg{scale},%
/pgf/fpu/scale file plot y=\marg{scale},%
- /pgf/fpu/scale file plot z=\marg{scale}}%
- These keys will patch \pgfname's |plot file| command to
- automatically scale single coordinates by \meta{scale}.
-
- The initial setting does not scale |plot file|.
+ /pgf/fpu/scale file plot z=\marg{scale}%
+}
+ These keys will patch \pgfname's |plot file| command to automatically scale
+ single coordinates by \meta{scale}.
+
+ The initial setting does not scale |plot file|.
\end{keylist}
\begin{command}{\pgflibraryfpuifactive\marg{true-code}\marg{false-code}}
- This command can be used to execute either \meta{true-code} or
- \meta{false-code}, depending on whether the FPU has been activated
- or not.
+ This command can be used to execute either \meta{true-code} or
+ \meta{false-code}, depending on whether the FPU has been activated or not.
\end{command}
+
\subsection{Comparison to the fixed point arithmetics library}
-There are other ways to increase the data range and/or the precision
-of \pgfname's math parser. One of them is the |fp| package, preferable
-combined with \pgfname's |fixed point arithmetic| library. The
-differences between the FPU and |fp| are:
+
+There are other ways to increase the data range and/or the precision of
+\pgfname's math parser. One of them is the |fp| package, preferable combined
+with \pgfname's |fixed point arithmetic| library. The differences between the
+FPU and |fp| are:
+%
\begin{itemize}
-\item The FPU supports at least the complete IEEE double precision
- number range, while |fp| covers only numbers of magnitude
- $\pm\pgfmathprintnumber{1e17}$.
-\item The FPU has a uniform relative precision of about 4--5 correct
- digits. The fixed point library has an absolute precision which may
- perform good in many cases -- but will fail at the ends of the data
- range (as every fixed point routines does).
-\item The FPU has potential to be faster than |fp| as it has access to
- fast mantissa operations using \pgfname's math capabilities (which
- use \TeX\ registers).
+ \item The FPU supports at least the complete IEEE double precision number
+ range, while |fp| covers only numbers of magnitude
+ $\pm\pgfmathprintnumber{1e17}$.
+ \item The FPU has a uniform relative precision of about 4--5 correct
+ digits. The fixed point library has an absolute precision which may
+ perform good in many cases -- but will fail at the ends of the data
+ range (as every fixed point routines does).
+ \item The FPU has potential to be faster than |fp| as it has access to fast
+ mantissa operations using \pgfname's math capabilities (which use \TeX\
+ registers).
\end{itemize}
+
\subsection{Command Reference and Programmer's Manual}
\subsubsection{Creating and Converting Floats}
+
\begin{command}{\pgfmathfloatparsenumber\marg{x}}
- Reads a number of arbitrary magnitude and precision and stores its
- result into |\pgfmathresult| as floating point number $m \cdot 10^e$
- with mantissa and exponent base~$10$.
+ Reads a number of arbitrary magnitude and precision and stores its result
+ into |\pgfmathresult| as floating point number $m \cdot 10^e$ with mantissa
+ and exponent base~$10$.
- The algorithm and the storage format is purely text-based. The
- number is stored as a triple of flags, a positive mantissa and an
- exponent, such as
+ The algorithm and the storage format is purely text-based. The number is
+ stored as a triple of flags, a positive mantissa and an exponent, such as
+ %
\begin{codeexample}[]
\pgfmathfloatparsenumber{2}
\pgfmathresult
\end{codeexample}
- Please do not rely on the low-level representation here, use
- |\pgfmathfloattomacro| (and its variants) and |\pgfmathfloatcreate|
- if you want to work with these components.
-
- The flags encoded in |\pgfmathresult| are represented as a digit
- where `$0$' stands for the number $\pm 0\cdot 10^0$, `$1$' stands
- for a positive sign, `$2$' means a negative sign, `$3$' stands for
- `not a number', `$4$' means $+\infty$ and `$5$' stands for
- $-\infty$.
-
- The mantissa is a normalized real number $m \in \mathbb{R}$, $1 \le
- m < 10$. It always contains a period and at least one digit after
- the period. The exponent is an integer.
-
- Examples:
+ %
+ Please do not rely on the low-level representation here, use
+ |\pgfmathfloattomacro| (and its variants) and |\pgfmathfloatcreate| if you
+ want to work with these components.
+
+ The flags encoded in |\pgfmathresult| are represented as a digit where
+ `$0$' stands for the number $\pm 0\cdot 10^0$, `$1$' stands for a positive
+ sign, `$2$' means a negative sign, `$3$' stands for `not a number', `$4$'
+ means $+\infty$ and `$5$' stands for $-\infty$.
+
+ The mantissa is a normalized real number $m \in \mathbb{R}$, $1 \le m <
+ 10$. It always contains a period and at least one digit after the period.
+ The exponent is an integer.
+
+ Examples:
+ %
\begin{codeexample}[]
\pgfmathfloatparsenumber{0}
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
@@ -221,48 +235,50 @@ Flags: \F; Mantissa \M; Exponent \E.
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
Flags: \F; Mantissa \M; Exponent \E.
\end{codeexample}
- The argument \meta{x} may be given in fixed point format or the
- scientific ``e'' (or ``E'') notation. The scientific notation does not
- necessarily need to be normalized. The supported exponent range is
- (currently) only limited by the \TeX-integer range (which uses 31
- bit integer numbers).
+ %
+ The argument \meta{x} may be given in fixed point format or the scientific
+ ``e'' (or ``E'') notation. The scientific notation does not necessarily
+ need to be normalized. The supported exponent range is (currently) only
+ limited by the \TeX-integer range (which uses 31 bit integer numbers).
\end{command}
\begin{key}{/pgf/fpu/handlers/empty number=\marg{input}\marg{unreadable part}}
- This command key is invoked in case an empty string is parsed inside
- of |\pgfmathfloatparsenumber|. You can overwrite it to assign a
- replacement |\pgfmathresult| (in float!).
+ This command key is invoked in case an empty string is parsed inside of
+ |\pgfmathfloatparsenumber|. You can overwrite it to assign a replacement
+ |\pgfmathresult| (in float!).
- The initial setting is to invoke |invalid number|, see below.
+ The initial setting is to invoke |invalid number|, see below.
\end{key}
+
\begin{key}{/pgf/fpu/handlers/invalid number=\marg{input}\marg{unreadable part}}
- This command key is invoked in case an invalid string is parsed
- inside of |\pgfmathfloatparsenumber|. You can overwrite it to assign
- a replacement |\pgfmathresult| (in float!).
+ This command key is invoked in case an invalid string is parsed inside of
+ |\pgfmathfloatparsenumber|. You can overwrite it to assign a replacement
+ |\pgfmathresult| (in float!).
- The initial setting is to generate an error message.
+ The initial setting is to generate an error message.
\end{key}
+
\begin{key}{/pgf/fpu/handlers/wrong lowlevel format=\marg{input}\marg{unreadable part}}
- This command key is invoked whenever |\pgfmathfloattoregisters| or
- its variants encounter something which is not a properly formatted
- lowlevel floating point number. As for |invalid number|, this key
- may assign a new |\pgfmathresult| (in floating point) which will be
- used instead of the offending \meta{input}.
+ This command key is invoked whenever |\pgfmathfloattoregisters| or its
+ variants encounter something which is not a properly formatted low-level
+ floating point number. As for |invalid number|, this key may assign a new
+ |\pgfmathresult| (in floating point) which will be used instead of the
+ offending \meta{input}.
- The initial setting is to generate an error message.
+ The initial setting is to generate an error message.
\end{key}
\begin{command}{\pgfmathfloatqparsenumber\marg{x}}
- The same as |\pgfmathfloatparsenumber|, but does not perform sanity checking.
+ The same as |\pgfmathfloatparsenumber|, but does not perform sanity checking.
\end{command}
\begin{command}{\pgfmathfloattofixed{\marg{x}}}
- Converts a number in floating point representation to a fixed point
- number. It is a counterpart to |\pgfmathfloatparsenumber|. The
- algorithm is purely text based and defines |\pgfmathresult| as a
- string sequence which represents the floating point number \meta{x}
- as a fixed point number (of arbitrary precision).
-
+ Converts a number in floating point representation to a fixed point number.
+ It is a counterpart to |\pgfmathfloatparsenumber|. The algorithm is purely
+ text based and defines |\pgfmathresult| as a string sequence which
+ represents the floating point number \meta{x} as a fixed point number (of
+ arbitrary precision).
+ %
\begin{codeexample}[]
\pgfmathfloatparsenumber{0.00052}
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
@@ -280,61 +296,67 @@ $\to$
\pgfmathfloattofixed{\pgfmathresult}
\pgfmathresult
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfmathfloattoint\marg{x}}
- Converts a number from low-level floating point representation to an
- integer (by truncating the fractional part).
+ Converts a number from low-level floating point representation to an
+ integer (by truncating the fractional part).
+ %
\begin{codeexample}[]
\pgfmathfloatparsenumber{123456}
\pgfmathfloattoint{\pgfmathresult}
\pgfmathresult
\end{codeexample}
-See also |\pgfmathfloatint| which returns the result as float.
+ See also |\pgfmathfloatint| which returns the result as float.
\end{command}
\begin{command}{\pgfmathfloattosci\marg{float}}
- Converts a number from low-level floating point representation to
- scientific format, $1.234e4$. The result will be assigned to the
- macro |\pgfmathresult|.
+ Converts a number from low-level floating point representation to
+ scientific format, $1.234e4$. The result will be assigned to the macro
+ |\pgfmathresult|.
\end{command}
\begin{command}{\pgfmathfloatvalueof\marg{float}}
- Expands a number from low-level floating point representation to
- scientific format, $1.234e4$.
+ Expands a number from low-level floating point representation to scientific
+ format, $1.234e4$.
- Use |\pgfmathfloatvalueof| in contexts where only expandable macros are allowed.
+ Use |\pgfmathfloatvalueof| in contexts where only expandable macros are
+ allowed.
\end{command}
\begin{command}{\pgfmathfloatcreate{\marg{flags}}{\marg{mantissa}}{\marg{exponent}}}
- Defines |\pgfmathresult| as the floating point number encoded by
- \meta{flags}, \meta{mantissa} and \meta{exponent}.
-
- All arguments are characters and will be expanded using |\edef|.
+ Defines |\pgfmathresult| as the floating point number encoded by
+ \meta{flags}, \meta{mantissa} and \meta{exponent}.
+
+ All arguments are characters and will be expanded using |\edef|.
+ %
\begin{codeexample}[]
\pgfmathfloatcreate{1}{1.0}{327}
\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
Flags: \F; Mantissa \M; Exponent \E
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfmathfloatifflags\marg{floating point number}\marg{flag}\marg{true-code}\marg{false-code}}
- Invokes \meta{true-code} if the flag of \meta{floating point number}
- equals \meta{flag} and \meta{false-code} otherwise.
-
- The argument \meta{flag} can be one of
- \begin{description}
- \item[0] to test for zero,
- \item[1] to test for positive numbers,
- \item[+] to test for positive numbers,
- \item[2] to test for negative numbers,
- \item[-] to test for negative numbers,
- \item[3] for ``not-a-number'',
- \item[4] for $+\infty$,
- \item[5] for $-\infty$.
- \end{description}
-
+ Invokes \meta{true-code} if the flag of \meta{floating point number} equals
+ \meta{flag} and \meta{false-code} otherwise.
+
+ The argument \meta{flag} can be one of
+ %
+ \begin{description}
+ \item[0] to test for zero,
+ \item[1] to test for positive numbers,
+ \item[+] to test for positive numbers,
+ \item[2] to test for negative numbers,
+ \item[-] to test for negative numbers,
+ \item[3] for ``not-a-number'',
+ \item[4] for $+\infty$,
+ \item[5] for $-\infty$.
+ \end{description}
+ %
\begin{codeexample}[]
\pgfmathfloatparsenumber{42}
\pgfmathfloatifflags{\pgfmathresult}{0}{It's zero!}{It's not zero!}
@@ -345,307 +367,311 @@ Flags: \F; Mantissa \M; Exponent \E
\pgfmathfloatifflags{\pgfmathresult}{+}{It's positive!}{It's not positive!}
\pgfmathfloatifflags{\pgfmathresult}{-}{It's negative!}{It's not negative!}
\end{codeexample}
+ %
\end{command}
-
\begin{command}{\pgfmathfloattomacro{\marg{x}}{\marg{flagsmacro}}{\marg{mantissamacro}}{\marg{exponentmacro}}}
- Extracts the flags of a floating point number \meta{x} to
- \meta{flagsmacro}, the mantissa to \meta{mantissamacro} and the
- exponent to \meta{exponentmacro}.
+ Extracts the flags of a floating point number \meta{x} to
+ \meta{flagsmacro}, the mantissa to \meta{mantissamacro} and the exponent to
+ \meta{exponentmacro}.
\end{command}
\begin{command}{\pgfmathfloattoregisters{\marg{x}}{\marg{flagscount}}{\marg{mantissadimen}}{\marg{exponentcount}}}
- Takes a floating point number \meta{x} as input and writes flags to
- count register \meta{flagscount}, mantissa to dimen register
- \meta{mantissadimen} and exponent to count register \meta{exponentcount}.
+ Takes a floating point number \meta{x} as input and writes flags to count
+ register \meta{flagscount}, mantissa to dimen register \meta{mantissadimen}
+ and exponent to count register \meta{exponentcount}.
- Please note that this method rounds the mantissa to \TeX-precision.
+ Please note that this method rounds the mantissa to \TeX-precision.
\end{command}
\begin{command}{\pgfmathfloattoregisterstok{\marg{x}}{\marg{flagscount}}{\marg{mantissatoks}}{\marg{exponentcount}}}
- A variant of |\pgfmathfloattoregisters| which writes the
- mantissa into a token register. It maintains the full input
- precision.
+ A variant of |\pgfmathfloattoregisters| which writes the mantissa into a
+ token register. It maintains the full input precision.
\end{command}
\begin{command}{\pgfmathfloatgetflags{\marg{x}}{\marg{flagscount}}}
- Extracts the flags of \meta{x} into the count register
- \meta{flagscount}.
+ Extracts the flags of \meta{x} into the count register \meta{flagscount}.
\end{command}
\begin{command}{\pgfmathfloatgetflagstomacro{\marg{x}}{\marg{macro}}}
- Extracts the flags of \meta{x} into the macro \meta{macro}.
+ Extracts the flags of \meta{x} into the macro \meta{macro}.
\end{command}
\begin{command}{\pgfmathfloatgetmantissa{\marg{x}}{\marg{mantissadimen}}}
- Extracts the mantissa of \meta{x} into the dimen register
- \meta{mantissadimen}.
+ Extracts the mantissa of \meta{x} into the dimen register
+ \meta{mantissadimen}.
\end{command}
\begin{command}{\pgfmathfloatgetmantissatok{\marg{x}}{\marg{mantissatoks}}}
- Extracts the mantissa of \meta{x} into the token register
- \meta{mantissatoks}.
+ Extracts the mantissa of \meta{x} into the token register
+ \meta{mantissatoks}.
\end{command}
\begin{command}{\pgfmathfloatgetexponent{\marg{x}}{\marg{exponentcount}}}
- Extracts the exponent of \meta{x} into the count register
- \meta{exponentcount}.
+ Extracts the exponent of \meta{x} into the count register
+ \meta{exponentcount}.
\end{command}
+
\subsubsection{Symbolic Rounding Operations}
-Commands in this section constitute the basic level implementations of
-the rounding routines. They work symbolically, i.e.\ they operate on
-text, not on numbers and allow arbitrarily large numbers.
+Commands in this section constitute the basic level implementations of the
+rounding routines. They work symbolically, i.e.\ they operate on text, not on
+numbers and allow arbitrarily large numbers.
\begin{command}{\pgfmathroundto{\marg{x}}}
- Rounds a fixed point number to prescribed precision and writes the
- result to |\pgfmathresult|.
-
- The desired precision can be configured with
- |/pgf/number format/precision|, see
- section~\ref{pgfmath-numberprinting}. This section does also contain
- application examples.
-
- Any trailing zeros after the period are discarded. The algorithm is
- purely text based and allows to deal with precisions beyond \TeX's
- fixed point support.
-
- As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod|
- will be set to true if and only if the resulting mantissa has a
- period. Furthermore, |\ifpgfmathfloatroundmayneedrenormalize| will
- be set to true if and only if the rounding result's floating point
- representation would have a larger exponent than \meta{x}.
+ Rounds a fixed point number to prescribed precision and writes the result
+ to |\pgfmathresult|.
+
+ The desired precision can be configured with
+ |/pgf/number format/precision|, see section~\ref{pgfmath-numberprinting}.
+ This section does also contain application examples.
+
+ Any trailing zeros after the period are discarded. The algorithm is purely
+ text based and allows to deal with precisions beyond \TeX's fixed point
+ support.
+
+ As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| will
+ be set to true if and only if the resulting mantissa has a period.
+ Furthermore, |\ifpgfmathfloatroundmayneedrenormalize| will be set to true
+ if and only if the rounding result's floating point representation would
+ have a larger exponent than \meta{x}.
+ %
\begin{codeexample}[]
\pgfmathroundto{1}
\pgfmathresult
\end{codeexample}
+ %
\begin{codeexample}[]
\pgfmathroundto{4.685}
\pgfmathresult
\end{codeexample}
+ %
\begin{codeexample}[]
\pgfmathroundto{19999.9996}
\pgfmathresult
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfmathroundtozerofill{\marg{x}}}
- A variant of |\pgfmathroundto| which always uses a fixed number of
- digits behind the period. It fills missing digits with zeros.
+ A variant of |\pgfmathroundto| which always uses a fixed number of digits
+ behind the period. It fills missing digits with zeros.
+ %
\begin{codeexample}[]
\pgfmathroundtozerofill{1}
\pgfmathresult
\end{codeexample}
+ %
\begin{codeexample}[]
\pgfmathroundto{4.685}
\pgfmathresult
\end{codeexample}
+ %
\begin{codeexample}[]
\pgfmathroundtozerofill{19999.9996}
\pgfmathresult
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfmathfloatround{\marg{x}}}
- Rounds a normalized floating point number to a prescribed precision
- and writes the result to |\pgfmathresult|.
-
- The desired precision can be configured with
- |/pgf/number format/precision|, see
- section~\ref{pgfmath-numberprinting}.
-
- This method employs |\pgfmathroundto| to round the mantissa and
- applies renormalization if necessary.
-
- As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod|
- will be set to true if and only if the resulting mantissa has a
- period.
+ Rounds a normalized floating point number to a prescribed precision and
+ writes the result to |\pgfmathresult|.
+
+ The desired precision can be configured with
+ |/pgf/number format/precision|, see section~\ref{pgfmath-numberprinting}.
+
+ This method employs |\pgfmathroundto| to round the mantissa and applies
+ renormalization if necessary.
+
+ As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| will
+ be set to true if and only if the resulting mantissa has a period.
+ %
\begin{codeexample}[]
\pgfmathfloatparsenumber{52.5864}
\pgfmathfloatround{\pgfmathresult}
\pgfmathfloattosci{\pgfmathresult}
\pgfmathresult
\end{codeexample}
+ %
\begin{codeexample}[]
\pgfmathfloatparsenumber{9.995}
\pgfmathfloatround{\pgfmathresult}
\pgfmathfloattosci{\pgfmathresult}
\pgfmathresult
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfmathfloatroundzerofill{\marg{x}}}
- A variant of |\pgfmathfloatround| produces always the same number of
- digits after the period (it includes zeros if necessary).
+ A variant of |\pgfmathfloatround| produces always the same number of digits
+ after the period (it includes zeros if necessary).
+ %
\begin{codeexample}[]
\pgfmathfloatparsenumber{52.5864}
\pgfmathfloatroundzerofill{\pgfmathresult}
\pgfmathfloattosci{\pgfmathresult}
\pgfmathresult
\end{codeexample}
+ %
\begin{codeexample}[]
\pgfmathfloatparsenumber{9.995}
\pgfmathfloatroundzerofill{\pgfmathresult}
\pgfmathfloattosci{\pgfmathresult}
\pgfmathresult
\end{codeexample}
+ %
\end{command}
-
\subsubsection{Math Operations Commands}
-This section describes some of the replacement commands in more
-detail.
+This section describes some of the replacement commands in more detail.
-Please note that these commands can be used even if the |fpu| as such
-has not been activated -- it is sufficient to load the library.
+Please note that these commands can be used even if the |fpu| as such has not
+been activated -- it is sufficient to load the library.
\begin{command}{\pgfmathfloat\meta{op}}
- Methods of this form constitute the replacement operations where
- \meta{op} can be any of the well-known math operations.
+ Methods of this form constitute the replacement operations where \meta{op}
+ can be any of the well-known math operations.
- Thus, \declareandlabel{\pgfmathfloatadd} is the counterpart
- for |\pgfmathadd| and so on. The semantics and number of
- arguments is the same, but all input and output arguments are
- \emph{expected} to be floating point numbers.
+ Thus, \declareandlabel{\pgfmathfloatadd} is the counterpart for
+ |\pgfmathadd| and so on. The semantics and number of arguments is the same,
+ but all input and output arguments are \emph{expected} to be floating point
+ numbers.
\end{command}
\begin{command}{\pgfmathfloattoextentedprecision{\marg{x}}}
- Renormalizes \meta{x} to extended precision mantissa, meaning
- $100 \le m < 1000$ instead of $1 \le m < 10$.
-
- The ``extended precision'' means we have higher accuracy when we apply
- pgfmath operations to mantissas.
-
- The input argument is expected to be a normalized floating point
- number; the output argument is a non-normalized floating point number
- (well, normalized to extended precision).
-
- The operation is supposed to be very fast.
+ Renormalizes \meta{x} to extended precision mantissa, meaning $100 \le m <
+ 1000$ instead of $1 \le m < 10$.
+
+ The ``extended precision'' means we have higher accuracy when we apply
+ pgfmath operations to mantissas.
+
+ The input argument is expected to be a normalized floating point number;
+ the output argument is a non-normalized floating point number (well,
+ normalized to extended precision).
+
+ The operation is supposed to be very fast.
\end{command}
\begin{command}{\pgfmathfloatsetextprecision\marg{shift}}
- Sets the precision used inside of |\pgfmathfloattoextentedprecision| to \meta{shift}.
-
- The different choices are
-
- \begin{tabular}{llrll}
- 0 & normalization to & $0$ & $\le m < 1$ & (disable extended precision)\\
- 1 & normalization to & $10$ & $\le m < 100$ \\
- 2 & normalization to & $100$ & $\le m < 1000$ & (default of |\pgfmathfloattoextentedprecision|)\\
- 3 & normalization to & $1000$ & $\le m < 10000$ \\
- \end{tabular}
+ Sets the precision used inside of |\pgfmathfloattoextentedprecision| to
+ \meta{shift}.
+
+ The different choices are
+
+ \begin{tabular}{llrll}
+ 0 & normalization to & $0$ & $\le m < 1$ & (disable extended precision) \\
+ 1 & normalization to & $10$ & $\le m < 100$ & \\
+ 2 & normalization to & $100$ & $\le m < 1000$ & (default of |\pgfmathfloattoextentedprecision|) \\
+ 3 & normalization to & $1000$ & $\le m < 10000$ & \\
+ \end{tabular}
\end{command}
\begin{command}{\pgfmathfloatlessthan{\marg{x}}{\marg{y}}}
- Defines |\pgfmathresult| as $1.0$ if $\meta{x} < \meta{y}$, but
- $0.0$ otherwise. It also sets the global \TeX-boolean
- |\pgfmathfloatcomparison| accordingly. The arguments \meta{x} and
- \meta{y} are expected to be numbers which have already been
- processed by |\pgfmathfloatparsenumber|. Arithmetic is carried out
- using \TeX-registers for exponent- and mantissa comparison.
+ Defines |\pgfmathresult| as $1.0$ if $\meta{x} < \meta{y}$, but $0.0$
+ otherwise. It also sets the global \TeX-boolean |\pgfmathfloatcomparison|
+ accordingly. The arguments \meta{x} and \meta{y} are expected to be numbers
+ which have already been processed by |\pgfmathfloatparsenumber|. Arithmetic
+ is carried out using \TeX-registers for exponent- and mantissa comparison.
\end{command}
\begin{command}{\pgfmathfloatmultiplyfixed\marg{float}\marg{fixed}}
- Defines |\pgfmathresult| to be $\meta{float} \cdot \meta{fixed}$
- where \meta{float} is a floating point number and \meta{fixed} is a
- fixed point number. The computation is performed in floating point
- arithmetics, that means we compute $m \cdot \meta{fixed}$ and
- renormalize the result where $m$ is the mantissa of \meta{float}.
+ Defines |\pgfmathresult| to be $\meta{float} \cdot \meta{fixed}$ where
+ \meta{float} is a floating point number and \meta{fixed} is a fixed point
+ number. The computation is performed in floating point arithmetics, that
+ means we compute $m \cdot \meta{fixed}$ and renormalize the result where
+ $m$ is the mantissa of \meta{float}.
- This operation renormalizes \meta{float} with
- |\pgfmathfloattoextentedprecision| before the operation, that means
- it is intended for relatively small arguments of \meta{fixed}. The
- result is a floating point number.
+ This operation renormalizes \meta{float} with
+ |\pgfmathfloattoextentedprecision| before the operation, that means it is
+ intended for relatively small arguments of \meta{fixed}. The result is a
+ floating point number.
\end{command}
\begin{command}{\pgfmathfloatifapproxequalrel\marg{a}\marg{b}\marg{true-code}\marg{false-code}}
- Computes the relative error between \meta{a} and \meta{b} (assuming
- \meta{b}$\neq 0$) and invokes \meta{true-code} if the relative error
- is below |/pgf/fpu/rel thresh| and \meta{false-code} if that is not
- the case.
+ Computes the relative error between \meta{a} and \meta{b} (assuming
+ \meta{b}$\neq 0$) and invokes \meta{true-code} if the relative error is
+ below |/pgf/fpu/rel thresh| and \meta{false-code} if that is not the case.
- The input arguments will be parsed with |\pgfmathfloatparsenumber|.
+ The input arguments will be parsed with |\pgfmathfloatparsenumber|.
- \begin{key}{/pgf/fpu/rel thresh=\marg{number} (initially 1e-4)}
- A threshold used by |\pgfmathfloatifapproxequalrel| to decide
- whether numbers are approximately equal.
- \end{key}
+ \begin{key}{/pgf/fpu/rel thresh=\marg{number} (initially 1e-4)}
+ A threshold used by |\pgfmathfloatifapproxequalrel| to decide whether
+ numbers are approximately equal.
+ \end{key}
\end{command}
-
\begin{command}{\pgfmathfloatshift{\marg{x}}{\marg{num}}}
- Defines |\pgfmathresult| to be $\meta{x} \cdot 10^{\meta{num}}$. The
- operation is an arithmetic shift base ten and modifies only the
- exponent of \meta{x}. The argument \meta{num} is expected to be a
- (positive or negative) integer.
+ Defines |\pgfmathresult| to be $\meta{x} \cdot 10^{\meta{num}}$. The
+ operation is an arithmetic shift base ten and modifies only the exponent of
+ \meta{x}. The argument \meta{num} is expected to be a (positive or
+ negative) integer.
\end{command}
-
\begin{command}{\pgfmathfloatabserror\marg{x}\marg{y}}
- Defines |\pgfmathresult| to be the absolute error between two
- floating point numbers $x$ and $y$, $\lvert x - y\rvert $ and
- returns the result as floating point number.
+ Defines |\pgfmathresult| to be the absolute error between two floating
+ point numbers $x$ and $y$, $\lvert x - y\rvert $ and returns the result as
+ floating point number.
\end{command}
\begin{command}{\pgfmathfloatrelerror\marg{x}\marg{y}}
- Defines |\pgfmathresult| to be the relative error between two
- floating point numbers $x$ and $y$, $\lvert x - y\rvert / \lvert y
- \rvert $ and returns the result as floating point number.
+ Defines |\pgfmathresult| to be the relative error between two floating
+ point numbers $x$ and $y$, $\lvert x - y\rvert / \lvert y \rvert$ and
+ returns the result as floating point number.
\end{command}
-
\begin{command}{\pgfmathfloatint\marg{x}}
- Returns the integer part of the floating point number \meta{x}, by
- truncating any digits after the period. This methods truncates the
- absolute value $\rvert x \lvert$ to the next smaller integer and
- restores the original sign afterwards.
+ Returns the integer part of the floating point number \meta{x}, by
+ truncating any digits after the period. This methods truncates the absolute
+ value $\rvert x \lvert$ to the next smaller integer and restores the
+ original sign afterwards.
- The result is returned as floating point number as well.
+ The result is returned as floating point number as well.
- See also |\pgfmathfloattoint| which returns the number in integer
- format.
+ See also |\pgfmathfloattoint| which returns the number in integer format.
\end{command}
\begin{command}{\pgfmathlog{\marg{x}}}
- Defines |\pgfmathresult| to be the natural logarithm of \meta{x},
- $\ln(\meta{x})$. This method is logically the same as |\pgfmathln|,
- but it applies floating point arithmetics to read number \meta{x}
- and employs the logarithm identity
- \[ \ln(m \cdot 10^e) = \ln(m) + e \cdot \ln(10) \]
- to get the result. The factor $\ln(10)$ is a constant, so only
- $\ln(m)$ with $1 \le m < 10$ needs to be computed. This is done
- using standard pgf math operations.
-
- Please note that \meta{x} needs to be a number, expression parsing
- is not possible here.
-
- If \meta{x} is \emph{not} a bounded positive real number (for
- example $\meta{x} \le 0$), |\pgfmathresult| will be \emph{empty}, no
- error message will be generated.
+ Defines |\pgfmathresult| to be the natural logarithm of \meta{x},
+ $\ln(\meta{x})$. This method is logically the same as |\pgfmathln|, but it
+ applies floating point arithmetics to read number \meta{x} and employs the
+ logarithm identity \[ \ln(m \cdot 10^e) = \ln(m) + e \cdot \ln(10) \] to
+ get the result. The factor $\ln(10)$ is a constant, so only $\ln(m)$ with
+ $1 \le m < 10$ needs to be computed. This is done using standard pgf math
+ operations.
+
+ Please note that \meta{x} needs to be a number, expression parsing is not
+ possible here.
+
+ If \meta{x} is \emph{not} a bounded positive real number (for example
+ $\meta{x} \le 0$), |\pgfmathresult| will be \emph{empty}, no error message
+ will be generated.
+ %
\begin{codeexample}[]
\pgfmathlog{1.452e-7}
\pgfmathresult
\end{codeexample}
+ %
\begin{codeexample}[]
\pgfmathlog{6.426e+8}
\pgfmathresult
\end{codeexample}
+ %
\end{command}
-\subsubsection{Accessing the Original Math Routines for Programmers}
-As soon as the library is loaded, every private math routine will be
-copied to a new name. This allows library and package authors to
-access the \TeX-register based math routines even if the FPU is
-activated. And, of course, it allows the FPU as such to perform its
-own mantissa computations.
+\subsubsection{Accessing the Original Math Routines for Programmers}
-The private implementations of \pgfname\ math commands, which are of
-the form |\pgfmath|\meta{name}|@|, will be available
-as|\pgfmath@basic@|\meta{name}|@| as soon as the library is loaded.
+As soon as the library is loaded, every private math routine will be copied to
+a new name. This allows library and package authors to access the \TeX-register
+based math routines even if the FPU is activated. And, of course, it allows the
+FPU as such to perform its own mantissa computations.
+The private implementations of \pgfname\ math commands, which are of the form
+|\pgfmath|\meta{name}|@|, will be available as|\pgfmath@basic@|\meta{name}|@|
+as soon as the library is loaded.
\endgroup