Next: Integer Related Functions, Previous: Input and Output Functions, Up: MPFR Interface
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.
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’:
‘h’ short
‘hh’ char
‘j’ intmax_t
oruintmax_t
‘l’ long
orwchar_t
‘ll’ long long
‘L’ long double
‘t’ ptrdiff_t
‘z’ size_t
‘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
‘R’ mpfr_t
input, float conversions‘P’ mpfr_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:
‘U’ round toward plus infinity ‘D’ round toward minus infinity ‘Z’ round toward zero ‘N’ round to nearest ‘*’ rounding mode (as a mpfr_rnd_t
) indicated by the argument just before the correspondingmpfr_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’ ‘A’ hex float, C99 style ‘b’ binary output ‘e’ ‘E’ scientific format float ‘f’ fixed point float ‘g’ ‘G’ fixed 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.
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 toEOVERFLOW
.
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 instdout
, the function returns −1, sets the erange flag, and (in POSIX system only)errno
is set toEOVERFLOW
.
Form a null-terminated string in
buf
. No overlap is permitted betweenbuf
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 inbuf
, the function returns −1, sets the erange flag, and (in POSIX system only)errno
is set toEOVERFLOW
.
Form a null-terminated string in
buf
. Ifn
is zero, nothing is written andbuf
may be a null pointer, otherwise, then-1
first characters are written inbuf
and then
-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 anint
, nothing is written inbuf
, the function returns −1, sets the erange flag, and (in POSIX system only)errno
is set toEOVERFLOW
.
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 anint
,str
is a null pointer, the function returns −1, sets the erange flag, and (in POSIX system only)errno
is set toEOVERFLOW
.