## 10 Formatted Output ¶

### 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 two’s 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.

### 10.2 Functions ¶

Each of the following functions is similar to the corresponding C library function. The basic `printf` forms take a variable argument list. The `vprintf` forms take an argument pointer, see Variadic Functions in The GNU C Library Reference Manual, or ‘`man 3 va_start`’.

It should be emphasised that if a format string is invalid, or the arguments don’t match what the format specifies, then the behaviour of any of these functions will be unpredictable. GCC format string checking is not available, since it doesn’t recognise the GMP extensions.

The file based functions `gmp_printf` and `gmp_fprintf` will return -1 to indicate a write error. Output is not “atomic”, so partial output may be produced if a write error occurs. All the functions can return -1 if the C library `printf` variant in use returns -1, but this shouldn’t normally occur.

Function: `int` gmp_printf `(const char *fmt, …)` ¶
Function: `int` gmp_vprintf `(const char *fmt, va_list ap)` ¶

  Print to the standard output `stdout`. Return the number of characters written, or -1 if an error occurred.

Function: `int` gmp_fprintf `(FILE *fp, const char *fmt, …)` ¶
Function: `int` gmp_vfprintf `(FILE *fp, const char *fmt, va_list ap)` ¶

  Print to the stream fp. Return the number of characters written, or -1 if an error occurred.

Function: `int` gmp_sprintf `(char *buf, const char *fmt, …)` ¶
Function: `int` gmp_vsprintf `(char *buf, const char *fmt, va_list ap)` ¶

  Form a null-terminated string in buf. Return the number of characters written, excluding the terminating null.

  No overlap is permitted between the space at buf and the string fmt.

  These functions are not recommended, since there’s no protection against exceeding the space available at buf.

Function: `int` gmp_snprintf `(char *buf, size_t size, const char *fmt, …)` ¶
Function: `int` gmp_vsnprintf `(char *buf, size_t size, const char *fmt, va_list ap)` ¶

  Form a null-terminated string in buf. No more than size bytes will be written. To get the full output, size must be enough for the string and null-terminator.

  The return value is the total number of characters which ought to have been produced, excluding the terminating null. If retval >= size then the actual output has been truncated to the first size-1 characters, and a null appended.

  No overlap is permitted between the region {buf,size} and the fmt string.

  Notice the return value is in ISO C99 `snprintf` style. This is so even if the C library `vsnprintf` is the older GLIBC 2.0.x style.

Function: `int` gmp_asprintf `(char **pp, const char *fmt, …)` ¶
Function: `int` gmp_vasprintf `(char **pp, const char *fmt, va_list ap)` ¶

  Form a null-terminated string in a block of memory obtained from the current memory allocation function (see Custom Allocation). The block will be the size of the string and null-terminator. The address of the block is stored to *pp. The return value is the number of characters produced, excluding the null-terminator.

  Unlike the C library `asprintf`, `gmp_asprintf` doesn’t return -1 if there’s no more memory available, it lets the current allocation function handle that.

Function: `int` gmp_obstack_printf `(struct obstack *ob, const char *fmt, …)` ¶
Function: `int` gmp_obstack_vprintf `(struct obstack *ob, const char *fmt, va_list ap)` ¶

  Append to the current object in ob. The return value is the number of characters written. A null-terminator is not written.

  fmt cannot be within the current object in ob, since that object might move as it grows.

  These functions are available only when the C library provides the obstack feature, which probably means only on GNU systems, see Obstacks in The GNU C Library Reference Manual.

### 10.3 C++ Formatted Output ¶

The following functions are provided in `libgmpxx` (see Headers and Libraries), which is built if C++ support is enabled (see Build Options). Prototypes are available from `<gmp.h>`.

Function: `ostream&` operator<< `(ostream& stream, const mpz_t op)` ¶

  Print op to stream, using its `ios` formatting settings. `ios::width` is reset to 0 after output, the same as the standard `ostream operator<<` routines do.

  In hex or octal, op is printed as a signed number, the same as for decimal. This is unlike the standard `operator<<` routines on `int` etc, which instead give two’s complement.

Function: `ostream&` operator<< `(ostream& stream, const mpq_t op)` ¶

  Print op to stream, using its `ios` formatting settings. `ios::width` is reset to 0 after output, the same as the standard `ostream operator<<` routines do.

  Output will be a fraction like ‘`5/9`’, or if the denominator is 1 then just a plain integer like ‘`123`’.

  In hex or octal, op is printed as a signed value, the same as for decimal. If `ios::showbase` is set then a base indicator is shown on both the numerator and denominator (if the denominator is required).

Function: `ostream&` operator<< `(ostream& stream, const mpf_t op)` ¶

  Print op to stream, using its `ios` formatting settings. `ios::width` is reset to 0 after output, the same as the standard `ostream operator<<` routines do.

  The decimal point follows the standard library float `operator<<`, which on recent systems means the `std::locale` imbued on stream.

  Hex and octal are supported, unlike the standard `operator<<` on `double`. The mantissa will be in hex or octal, the exponent will be in decimal. For hex the exponent delimiter is an ‘`@`’. This is as per `mpf_out_str`.

  `ios::showbase` is supported, and will put a base on the mantissa, for example hex ‘`0x1.8`’ or ‘`0x0.8`’, or octal ‘`01.4`’ or ‘`00.4`’. This last form is slightly strange, but at least differentiates itself from decimal.

These operators mean that GMP types can be printed in the usual C++ way, for example,

    mpz_t  z;
    int    n;
    ...
    cout << "iteration " << n << " value " << z << "\n";

But note that `ostream` output (and `istream` input, see C++ Formatted Input) is the only overloading available for the GMP types and that for instance using `+` with an `mpz_t` will have unpredictable results. For classes with overloading, see C++ Class Interface.