\section{Number Printing}

\label{pgfmath-numberprinting}%

{\emph{An extension by Christian Feuers\"anger}}

\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 \marg{x}. The input number \marg{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}|]|\marg{x}.
\end{command}

\begin{command}{\pgfmathprintnumberto\marg{x}\marg{\textbackslash macro}}
	Returns the resulting number into \marg{\textbackslash 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 scientific format can be adjusted with |sci precision| if necessary.

\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}

\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/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 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 few 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 few 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/@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/@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 intent 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}
%--------------------------------------------------