manpagez: man pages & more
info mpfr
Home | html | info | man
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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:

hshort
hhchar
jintmax_t or uintmax_t
llong or wchar_t
lllong long
Llong double
tptrdiff_t
zsize_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):

Fmpf_t, float conversions
Qmpq_t, integer conversions
Mmp_limb_t, integer conversions
Nmp_limb_t array, integer conversions
Zmpz_t, integer conversions
Pmpfr_prec_t, integer conversions
Rmpfr_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 ‘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 unsigned 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:

Uround toward plus infinity
Dround toward minus infinity
Yround away from zero
Zround toward zero
Nround to nearest
*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’ ‘Ahex float, C99 style
bbinary output
e’ ‘Escientific format float
f’ ‘Ffixed point float
g’ ‘Gfixed 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.