Next: , Previous: Input and Output Functions, Up: MPFR Interface


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 C function 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), plus ‘R’ and ‘P’:

hshort
hhchar
jintmax_t or uintmax_t
llong or wchar_t
lllong long
Llong double
tptrdiff_t
zsize_t


Fmpf_t, float conversions
Qmpq_t, integer conversions
Mmp_limb_t, integer conversions
Nmp_limb_t array, integer conversions
Zmpz_t, integer conversions


Rmpfr_t input, float conversions
Pmpfr_prec_t input, integer conversions

The ‘type’ specifiers have the same restrictions as those mentioned in the GMP documentation: see Section “Formatted Output Strings” in GNU MP. More precisely, except for ‘R’ and ‘P’ (which are defined by MPFR), the ‘type’ specifiers 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’ specifier is specific to mpfr_t parameter and shall not be used with other types. mpfr_printf accepts the same conversion specifier character ‘conv’ as gmp_printf plus ‘b’.

The ‘P’ type outputs the precision of an mpfr_t variable. It is needed because the mpfr_prec_t type does not necessarily correspond to an unsigned int or any fixed standard type. 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 is used for a mpfr_t output and can be followed by a rounding specifier denoted by one of the following characters:

Uround toward plus infinity
Dround toward minus infinity
Zround toward zero
Nround to nearest
*rounding mode (as a mpfr_rnd_t) indicated by the argument just before the corresponding mpfr_t variable.

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 field is empty (as in ‘%.Rf’), the number is displayed with enough digits so that it can be read back exactly (assuming rounding to nearest, see mpfr_get_str). If no rounding is specified, the mpfr_t argument is rounded 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", GMP_RNDN, x);

mpfr_printf also adds a new conversion specifier ‘b’ which displays the mpfr_t parameter in binary, the behavior is undefined with other parameter type. The ‘conv’ specifiers allowed with mpfr_t parameter are:

a’ ‘Ahex float, C99 style
bbinary output
e’ ‘Escientific format float
ffixed point float
g’ ‘Gfixed or scientific float

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. In binary output, the precision is silently increased up to 2 if it equals 1.

5.9.3 Functions

— 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. 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, the function returns −1, sets the erange flag, and (in POSIX system only) errno is set to EOVERFLOW.

— 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. If the number of characters which ought to be written appears to exceed the maximum limit for an int, nothing is written in stdout, the function returns −1, sets the erange flag, and (in POSIX system only) errno is set to EOVERFLOW.

— 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 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. If the number of characters which ought to be written appears to exceed the maximum limit for an int, nothing is written in buf, the function returns −1, sets the erange flag, and (in POSIX system only) errno is set to EOVERFLOW.

— 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 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. If the number of characters produced by the optional arguments under the control of the template string template appears to exceed the maximum limit for an int, nothing is written in buf, the function returns −1, sets the erange flag, and (in POSIX system only) errno is set to EOVERFLOW.

— 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. If the number of characters produced by the optional arguments under the control of the template string template appears to exceed the maximum limit for an int, str is a null pointer, the function returns −1, sets the erange flag, and (in POSIX system only) errno is set to EOVERFLOW.