### 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 `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). `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`’ 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_printf`.

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`’ field 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 %Pu 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 plus infinity
> ‘`D`’ | round toward minus 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 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. Special values are always displayed as `nan`, `-inf`, and `inf` for ‘`a`’, ‘`b`’, ‘`e`’, ‘`f`’, and ‘`g`’ specifiers and `NAN`, `-INF`, and `INF` for ‘`A`’, ‘`E`’, ‘`F`’, and ‘`G`’ specifiers.

If the ‘`precision`’ field is not empty, the `mpfr_t` number is rounded to the given precision in the direction specified by the rounding mode. If the precision is zero with rounding to nearest mode and one of the following ‘`conv`’ 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`’ field is empty (as in `%Re` or `%.RE`) with ‘`conv`’ specifier ‘`e`’ and ‘`E`’, the number is displayed with enough digits so that it can be read back exactly, assuming that the input and output variables have the same precision and that the input and output rounding modes are both rounding to nearest (as for `mpfr_get_str`). The default precision for an empty ‘`precision`’ field with ‘`conv`’ specifiers ‘`f`’, ‘`F`’, ‘`g`’, and ‘`G`’ is 6.

#### 5.9.3 Functions

For all the following functions, if the number of characters which ought to be written appears to exceed the maximum limit 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 (in POSIX system only) `errno` is set to `EOVERFLOW`.

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 string 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 string 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 n−1 first characters are written in buf and the n-th is a null character. Return the number of characters that would have been written had n be 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 string in a block of memory allocated using the current allocation function. A pointer to the block is stored in str. The block of memory must be freed using `mpfr_free_str`. The return value is the number of characters written in the string, excluding the null-terminator, or a negative value if an error occurred.