Node:Formatted Output Strings, Next:, Previous:Formatted Output, Up:Formatted Output


Format Strings

gmp_printf and friends accept format strings similar to the standard C printf (see Formatted Output). 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, and N for an mp_limb_t array. Z, Q 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);

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 same as L
L long long or 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
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, GLIBC 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.

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 it's 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 20 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.

The decimal point character (or string) is taken from the current locale settings on systems which provide localeconv (see Locales and Internationalization). The C library will normally do the same for standard float output.