10.1 Format Strings

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 mpz_t, mpq_t and mpf_t respectively, ‘M’ for mp_limb_t, and ‘N’ for an 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 handed to 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.

0	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 int, the same as the standard printf.

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.

h	short
hh	char
j	intmax_t or uintmax_t
l	long or wchar_t
ll	long long
L	long double
q	quad_t or u_quad_t
t	ptrdiff_t
z	size_t

The GMP types are

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

The conversions accepted are as follows. ‘a’ and ‘A’ are always supported for mpf_t but depend on the C library for standard C float types. ‘m’ and ‘p’ depend on the C library.

a A	hex floats, C99 style
c	character
d	decimal integer
e E	scientific format float
f	fixed point float
i	same as d
g G	fixed or scientific float
m	strerror string, GLIBC style
n	store characters written so far
o	octal integer
p	pointer
s	string
u	unsigned integer
x X	hex integer

‘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 size of mp_limb_t. Unsigned conversions will be usual, but a signed conversion can be used and will interpret the value as a twos complement negative.

‘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 register_printf_function. 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 mpf_get_str does. 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 different.

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 chars, multibyte characters are not recognised. Perhaps this will change in the future.