☰
PGF/TikZ Manual | PGFplots | TikZ Editor

TikZ and PGF Manual

Mathematical and Object-Oriented Engines

97 Number Printing

An extension by Christian Feuersänger

pgf supports number printing in different styles and rounds to arbitrary precision.

  • \pgfmathprintnumber{⟨x⟩}

    • Generates pretty-printed output for the (real) number ⟨x⟩. The input number ⟨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[⟨options⟩]⟨x⟩.

  • /pgf/number format/relative*=⟨exponent base 10⟩(no default)

    • 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.

First use-case:

provide a unified format for a sequence of numbers. Consider the following test:

(image)


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

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.

(image)


\pgfkeys{/pgf/number format/relative*={2}}
\pgfmathprintnumber{123.345}\hspace{1em}
\pgfmathprintnumber{0.0012}\hspace{1em}
\pgfmathprintnumber{0.0014}\hspace{1em}

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.

(image)


\pgfkeys{/pgf/number format/relative*={-3}}
\pgfmathprintnumber{123.345}\hspace{1em}
\pgfmathprintnumber{0.0012}\hspace{1em}
\pgfmathprintnumber{0.0014}\hspace{1em}

Second use-case:

improve rounding in the presence of inaccurate numbers. Let us suppose that some limited-precision arithmetic resulted in the result 123456999 (like the fpu of pgf). 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:

(image)


\pgfkeys{/pgf/number format/.cd,relative*={3},precision=0}
\pgfmathprintnumber{123456999}\hspace{1em}
\pgfmathprintnumber{123456999.12}

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:

(image)


\pgfkeys{/pgf/number format/.cd,relative*={3},precision=0,relative style=fixed}
\pgfmathprintnumber{123456999}\hspace{1em}
\pgfmathprintnumber{123456999.12}

Note that there is another alternative for this use-case which is discussed later: the fixed relative style.

(image)


\pgfkeys{/pgf/number format/.cd,fixed relative,precision=6}
\pgfmathprintnumber{123456999}\hspace{1em}
\pgfmathprintnumber{123456999.12}

You might wonder why there is an asterisk in the key’s name. The short answer is: there is also a /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.

  • /pgf/number format/relative style={⟨options⟩}(no default)

    • The same as every relative/.append style={⟨options⟩}.

  • /pgf/number format/fixed relative(no value)

    • 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:

    (image)


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

    The effect of fixed relative is that the number is rounded to exactly the first ⟨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={⟨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 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.

  • /pgf/number format/precision={⟨number⟩}(no default)

    • Sets the desired rounding precision for any display operation. For scientific format, this affects the mantissa.

  • /pgf/number format/sci precision=⟨number or empty⟩ (no default, 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).

97.1 Changing display styles

You can change the way how numbers are displayed. For example, if you use the ‘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 -code.

  • /pgf/number format/dec sep={⟨text⟩}(style, no default)

    • Just another name for set decimal separator.

Testing comma  to see what happens after the end of key.

Checking  comma.

  • /pgf/number format/sci e(no value)

    • Uses the ‘\(1e{+}0\)’ format which is generated by common scientific tools for any number displayed in scientific format.

    (image)


    \pgfkeys{/pgf/number format/.cd,sci,sci e}
    \pgfmathprintnumber{12.345}

  • /pgf/number format/@dec sep mark={⟨text⟩}(no default)

    • Will be placed right before the place where a decimal separator belongs to. However, {⟨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.

  • /pgf/number format/@sci exponent mark={⟨text⟩}(no default)

    • 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!