Constant gmp_mpfr_sys::C::GMP::Formatted_Output[−][src]

pub const Formatted_Output: ();

This constant is a place-holder for documentation; do not use it in code.

Next: , Previous: , Up: Top   [Index]

10 Formatted Output

• Formatted Output Strings  
• Formatted Output Functions  
• C++ Formatted Output  

Next: , Previous: , Up: Formatted Output   [Index]

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.

0pad 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.

hshort
hhchar
jintmax_t or uintmax_t
llong or wchar_t
lllong long
Llong double
qquad_t or u_quad_t
tptrdiff_t
zsize_t

The GMP types are

Fmpf_t, float conversions
Qmpq_t, integer conversions
Mmp_limb_t, integer conversions
Nmp_limb_t array, integer conversions
Zmpz_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 Ahex floats, C99 style
ccharacter
ddecimal integer
e Escientific format float
ffixed point float
isame as d
g Gfixed or scientific float
mstrerror string, GLIBC style
nstore characters written so far
ooctal integer
ppointer
sstring
uunsigned integer
x Xhex 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.

Next: , Previous: , Up: Formatted Output   [Index]

10.2 Functions

Each of the following functions is similar to the corresponding C library function. The basic printf forms take a variable argument list. The vprintf forms take an argument pointer, see Variadic Functions in The GNU C Library Reference Manual, or ‘man 3 va_start’.

It should be emphasised that if a format string is invalid, or the arguments don’t match what the format specifies, then the behaviour of any of these functions will be unpredictable. GCC format string checking is not available, since it doesn’t recognise the GMP extensions.

The file based functions gmp_printf and gmp_fprintf will return -1 to indicate a write error. Output is not “atomic”, so partial output may be produced if a write error occurs. All the functions can return -1 if the C library printf variant in use returns -1, but this shouldn’t normally occur.

Function: int gmp_printf (const char *fmt, …)
Function: int gmp_vprintf (const char *fmt, va_list ap)

Print to the standard output stdout. Return the number of characters written, or -1 if an error occurred.

Function: int gmp_fprintf (FILE *fp, const char *fmt, …)
Function: int gmp_vfprintf (FILE *fp, const char *fmt, va_list ap)

Print to the stream fp. Return the number of characters written, or -1 if an error occurred.

Function: int gmp_sprintf (char *buf, const char *fmt, …)
Function: int gmp_vsprintf (char *buf, const char *fmt, va_list ap)

Form a null-terminated string in buf. Return the number of characters written, excluding the terminating null.

No overlap is permitted between the space at buf and the string fmt.

These functions are not recommended, since there’s no protection against exceeding the space available at buf.

Function: int gmp_snprintf (char *buf, size_t size, const char *fmt, …)
Function: int gmp_vsnprintf (char *buf, size_t size, const char *fmt, va_list ap)

Form a null-terminated string in buf. No more than size bytes will be written. To get the full output, size must be enough for the string and null-terminator.

The return value is the total number of characters which ought to have been produced, excluding the terminating null. If retval >= size then the actual output has been truncated to the first size-1 characters, and a null appended.

No overlap is permitted between the region {buf,size} and the fmt string.

Notice the return value is in ISO C99 snprintf style. This is so even if the C library vsnprintf is the older GLIBC 2.0.x style.

Function: int gmp_asprintf (char **pp, const char *fmt, …)
Function: int gmp_vasprintf (char **pp, const char *fmt, va_list ap)

Form a null-terminated string in a block of memory obtained from the current memory allocation function (see Custom Allocation). The block will be the size of the string and null-terminator. The address of the block in stored to *pp. The return value is the number of characters produced, excluding the null-terminator.

Unlike the C library asprintf, gmp_asprintf doesn’t return -1 if there’s no more memory available, it lets the current allocation function handle that.

Function: int gmp_obstack_printf (struct obstack *ob, const char *fmt, …)
Function: int gmp_obstack_vprintf (struct obstack *ob, const char *fmt, va_list ap)

Append to the current object in ob. The return value is the number of characters written. A null-terminator is not written.

fmt cannot be within the current object in ob, since that object might move as it grows.

These functions are available only when the C library provides the obstack feature, which probably means only on GNU systems, see Obstacks in The GNU C Library Reference Manual.

Previous: , Up: Formatted Output   [Index]

10.3 C++ Formatted Output

The following functions are provided in libgmpxx (see Headers and Libraries), which is built if C++ support is enabled (see Build Options). Prototypes are available from <gmp.h>.

Function: ostream& operator<< (ostream& stream, const mpz_t op)

Print op to stream, using its ios formatting settings. ios::width is reset to 0 after output, the same as the standard ostream operator<< routines do.

In hex or octal, op is printed as a signed number, the same as for decimal. This is unlike the standard operator<< routines on int etc, which instead give twos complement.

Function: ostream& operator<< (ostream& stream, const mpq_t op)

Print op to stream, using its ios formatting settings. ios::width is reset to 0 after output, the same as the standard ostream operator<< routines do.

Output will be a fraction like ‘5/9’, or if the denominator is 1 then just a plain integer like ‘123’.

In hex or octal, op is printed as a signed value, the same as for decimal. If ios::showbase is set then a base indicator is shown on both the numerator and denominator (if the denominator is required).

Function: ostream& operator<< (ostream& stream, const mpf_t op)

Print op to stream, using its ios formatting settings. ios::width is reset to 0 after output, the same as the standard ostream operator<< routines do.

The decimal point follows the standard library float operator<<, which on recent systems means the std::locale imbued on stream.

Hex and octal are supported, unlike the standard operator<< on double. The mantissa will be in hex or octal, the exponent will be in decimal. For hex the exponent delimiter is an ‘@’. This is as per mpf_out_str.

ios::showbase is supported, and will put a base on the mantissa, for example hex ‘0x1.8’ or ‘0x0.8’, or octal ‘01.4’ or ‘00.4’. This last form is slightly strange, but at least differentiates itself from decimal.

These operators mean that GMP types can be printed in the usual C++ way, for example, 

mpz_t  z;
int    n;
...
cout << "iteration " << n << " value " << z << "\n";

But note that ostream output (and istream input, see C++ Formatted Input) is the only overloading available for the GMP types and that for instance using + with an mpz_t will have unpredictable results. For classes with overloading, see C++ Class Interface.

Previous: , Up: Formatted Output   [Index]