Formatted Output Strings (GNU MP 6.2.1)
Description: How to install and use the GNU multiple precision arithmetic library, version 6.2.1.

Next: Formatted Output Functions, Previous: Formatted Output, Up: Formatted Output [Index]

### 10.1 Format Strings

`gmp_printf` and friends accept format strings similar to the standard C `printf` (see Formatted Output in The GNU C Library Reference Manual). A format specification is of the form

    % [flags] [width] [.[precision]] [type] conv

GMP adds types ‘`Z`’, ‘`Q`’ and ‘`F`’ for `mpz_t`, `mpq_t` and `mpf_t` respectively, ‘`M`’ for `mp_limb_t`, and ‘`N`’ for an `mp_limb_t` array. ‘`Z`’, ‘`Q`’, ‘`M`’ and ‘`N`’ behave like integers. ‘`Q`’ will print a ‘`/`’ and a denominator, if needed. ‘`F`’ behaves like a float. For example,

    mpz_t z;
    gmp_printf ("%s is an mpz %Zd\n", "here", z);

    mpq_t q;
    gmp_printf ("a hex rational: %#40Qx\n", q);

    mpf_t f;
    int   n;
    gmp_printf ("fixed point mpf %.*Ff with %d digits\n", n, f, n);

    mp_limb_t l;
    gmp_printf ("limb %Mu\n", l);

    const mp_limb_t *ptr;
    mp_size_t       size;
    gmp_printf ("limb array %Nx\n", ptr, size);

For ‘`N`’ the limbs are expected least significant first, as per the `mpn` functions (see Low-level Functions). A negative size can be given to print the value as a negative.

All the standard C `printf` types behave the same as the C library `printf`, and can be freely intermixed with the GMP extensions. In the current implementation the standard parts of the format string are simply handed to `printf` and only the GMP extensions handled directly.

The flags accepted are as follows. GLIBC style ‘`'`’ is only for the standard C types (not the GMP types), and only if the C library supports it.

> `0` | pad with zeros (rather than spaces)
> `#` | show the base with ‘`0x`’, ‘`0X`’ or ‘`0`’
> `+` | always show a sign
> (space) | show a space or a ‘`-`’ sign
> `'` | group digits, GLIBC style (not GMP types)

The optional width and precision can be given as a number within the format string, or as a ‘`*`’ to take an extra parameter of type `int`, the same as the standard `printf`.

The standard types accepted are as follows. ‘`h`’ and ‘`l`’ are portable, the rest will depend on the compiler (or include files) for the type and the C library for the output.

> `h` | `short`
> `hh` | `char`
> `j` | `intmax_t` or `uintmax_t`
> `l` | `long` or `wchar_t`
> `ll` | `long long`
> `L` | `long double`
> `q` | `quad_t` or `u_quad_t`
> `t` | `ptrdiff_t`
> `z` | `size_t`

The GMP types are

> `F` | `mpf_t`, float conversions
> `Q` | `mpq_t`, integer conversions
> `M` | `mp_limb_t`, integer conversions
> `N` | `mp_limb_t` array, integer conversions
> `Z` | `mpz_t`, integer conversions

The conversions accepted are as follows. ‘`a`’ and ‘`A`’ are always supported for `mpf_t` but depend on the C library for standard C float types. ‘`m`’ and ‘`p`’ depend on the C library.

> `a` `A` | hex floats, C99 style
> `c` | character
> `d` | decimal integer
> `e` `E` | scientific format float
> `f` | fixed point float
> `i` | same as `d`
> `g` `G` | fixed or scientific float
> `m` | `strerror` string, GLIBC style
> `n` | store characters written so far
> `o` | octal integer
> `p` | pointer
> `s` | string
> `u` | unsigned integer
> `x` `X` | hex integer

‘`o`’, ‘`x`’ and ‘`X`’ are unsigned for the standard C types, but for types ‘`Z`’, ‘`Q`’ and ‘`N`’ they are signed. ‘`u`’ is not meaningful for ‘`Z`’, ‘`Q`’ and ‘`N`’.

‘`M`’ is a proxy for the C library ‘`l`’ or ‘`L`’, according to the size of `mp_limb_t`. Unsigned conversions will be usual, but a signed conversion can be used and will interpret the value as a twos complement negative.

‘`n`’ can be used with any type, even the GMP types.

Other types or conversions that might be accepted by the C library `printf` cannot be used through `gmp_printf`, this includes for instance extensions registered with GLIBC `register_printf_function`. Also currently there’s no support for POSIX ‘`$`’ style numbered arguments (perhaps this will be added in the future).

The precision field has its usual meaning for integer ‘`Z`’ and float ‘`F`’ types, but is currently undefined for ‘`Q`’ and should not be used with that.

`mpf_t` conversions only ever generate as many digits as can be accurately represented by the operand, the same as `mpf_get_str` does. Zeros will be used if necessary to pad to the requested precision. This happens even for an ‘`f`’ conversion of an `mpf_t` which is an integer, for instance 2^1024 in an `mpf_t` of 128 bits precision will only produce about 40 digits, then pad with zeros to the decimal point. An empty precision field like ‘`%.Fe`’ or ‘`%.Ff`’ can be used to specifically request just the significant digits. Without any dot and thus no precision field, a precision value of 6 will be used. Note that these rules mean that ‘`%Ff`’, ‘`%.Ff`’, and ‘`%.0Ff`’ will all be different.

The decimal point character (or string) is taken from the current locale settings on systems which provide `localeconv` (see Locales and Internationalization in The GNU C Library Reference Manual). The C library will normally do the same for standard float output.

The format string is only interpreted as plain `char`s, multibyte characters are not recognised. Perhaps this will change in the future.

Next: Formatted Output Functions, Previous: Formatted Output, Up: Formatted Output [Index]