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

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

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.

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 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 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 string 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. The return value is the number of characters written in the string, excluding the null-terminator, or a negative value if an error occurred, in which case the contents of str are undefined.