gmp_printf and friends accept format strings similar to the standard C
printf (see Formatted Output in The GNU C
Library Reference Manual). A format specification is of the form
% [flags] [width] [.[precision]] [type] conv
GMP adds types ‘Z’, ‘Q’ and ‘F’ for
mpf_t respectively, ‘M’ for
mp_limb_t, and ‘N’ for
mp_limb_t array. ‘Z’, ‘Q’, ‘M’ and ‘N’ behave
like integers. ‘Q’ will print a ‘/’ and a denominator, if needed.
‘F’ behaves like a float. For example,
mpz_t z; gmp_printf ("%s is an mpz %Zd\n", "here", z); mpq_t q; gmp_printf ("a hex rational: %#40Qx\n", q); mpf_t f; int n; gmp_printf ("fixed point mpf %.*Ff with %d digits\n", n, f, n); mp_limb_t l; gmp_printf ("limb %Mu\n", l); const mp_limb_t *ptr; mp_size_t size; gmp_printf ("limb array %Nx\n", ptr, size);
For ‘N’ the limbs are expected least significant first, as per the
mpn functions (see Low-level Functions). A negative size can be
given to print the value as a negative.
All the standard C
printf types behave the same as the C library
printf, and can be freely intermixed with the GMP extensions. In the
current implementation the standard parts of the format string are simply
printf and only the GMP extensions handled directly.
The flags accepted are as follows. GLIBC style ‘'’ is only for the standard C types (not the GMP types), and only if the C library supports it.
pad with zeros (rather than spaces)
show the base with ‘0x’, ‘0X’ or ‘0’
always show a sign (space) show a space or a ‘-’ sign
group digits, GLIBC style (not GMP types)
The optional width and precision can be given as a number within the format
string, or as a ‘*’ to take an extra parameter of type
same as the standard
The standard types accepted are as follows. ‘h’ and ‘l’ are portable, the rest will depend on the compiler (or include files) for the type and the C library for the output.
The GMP types are
mpf_t, float conversions
mpq_t, integer conversions
mp_limb_t, integer conversions
mp_limb_tarray, integer conversions
mpz_t, integer conversions
The conversions accepted are as follows. ‘a’ and ‘A’ are always
mpf_t but depend on the C library for standard C float
types. ‘m’ and ‘p’ depend on the C library.
hex floats, C99 style
scientific format float
fixed point float
fixed or scientific float
strerrorstring, GLIBC style
store characters written so far
‘o’, ‘x’ and ‘X’ are unsigned for the standard C types, but for types ‘Z’, ‘Q’ and ‘N’ they are signed. ‘u’ is not meaningful for ‘Z’, ‘Q’ and ‘N’.
‘M’ is a proxy for the C library ‘l’ or ‘L’, according to the
mp_limb_t. Unsigned conversions will be usual, but a signed
conversion can be used and will interpret the value as a twos complement
‘n’ can be used with any type, even the GMP types.
Other types or conversions that might be accepted by the C library
printf cannot be used through
gmp_printf, this includes for
instance extensions registered with GLIBC
Also currently there’s no support for POSIX ‘$’ style numbered arguments
(perhaps this will be added in the future).
The precision field has its usual meaning for integer ‘Z’ and float ‘F’ types, but is currently undefined for ‘Q’ and should not be used with that.
mpf_t conversions only ever generate as many digits as can be
accurately represented by the operand, the same as
Zeros will be used if necessary to pad to the requested precision. This
happens even for an ‘f’ conversion of an
mpf_t which is an
integer, for instance 2^1024 in an
mpf_t of 128 bits
precision will only produce about 40 digits, then pad with zeros to the
decimal point. An empty precision field like ‘%.Fe’ or ‘%.Ff’ can
be used to specifically request just the significant digits. Without any dot
and thus no precision field, a precision value of 6 will be used. Note that
these rules mean that ‘%Ff’, ‘%.Ff’, and ‘%.0Ff’ will all be
The decimal point character (or string) is taken from the current locale
settings on systems which provide
localeconv (see Locales
and Internationalization in The GNU C Library Reference Manual). The C
library will normally do the same for standard float output.
The format string is only interpreted as plain
characters are not recognised. Perhaps this will change in the future.