### 5.9 Formatted Output Functions ¶

#### 5.9.1 Requirements ¶

The class of `mpfr_printf` functions provides formatted output in a similar manner as the standard C `printf`. These functions are defined only if your system supports ISO C variadic functions and the corresponding argument access macros.

When using any of these functions, you must include the `<stdio.h>` standard header before `mpfr.h`, to allow `mpfr.h` to define prototypes for these functions.

#### 5.9.2 Format String ¶

The format specification accepted by `mpfr_printf` is an extension of the `gmp_printf` one (itself, an extension of the `printf` one). The conversion specification is of the form:

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

‘`flags`’, ‘`width`’, and ‘`precision`’ have the same meaning as for the standard `printf` (in particular, notice that the precision is related to the number of digits displayed in the base chosen by ‘`conv`’ and not related to the internal precision of the `mpfr_t` variable), but note that for ‘`Re`’, the default precision is not the same as the one for ‘`e`’. `mpfr_printf` accepts the same ‘`type`’ specifiers as GMP (except the non-standard and deprecated ‘`q`’, use ‘`ll`’ instead), namely the length modifiers defined in the C standard:

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

and the ‘`type`’ specifiers defined in GMP, plus ‘`R`’ and ‘`P`’, which are specific to MPFR (the second column in the table below shows the type of the argument read in the argument list and the kind of ‘`conv`’ specifier to use after the ‘`type`’ specifier):

> ‘`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
> ‘`P`’ | `mpfr_prec_t`, integer conversions
> ‘`R`’ | `mpfr_t`, float conversions

The ‘`type`’ specifiers have the same restrictions as those mentioned in the GMP documentation: see Section “Formatted Output Strings” in GNU MP. In particular, the ‘`type`’ specifiers (except ‘`R`’ and ‘`P`’) are supported only if they are supported by `gmp_printf` in your GMP build; this implies that the standard specifiers, such as ‘`t`’, must also be supported by your C library if you want to use them.

The ‘`rounding`’ field is specific to `mpfr_t` arguments and should not be used with other types.

With conversion specification not involving ‘`P`’ and ‘`R`’ types, `mpfr_printf` behaves exactly as `gmp_vasprintf` (thus, if GMP uses its `vsnprintf` replacement, the behavior may differ from the C library or from other GMP formatted output functions; for instance, in such a case, up to GMP 6.3.0, the conversion specifiers ‘`a`’/‘`A`’ will not work).

Thus the ‘`conv`’ specifier ‘`F`’ is not supported (due to the use of ‘`F`’ as the ‘`type`’ specifier for `mpf_t`), except for the ‘`type`’ specifier ‘`R`’ (i.e., for `mpfr_t` arguments).

The ‘`P`’ type specifies that a following ‘`d`’, ‘`i`’, ‘`o`’, ‘`u`’, ‘`x`’, or ‘`X`’ conversion specifier applies to a `mpfr_prec_t` argument. It is needed because the `mpfr_prec_t` type does not necessarily correspond to an `int` or any fixed standard type. The ‘`precision`’ value specifies the minimum number of digits to appear. The default precision is 1. For example:

    mpfr_t x;
    mpfr_prec_t p;
    mpfr_init (x);
    ...
    p = mpfr_get_prec (x);
    mpfr_printf ("variable x with %Pd bits", p);

The ‘`R`’ type specifies that a following ‘`a`’, ‘`A`’, ‘`b`’, ‘`e`’, ‘`E`’, ‘`f`’, ‘`F`’, ‘`g`’, ‘`G`’, or ‘`n`’ conversion specifier applies to a `mpfr_t` argument. The ‘`R`’ type can be followed by a ‘`rounding`’ specifier denoted by one of the following characters:

> ‘`U`’ | round toward positive infinity
> ‘`D`’ | round toward negative infinity
> ‘`Y`’ | round away from zero
> ‘`Z`’ | round toward zero
> ‘`N`’ | round to nearest (with ties to even)
> ‘`*`’ | rounding mode indicated by the `mpfr_rnd_t` argument just before the corresponding `mpfr_t` variable.

The default rounding mode is rounding to nearest. The following three examples are equivalent:

    mpfr_t x;
    mpfr_init (x);
    ...
    mpfr_printf ("%.128Rf", x);
    mpfr_printf ("%.128RNf", x);
    mpfr_printf ("%.128R*f", MPFR_RNDN, x);

Note that the rounding away from zero mode is specified with ‘`Y`’ because ISO C reserves the ‘`A`’ specifier for hexadecimal output (see below).

The output ‘`conv`’ specifiers allowed with `mpfr_t` parameter are:

> ‘`a`’ ‘`A`’ | hex float, C99 style
> ‘`b`’ | binary output
> ‘`e`’ ‘`E`’ | scientific-format float
> ‘`f`’ ‘`F`’ | fixed-point float
> ‘`g`’ ‘`G`’ | fixed-point or scientific float

The conversion specifier ‘`b`’, which displays the argument in binary, is specific to `mpfr_t` arguments and should not be used with other types. Other conversion specifiers have the same meaning as for a `double` argument.

In case of non-decimal output, only the significand is written in the specified base, the exponent is always displayed in decimal.

Non-real values are always displayed as ‘`nan`’ / ‘`inf`’ for the ‘`a`’, ‘`b`’, ‘`e`’, ‘`f`’, and ‘`g`’ specifiers, and ‘`NAN`’ / ‘`INF`’ for ‘`A`’, ‘`E`’, ‘`F`’, and ‘`G`’ specifiers, possibly preceded by a sign or a space (the minus sign when the value has a negative sign, the plus sign when the value has a positive sign and the ‘`+`’ flag is used, a space when the value has a positive sign and the space flag is used).

The `mpfr_t` number is rounded to the given precision in the direction specified by the rounding mode (see below if the precision is missing). Similarly to the native C types, the precision is the number of digits output after the decimal-point character, except for the ‘`g`’ and ‘`G`’ conversion specifiers, where it is the number of significant digits (but trailing zeros of the fractional part are not output by default), or 1 if the precision is zero. If the precision is zero with rounding to nearest mode and one of the following conversion specifiers: ‘`a`’, ‘`A`’, ‘`b`’, ‘`e`’, ‘`E`’, tie case is rounded to even when it lies between two consecutive values at the wanted precision which have the same exponent, otherwise, it is rounded away from zero. For instance, 85 is displayed as ‘`8e+1`’ and 95 is displayed as ‘`1e+2`’ with the format specification `"%.0RNe"`. This also applies when the ‘`g`’ (resp. ‘`G`’) conversion specifier uses the ‘`e`’ (resp. ‘`E`’) style. If the precision is set to a value greater than the maximum value for an `int`, it will be silently reduced down to `INT_MAX`.

If the precision is missing, it is chosen as follows, depending on the conversion specifier.

- With ‘`a`’, ‘`A`’, and ‘`b`’, it is chosen to have an exact representation with no trailing zeros.
- With ‘`e`’ and ‘`E`’, it is ceil(p times log(2)/log(10)), where p is the precision of the input variable, matching the choice done for `mpfr_get_str`; thus, if rounding to nearest is used, outputting the value with a missing precision and reading it back will yield the original value.
- With ‘`f`’, ‘`F`’, ‘`g`’, and ‘`G`’, it is 6.

For a given number with ‘`a`’/‘`A`’, 4 exponent values allow the first hexadecimal digit to be non-zero as required, and the choice is unspecified in ISO C99 and later. In MPFR, the choice currently depends on the value of the precision field (zero or non-zero) and on the input value. This may change in the future in order to have a more consistent behavior. Details and discussion: https://sympa.inria.fr/sympa/arc/mpfr/2021-05/msg00002.html

#### 5.9.3 Functions ¶

For all the following functions, if the number of characters that ought to be written exceeds the maximum limit `INT_MAX` for an `int`, nothing is written in the stream (resp. to `stdout`, to buf, to str), the function returns −1, sets the erange flag, and `errno` is set to `EOVERFLOW` if the `EOVERFLOW` macro is defined (such as on POSIX systems). Note, however, that `errno` might be changed to another value by some internal library call if another error occurs there (currently, this would come from the unallocation function).

Function: `int` mpfr_fprintf `(FILE *stream, const char *template, …)` ¶
Function: `int` mpfr_vfprintf `(FILE *stream, const char *template, va_list ap)` ¶

  Print to the stream stream the optional arguments under the control of the template string template. Return the number of characters written or a negative value if an error occurred.

Function: `int` mpfr_printf `(const char *template, …)` ¶
Function: `int` mpfr_vprintf `(const char *template, va_list ap)` ¶

  Print to `stdout` the optional arguments under the control of the template string template. Return the number of characters written or a negative value if an error occurred.

Function: `int` mpfr_sprintf `(char *buf, const char *template, …)` ¶
Function: `int` mpfr_vsprintf `(char *buf, const char *template, va_list ap)` ¶

  Form a null-terminated array corresponding to the optional arguments under the control of the template string template, and print it in buf. No overlap is permitted between buf and the other arguments. Return the number of characters written in the array buf not counting the terminating null character or a negative value if an error occurred.

Function: `int` mpfr_snprintf `(char *buf, size_t n, const char *template, …)` ¶
Function: `int` mpfr_vsnprintf `(char *buf, size_t n, const char *template, va_list ap)` ¶

  Form a null-terminated array corresponding to the optional arguments under the control of the template string template, and print it in buf. If n is zero, nothing is written and buf may be a null pointer, otherwise, the first n − 1 characters are written in buf and the n-th one is a null character. Return the number of characters that would have been written had n been sufficiently large, not counting the terminating null character, or a negative value if an error occurred.

Function: `int` mpfr_asprintf `(char **str, const char *template, …)` ¶
Function: `int` mpfr_vasprintf `(char **str, const char *template, va_list ap)` ¶

  Write their output as a null-terminated array in a block of memory allocated using the allocation function (see Memory Handling). A pointer to the block is stored in str. The block of memory must be freed using `mpfr_free_str`, but you must first make sure that it does not contain non-terminating null characters or that the unallocation function does not use its size argument. The return value is the number of characters written in the array, excluding the null-terminator, or a negative value if an error occurred, in which case the contents of str are undefined. Note that this return value may be used to know how many bytes may need to be set to a non-zero value (in case ‘`%c`’ was used with the value 0) before the call to `mpfr_free_str`.