summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-math-numberprinting.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /graphics/pgf/base/doc/text-en/pgfmanual-en-math-numberprinting.tex
Initial commit
Diffstat (limited to 'graphics/pgf/base/doc/text-en/pgfmanual-en-math-numberprinting.tex')
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-math-numberprinting.tex875
1 files changed, 875 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-math-numberprinting.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-math-numberprinting.tex
new file mode 100644
index 0000000000..9cd4a9a6dd
--- /dev/null
+++ b/graphics/pgf/base/doc/text-en/pgfmanual-en-math-numberprinting.tex
@@ -0,0 +1,875 @@
+
+\section{Number Printing}
+\label{pgfmath-numberprinting}
+
+{\emph{An extension by Christian Feuersänger}}
+
+\medskip
+\noindent
+\pgfname\ supports number printing in different styles and rounds to arbitrary
+precision.
+
+\begin{command}{\pgfmathprintnumber\marg{x}}
+ Generates pretty-printed output for the (real) number \meta{x}. The input
+ number \meta{x} is parsed using |\pgfmathfloatparsenumber| which allows
+ arbitrary precision.
+
+ Numbers are typeset in math mode using the current set of number printing
+ options, see below. Optional arguments can also be provided using
+ |\pgfmathprintnumber[|\meta{options}|]|\meta{x}.
+\end{command}
+
+\begin{command}{\pgfmathprintnumberto\marg{x}\marg{macro}}
+ Returns the resulting number into \meta{macro} instead of typesetting it
+ directly.
+\end{command}
+
+\begin{key}{/pgf/number format/fixed}
+ Configures |\pgfmathprintnumber| to round the number to a fixed number of
+ digits after the period, discarding any trailing zeros.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,fixed,precision=2}
+\pgfmathprintnumber{4.568}\hspace{1em}
+\pgfmathprintnumber{5e-04}\hspace{1em}
+\pgfmathprintnumber{0.1}\hspace{1em}
+\pgfmathprintnumber{24415.98123}\hspace{1em}
+\pgfmathprintnumber{123456.12345}
+\end{codeexample}
+
+ See section~\ref{sec:number:styles} for how to change the appearance.
+\end{key}
+
+\begin{key}{/pgf/number format/fixed zerofill=\marg{boolean} (default true)}
+ Enables or disables zero filling for any number drawn in fixed point
+ format.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,fixed,fixed zerofill,precision=2}
+\pgfmathprintnumber{4.568}\hspace{1em}
+\pgfmathprintnumber{5e-04}\hspace{1em}
+\pgfmathprintnumber{0.1}\hspace{1em}
+\pgfmathprintnumber{24415.98123}\hspace{1em}
+\pgfmathprintnumber{123456.12345}
+\end{codeexample}
+ %
+ This key affects numbers drawn with |fixed| or |std| styles (the latter
+ only if no scientific format is chosen).
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,std,fixed zerofill,precision=2}
+\pgfmathprintnumber{4.568}\hspace{1em}
+\pgfmathprintnumber{5e-05}\hspace{1em}
+\pgfmathprintnumber{1}\hspace{1em}
+\pgfmathprintnumber{123456.12345}
+\end{codeexample}
+
+ See section~\ref{sec:number:styles} for how to change the appearance.
+\end{key}
+
+\begin{key}{/pgf/number format/sci}
+ Configures |\pgfmathprintnumber| to display numbers in scientific format,
+ that means sign, mantissa and exponent (basis~$10$). The mantissa is
+ rounded to the desired |precision| (or |sci precision|, see below).
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,sci,precision=2}
+\pgfmathprintnumber{4.568}\hspace{1em}
+\pgfmathprintnumber{5e-04}\hspace{1em}
+\pgfmathprintnumber{0.1}\hspace{1em}
+\pgfmathprintnumber{24415.98123}\hspace{1em}
+\pgfmathprintnumber{123456.12345}
+\end{codeexample}
+
+ See section~\ref{sec:number:styles} for how to change the exponential
+ display style.
+\end{key}
+
+\begin{key}{/pgf/number format/sci zerofill=\marg{boolean} (default true)}
+ Enables or disables zero filling for any number drawn in scientific format.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,sci,sci zerofill,precision=2}
+\pgfmathprintnumber{4.568}\hspace{1em}
+\pgfmathprintnumber{5e-04}\hspace{1em}
+\pgfmathprintnumber{0.1}\hspace{1em}
+\pgfmathprintnumber{24415.98123}\hspace{1em}
+\pgfmathprintnumber{123456.12345}
+\end{codeexample}
+ %
+ As with |fixed zerofill|, this option does only affect numbers drawn in
+ |sci| format (or |std| if the scientific format is chosen).
+
+ See section~\ref{sec:number:styles} for how to change the exponential
+ display style.
+\end{key}
+
+\begin{stylekey}{/pgf/number format/zerofill=\marg{boolean} (default true)}
+ Sets both |fixed zerofill| and |sci zerofill| at once.
+\end{stylekey}
+
+\begin{keylist}{/pgf/number format/std,%
+ /pgf/number format/std=\meta{lower e},
+ /pgf/number format/std=\meta{lower e}:\meta{upper e}%
+}
+ Configures |\pgfmathprintnumber| to a standard algorithm. It chooses either
+ |fixed| or |sci|, depending on the order of magnitude. Let $n=s \cdot m
+ \cdot 10^e$ be the input number and $p$ the current precision. If $-p/2 \le
+ e \le 4$, the number is displayed using |fixed| format. Otherwise, it is
+ displayed using |sci| format.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,std,precision=2}
+\pgfmathprintnumber{4.568}\hspace{1em}
+\pgfmathprintnumber{5e-04}\hspace{1em}
+\pgfmathprintnumber{0.1}\hspace{1em}
+\pgfmathprintnumber{24415.98123}\hspace{1em}
+\pgfmathprintnumber{123456.12345}
+\end{codeexample}
+ %
+ The parameters can be customized using the optional integer argument(s): if
+ $\text{\meta{lower e}} \le e \le \text{\meta{upper e}}$, the number is
+ displayed in |fixed| format, otherwise in |sci| format. Note that
+ \meta{lower e} should be negative for useful results. The precision used
+ for the scientific format can be adjusted with |sci precision| if
+ necessary.
+\end{keylist}
+
+\begin{keylist}{/pgf/number format/relative*=\meta{exponent base 10}}
+ Configures |\pgfmathprintnumber| to format numbers relative to an order of
+ magnitude, $10^r$, where $r$ is an integer number.
+
+ This key addresses different use-cases.
+
+ \paragraph{First use-case:}
+
+ provide a unified format for a \emph{sequence} of numbers. Consider the
+ following test:
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/relative*={1}}
+\pgfmathprintnumber{6.42e-16}\hspace{1em}
+\pgfmathprintnumber{1.2}\hspace{1em}
+\pgfmathprintnumber{6}\hspace{1em}
+\pgfmathprintnumber{20.6}\hspace{1em}
+\pgfmathprintnumber{87}
+\end{codeexample}
+ %
+ \noindent With any other style, the |6.42e-16| would have been formatted as
+ an isolated number. Here, it is rounded to |0| because when viewed relative
+ to $10^1$ (the exponent $1$ is the argument for |relative|), it has no
+ significant digits.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/relative*={2}}
+\pgfmathprintnumber{123.345}\hspace{1em}
+\pgfmathprintnumber{0.0012}\hspace{1em}
+\pgfmathprintnumber{0.0014}\hspace{1em}
+\end{codeexample}
+ %
+ \noindent The example above applies the initial |precision=2| to |123.345|
+ -- relative to $100$. Two significant digits of |123.345| relative to $100$
+ are |123|. Note that the ``$2$ significant digits of |123.345|'' translates
+ to ``round |1.2345| to $2$ digits'', which would yield |1.2300|. Similarly,
+ the other two numbers are |0| compared to $100$ using the given
+ |precision|.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/relative*={-3}}
+\pgfmathprintnumber{123.345}\hspace{1em}
+\pgfmathprintnumber{0.0012}\hspace{1em}
+\pgfmathprintnumber{0.0014}\hspace{1em}
+\end{codeexample}
+
+ \paragraph{Second use-case:}
+
+ improve rounding in the presence of \emph{inaccurate} numbers. Let us
+ suppose that some limited-precision arithmetics resulted in the result
+ |123456999| (like the |fpu| of \pgfname). You know that its precision is
+ about five or six significant digits. And you want to provide a fixed point
+ output. In this case, the trailing digits |....999| are a numerical
+ artifact due to the limited precision. Use |relative*=3,precision=0| to
+ eliminate the artifacts:
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,relative*={3},precision=0}
+\pgfmathprintnumber{123456999}\hspace{1em}
+\pgfmathprintnumber{123456999.12}
+\end{codeexample}
+ %
+ \noindent Here, |precision=0| means that we inspect |123456.999| and round
+ that number to $0$ digits. Finally, we move the period back to its initial
+ position. Adding |relative style=fixed| results in fixed point output
+ format:
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,relative*={3},precision=0,relative style=fixed}
+\pgfmathprintnumber{123456999}\hspace{1em}
+\pgfmathprintnumber{123456999.12}
+\end{codeexample}
+ %
+ \noindent Note that there is another alternative for this use-case which is
+ discussed later: the |fixed relative| style.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,fixed relative,precision=6}
+\pgfmathprintnumber{123456999}\hspace{1em}
+\pgfmathprintnumber{123456999.12}
+\end{codeexample}
+
+ You might wonder why there is an asterisk in the key's name. The short
+ answer is: there is also a \declareandlabel{/pgf/number format/relative}
+ number printer which does unexpected things. The key |relative*| repairs
+ this. Existing code will still use the old behavior.
+
+ Technically, the key works as follows: as already explained above,
+ |relative*=3| key applied to |123456999.12| moves the period by three
+ positions and analyzes |123456.99912|. Mathematically speaking, we are
+ given a number $x = \pm m \cdot 10^e$ and we attempt to apply
+ |relative*=|$r$. The method then rounds $x / 10^r$ to |precision| digits.
+ Afterwards, it multiplies the result by $10^r$ and typesets it.
+\end{keylist}
+
+\begin{stylekey}{/pgf/number format/every relative}
+ A style which configures how the |relative| method finally displays its
+ results.
+
+ The initial configuration is
+ %
+\begin{codeexample}[code only]
+\pgfkeys{/pgf/number format/every relative/.style=std}
+\end{codeexample}
+
+ Note that rounding is turned off when the resulting style is being
+ evaluated (since |relative| already rounded the number).
+
+ Although supported, I discourage from using |fixed zerofill| or
+ |sci zerofill| in this context -- it may lead to a suggestion of higher
+ precision than is actually used (because |fixed zerofill| might simply add
+ |.00| although there was a different information before |relative| rounded
+ the result).
+\end{stylekey}
+
+\begin{key}{/pgf/number format/relative style=\marg{options}}
+ The same as |every relative/.append style=|\marg{options}.
+\end{key}
+
+\begin{keylist}{/pgf/number format/fixed relative}
+ Configures |\pgfmathprintnumber| to format numbers in a similar way to the
+ |fixed| style, but the |precision| is interpreted relatively to the
+ number's exponent.
+
+ The motivation is to get the same rounding effect as for |sci|, but to
+ display the number in the |fixed| style:
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,fixed relative,precision=3}
+\pgfmathprintnumber{1000.0123}\hspace{1em}
+\pgfmathprintnumber{100.0567}\hspace{1em}
+\pgfmathprintnumber{0.000010003452}\hspace{1em}
+\pgfmathprintnumber{0.010073452}\hspace{1em}
+\pgfmathprintnumber{1.23567}\hspace{1em}
+\pgfmathprintnumber{1003.75}\hspace{1em}
+\pgfmathprintnumber{1006.75}\hspace{1em}
+\end{codeexample}
+
+ The effect of |fixed relative| is that the number is rounded to
+ \emph{exactly} the first \meta{precision} non-zero digits, no matter how
+ many leading zeros the number might have.
+
+ Use |fixed relative| if you want |fixed| and if you know that only the
+ first $n$ digits are correct. Use |sci| if you need a scientific display
+ style and only the first $n$ digits are correct.
+
+ Note that |fixed relative| ignores the |fixed zerofill| flag.
+
+ See also the |relative*| key. Note that the |relative=|\marg{exponent} key
+ explicitly moves the period to some designated position before it attempts
+ to round the number. Afterwards, it ``rounds from the right'', i.e.\ it
+ rounds to that explicitly chosen digit position. In contrast to that,
+ |fixed relative| ``rounds from the left'': it takes the \emph{first}
+ non-zero digit, temporarily places the period after this digit, and rounds
+ that number. The rounding style |fixed| leaves the period where it is, and
+ rounds everything behind that digit. The |sci| style is similar to |fixed
+ relative|.
+\end{keylist}
+
+\begin{key}{/pgf/number format/int detect}
+ Configures |\pgfmathprintnumber| to detect integers automatically. If the
+ input number is an integer, no period is displayed at all. If not, the
+ scientific format is chosen.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,int detect,precision=2}
+\pgfmathprintnumber{15}\hspace{1em}
+\pgfmathprintnumber{20}\hspace{1em}
+\pgfmathprintnumber{20.4}\hspace{1em}
+\pgfmathprintnumber{0.01}\hspace{1em}
+\pgfmathprintnumber{0}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{command}{\pgfmathifisint\marg{number constant}\marg{true code}\marg{false code}}
+ A command which does the same check as |int detect|, but it invokes
+ \meta{true code} if the \meta{number constant} actually is an integer and
+ the \meta{false code} if not.
+
+ As a side-effect, |\pgfretval| will contain the parsed number, either in
+ integer format or as parsed floating point number.
+
+ The argument \meta{number constant} will be parsed with
+ |\pgfmathfloatparsenumber|.
+ %
+\begin{codeexample}[]
+15 \pgfmathifisint{15}{is an int: \pgfretval.}{is no int}\hspace{1em}
+15.5 \pgfmathifisint{15.5}{is an int: \pgfretval.}{is no int}
+\end{codeexample}
+ %
+\end{command}
+
+\begin{key}{/pgf/number format/int trunc}
+ Truncates every number to integers (discards any digit after the period).
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,int trunc}
+\pgfmathprintnumber{4.568}\hspace{1em}
+\pgfmathprintnumber{5e-04}\hspace{1em}
+\pgfmathprintnumber{0.1}\hspace{1em}
+\pgfmathprintnumber{24415.98123}\hspace{1em}
+\pgfmathprintnumber{123456.12345}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/number format/frac}
+ Displays numbers as fractionals.
+ %
+\begin{codeexample}[width=3cm]
+\pgfkeys{/pgf/number format/frac}
+\pgfmathprintnumber{0.333333333333333}\hspace{1em}
+\pgfmathprintnumber{0.5}\hspace{1em}
+\pgfmathprintnumber{2.133333333333325e-01}\hspace{1em}
+\pgfmathprintnumber{0.12}\hspace{1em}
+\pgfmathprintnumber{2.666666666666646e-02}\hspace{1em}
+\pgfmathprintnumber{-1.333333333333334e-02}\hspace{1em}
+\pgfmathprintnumber{7.200000000000000e-01}\hspace{1em}
+\pgfmathprintnumber{6.666666666666667e-02}\hspace{1em}
+\pgfmathprintnumber{1.333333333333333e-01}\hspace{1em}
+\pgfmathprintnumber{-1.333333333333333e-02}\hspace{1em}
+\pgfmathprintnumber{3.3333333}\hspace{1em}
+\pgfmathprintnumber{1.2345}\hspace{1em}
+\pgfmathprintnumber{1}\hspace{1em}
+\pgfmathprintnumber{-6}
+\end{codeexample}
+
+ \begin{key}{/pgf/number format/frac TeX=\marg{\textbackslash macro} (initially \texttt{\textbackslash frac})}
+ Allows to use a different implementation for |\frac| inside of the
+ |frac| display type.
+ \end{key}
+
+ \begin{key}{/pgf/number format/frac denom=\meta{int} (initially empty)}
+ Allows to provide a custom denominator for |frac|.
+ %
+\begin{codeexample}[width=3cm]
+\pgfkeys{/pgf/number format/.cd,frac, frac denom=10}
+\pgfmathprintnumber{0.1}\hspace{1em}
+\pgfmathprintnumber{0.5}\hspace{1em}
+\pgfmathprintnumber{1.2}\hspace{1em}
+\pgfmathprintnumber{-0.6}\hspace{1em}
+\pgfmathprintnumber{-1.4}\hspace{1em}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/number format/frac whole=\mchoice{true,false} (initially true)}
+ Configures whether complete integer parts shall be placed in front of
+ the fractional part. In this case, the fractional part will be less
+ then $1$. Use |frac whole=false| to avoid whole number parts.
+ %
+\begin{codeexample}[width=3cm]
+\pgfkeys{/pgf/number format/.cd,frac, frac whole=false}
+\pgfmathprintnumber{20.1}\hspace{1em}
+\pgfmathprintnumber{5.5}\hspace{1em}
+\pgfmathprintnumber{1.2}\hspace{1em}
+\pgfmathprintnumber{-5.6}\hspace{1em}
+\pgfmathprintnumber{-1.4}\hspace{1em}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/number format/frac shift=\marg{integer} (initially 4)}
+ In case you experience problems because of stability problems, try
+ experimenting with a different |frac shift|. Higher shift values $k$
+ yield higher sensitivity to inaccurate data or inaccurate arithmetics.
+
+ Technically, the following happens. If $r < 1$ is the fractional part
+ of the mantissa, then a scale $i = 1/r \cdot 10^k$ is computed where
+ $k$ is the shift; fractional parts of $i$ are neglected. The value
+ $1/r$ is computed internally, its error is amplified.
+
+ If you still experience stability problems, use |\usepackage{fp}| in
+ your preamble. The |frac| style will then automatically employ the
+ higher absolute precision of |fp| for the computation of $1/r$.
+ \end{key}
+\end{key}
+
+\begin{key}{/pgf/number format/precision=\marg{number}}
+ Sets the desired rounding precision for any display operation. For
+ scientific format, this affects the mantissa.
+\end{key}
+
+\begin{key}{/pgf/number format/sci precision=\meta{number or empty} (initially empty)}
+ Sets the desired rounding precision only for |sci| styles.
+
+ Use |sci precision={}| to restore the initial configuration (which uses the
+ argument provided to |precision| for all number styles).
+\end{key}
+
+\begin{key}{/pgf/number format/read comma as period=\mchoice{true,false} (initially false)}
+ This is one of the few keys which allows to customize the number parser. If
+ this switch is turned on, a comma is read just as a period.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/read comma as period}
+\pgfmathprintnumber{1234,56}
+\end{codeexample}
+ %
+ This is typically undesired as it can cause side-effects with math parsing
+ instructions. However, it is supported to format input numbers or input
+ tables. Consider |use comma| to typeset the result with a comma as well.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ read comma as period,
+ use comma}
+\pgfmathprintnumber{1234,56}
+\end{codeexample}
+ %
+\end{key}
+
+
+\subsection{Changing display styles}%
+\label{sec:number:styles}
+
+You can change the way how numbers are displayed. For example, if you use the
+`\texttt{fixed}' style, the input number is rounded to the desired precision
+and the current fixed point display style is used to typeset the number. The
+same is applied to any other format: first, rounding routines are used to get
+the correct digits, afterwards a display style generates proper \TeX-code.
+
+\begin{key}{/pgf/number format/set decimal separator=\marg{text}}
+ Assigns \marg{text} as decimal separator for any fixed point numbers
+ (including the mantissa in sci format).
+
+ Use |\pgfkeysgetvalue{/pgf/number format/set decimal separator}\value| to
+ get the current separator into |\value|.
+\end{key}
+
+\begin{stylekey}{/pgf/number format/dec sep=\marg{text}}
+ Just another name for |set decimal separator|.
+\end{stylekey}
+
+\begin{key}{/pgf/number format/set thousands separator=\marg{text}}
+ Assigns \marg{text} as thousands separator for any fixed point numbers
+ (including the mantissa in sci format).
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ fixed,
+ fixed zerofill,
+ precision=2,
+ set thousands separator={}}
+\pgfmathprintnumber{1234.56}
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ fixed,
+ fixed zerofill,
+ precision=2,
+ set thousands separator={}}
+\pgfmathprintnumber{1234567890}
+\end{codeexample}
+
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ fixed,
+ fixed zerofill,
+ precision=2,
+ set thousands separator={.}}
+\pgfmathprintnumber{1234567890}
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ fixed,
+ fixed zerofill,
+ precision=2,
+ set thousands separator={,}}
+\pgfmathprintnumber{1234567890}
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ fixed,
+ fixed zerofill,
+ precision=2,
+ set thousands separator={{{,}}}}
+\pgfmathprintnumber{1234567890}
+\end{codeexample}
+ %
+ The last example employs commas and disables the default comma-spacing.
+
+ Use |\pgfkeysgetvalue{/pgf/number format/set thousands separator}\value| to
+ get the current separator into |\value|.
+\end{key}
+
+\begin{stylekey}{/pgf/number format/1000 sep=\marg{text}}
+ Just another name for |set thousands separator|.
+\end{stylekey}
+
+\begin{key}{/pgf/number format/1000 sep in fractionals=\marg{boolean} (initially false)}
+ Configures whether the fractional part should also be grouped into groups
+ of three digits.
+
+ The value |true| will active the |1000 sep| for both, integer and
+ fractional parts. The value |false| will active |1000 sep| only for the
+ integer part.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ fixed,
+ precision=999,
+ set thousands separator={\,},
+ 1000 sep in fractionals,
+ }
+\pgfmathprintnumber{1234.1234567}
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ fixed,fixed zerofill,
+ precision=9,
+ set thousands separator={\,},
+ 1000 sep in fractionals,
+ }
+\pgfmathprintnumber{1234.1234567}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/number format/min exponent for 1000 sep=\marg{number} (initially 0)}
+ Defines the smallest exponent in scientific notation which is required to
+ draw thousand separators. The exponent is the number of digits minus one,
+ so $\meta{number}=4$ will use thousand separators starting with $1e4 =
+ 10000$.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ int detect,
+ 1000 sep={\,},
+ min exponent for 1000 sep=0}
+\pgfmathprintnumber{5000}; \pgfmathprintnumber{1000000}
+\end{codeexample}
+
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ int detect,
+ 1000 sep={\,},
+ min exponent for 1000 sep=4}
+\pgfmathprintnumber{1000}; \pgfmathprintnumber{5000}
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ int detect,
+ 1000 sep={\,},
+ min exponent for 1000 sep=4}
+\pgfmathprintnumber{10000}; \pgfmathprintnumber{1000000}
+\end{codeexample}
+ %
+ \noindent A value of |0| disables this feature (negative values are
+ ignored).
+\end{key}
+
+\begin{key}{/pgf/number format/use period}
+ A predefined style which installs periods ``\texttt{.}'' as decimal
+ separators and commas ``\texttt{,}'' as thousands separators. This style is
+ the default.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use period}
+\pgfmathprintnumber{12.3456}
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use period}
+\pgfmathprintnumber{1234.56}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/number format/use comma}
+ A predefined style which installs commas ``\texttt{,}'' as decimal
+ separators and periods ``\texttt{.}'' as thousands separators.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use comma}
+\pgfmathprintnumber{12.3456}
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use comma}
+\pgfmathprintnumber{1234.56}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/number format/skip 0.=\marg{boolean} (initially false)}
+ Configures whether numbers like $0.1$ shall be typeset as $.1$ or not.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ fixed,
+ fixed zerofill,precision=2,
+ skip 0.}
+\pgfmathprintnumber{0.56}
+\end{codeexample}
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,
+ fixed,
+ fixed zerofill,precision=2,
+ skip 0.=false}
+\pgfmathprintnumber{0.56}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/number format/showpos=\marg{boolean} (initially false)}
+ Enables or disables the display of plus signs for non-negative numbers.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/showpos}
+\pgfmathprintnumber{12.345}
+\end{codeexample}
+
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/showpos=false}
+\pgfmathprintnumber{12.345}
+\end{codeexample}
+
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,showpos,sci}
+\pgfmathprintnumber{12.345}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{stylekey}{/pgf/number format/print sign=\marg{boolean}}
+ A style which is simply an alias for |showpos=|\marg{boolean}.
+\end{stylekey}
+
+\begin{key}{/pgf/number format/sci 10e}
+ Uses $m \cdot 10^e$ for any number displayed in scientific format.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,sci,sci 10e}
+\pgfmathprintnumber{12.345}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/number format/sci 10\textasciicircum e}
+ The same as `|sci 10e|'.
+\end{key}
+
+\begin{key}{/pgf/number format/sci e}
+ Uses the `$1e{+}0$' format which is generated by common scientific tools
+ for any number displayed in scientific format.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,sci,sci e}
+\pgfmathprintnumber{12.345}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/number format/sci E}
+ The same with an uppercase `\texttt{E}'.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,sci,sci E}
+\pgfmathprintnumber{12.345}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/number format/sci subscript}
+ Typesets the exponent as subscript for any number displayed in scientific
+ format. This style requires very little space.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,sci,sci subscript}
+\pgfmathprintnumber{12.345}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/number format/sci superscript}
+ Typesets the exponent as superscript for any number displayed in scientific
+ format. This style requires very little space.
+ %
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,sci,sci superscript}
+\pgfmathprintnumber{12.345}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/pgf/number format/sci generic=\marg{keys}}
+ Allows to define an own number style for the scientific format. Here,
+ \meta{keys} can be one of the following choices (omit the long key prefix):
+
+ \begin{key}{/pgf/number format/sci generic/mantissa sep=\marg{text} (initially empty)}
+ Provides the separator between a mantissa and the exponent. It might be
+ |\cdot|, for example,
+ \end{key}
+ %
+ \begin{key}{/pgf/number format/sci generic/exponent=\marg{text} (initially empty)}
+ Provides text to format the exponent. The actual exponent is available
+ as argument |#1| (see below).
+ \end{key}
+ %
+\begin{codeexample}[]
+\pgfkeys{
+ /pgf/number format/.cd,
+ sci,
+ sci generic={mantissa sep=\times,exponent={10^{#1}}}}
+\pgfmathprintnumber{12.345};
+\pgfmathprintnumber{0.00012345}
+\end{codeexample}
+ %
+ The \meta{keys} can depend on three parameters, namely on |#1| which is the
+ exponent, |#2| containing the flags entity of the floating point number and
+ |#3| is the (unprocessed and unformatted) mantissa.
+
+ Note that |sci generic| is \emph{not} suitable to modify the appearance of
+ fixed point numbers, nor can it be used to format the mantissa (which is
+ typeset like fixed point numbers). Use |dec sep|, |1000 sep| and
+ |print sign| to customize the mantissa.
+\end{key}
+
+\begin{key}{/pgf/number format/retain unit mantissa=\mchoice{true,false} (initially true)}
+ Allows to omit a unit mantissa.
+ %
+\begin{codeexample}[]
+\pgfkeys{
+ /pgf/number format/.cd,
+ sci, retain unit mantissa=false}
+\pgfmathprintnumber{10.5};
+\pgfmathprintnumber{10};
+\pgfmathprintnumber{1010};
+\pgfmathprintnumber[precision=1]{-1010};
+\end{codeexample}
+ %
+ The feature is applied after rounding to the desired precision: if the
+ remaining mantissa is equal to~$1$, it will be omitted. It applies to all
+ styles involving the scientific format (including |std|).
+\end{key}
+
+\begin{key}{/pgf/number format/\protect\atmarktext dec sep mark=\marg{text}}
+ Will be placed right before the place where a decimal separator belongs to.
+ However, \marg{text} will be inserted even if there is no decimal
+ separator. It is intended as place-holder for auxiliary routines to find
+ alignment positions.
+
+ This key should never be used to change the decimal separator!
+ Use |dec sep| instead.
+\end{key}
+
+\begin{key}{/pgf/number format/\protect\atmarktext sci exponent mark=\marg{text}}
+ Will be placed right before exponents in scientific notation. It is
+ intended as place-holder for auxiliary routines to find alignment
+ positions.
+
+ This key should never be used to change the exponent!
+\end{key}
+
+\begin{key}{/pgf/number format/assume math mode=\marg{boolean} (default true)}
+ Set this to |true| if you don't want any checks for math mode. The initial
+ setting checks whether math mode is active using |\pgfutilensuremath| for
+ each final number.
+
+ Use |assume math mode=true| if you know that math mode is active. In that
+ case, the final number is typeset as-is, no further checking is performed.
+\end{key}
+
+\begin{stylekey}{/pgf/number format/verbatim}
+ A style which configures the number printer to produce verbatim text
+ output, i.\,e., it doesn't contain \TeX\ macros.
+ %
+\begin{codeexample}[]
+\pgfkeys{
+ /pgf/fpu,
+ /pgf/number format/.cd,
+ sci,
+ verbatim}
+\pgfmathprintnumber{12.345};
+\pgfmathprintnumber{0.00012345};
+\pgfmathparse{exp(15)}
+\pgfmathprintnumber{\pgfmathresult}
+\end{codeexample}
+ %
+ The style resets |1000 sep|, |dec sep|, |print sign|, |skip 0.| and sets
+ |assume math mode|. Furthermore, it installs a |sci generic| format for
+ verbatim output of scientific numbers.
+
+ However, it will still respect |precision|, |fixed zerofill|, |sci
+ zerofill| and the overall styles |fixed|, |sci|, |int detect| (and their
+ variants). It might be useful if you intend to write output files.
+\end{stylekey}
+
+
+%--------------------------------------------------
+% \subsubsection{Defining own display styles}
+% You can define own display styles, although this may require some insight into \TeX-programming. Here are two examples:
+% \begin{enumerate}
+% \item A new fixed point display style: The following code defines a new style named `\texttt{my own fixed point style}' which uses $1{\cdot}00$ instead of $1.00$.
+% \begin{lstlisting}
+% \def\myfixedpointstyleimpl#1.#2\relax{%
+% #1{\cdot}#2%
+% }%
+% \def\myfixedpointstyle#1{%
+% \pgfutilensuremath{%
+% \ifpgfmathfloatroundhasperiod
+% \expandafter\myfixedpointstyleimpl#1\relax
+% \else
+% #1%
+% \fi
+% }%
+% }
+% \pgfkeys{/my own fixed point style/.code={%
+% \let\pgfmathprintnumber@fixed@style=\myfixedpointstyle}
+% }%
+% \end{lstlisting}
+% You only need to overwrite the macro \lstinline!\pgfmathprintnumber@fixed@style!. This macro takes one argument (the result of any numerical computations). The \TeX-boolean \lstinline!\ifpgfmathfloatroundhasperiod! is true if and only if the input number contains a period.
+%
+% \item An example for a new scientific display style:
+% \begin{lstlisting}
+% % #1:
+% % 0 == '0' (the number is +- 0.0),
+% % 1 == '+',
+% % 2 == '-',
+% % 3 == 'not a number'
+% % 4 == '+ infinity'
+% % 5 == '- infinity'
+% % #2: the mantissa
+% % #3: the exponent
+% \def\myscistyle#1#2e#3\relax{%
+% ...
+% }
+% \pgfkeys{/my own sci style/.code={%
+% \let\pgfmathfloatrounddisplaystyle=\myscistyle},
+% }%
+% \end{lstlisting}
+% \end{enumerate}
+%--------------------------------------------------