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


Formatted Input Strings

gmp_scanf and friends accept format strings similar to the standard C scanf (see Formatted Input). A format specification is of the form 

% [flags] [width] [type] conv

GMP adds types Z, Q and F for mpz_t, mpq_t and mpf_t respectively. Z and Q behave like integers. Q will read a / and a denominator, if present. F behaves like a float.

GMP variables don't require an & when passed to gmp_scanf, since they're already "call-by-reference". For example, 

/* to read say "a(5) = 1234" */
int   n;
mpz_t z;
gmp_scanf ("a(%d) = %Zd\n", &n, z);

mpq_t q1, q2;
gmp_sscanf ("0377 + 0x10/0x11", "%Qi + %Qi", q1, q2);

/* to read say "topleft (1.55,-2.66)" */
mpf_t x, y;
char  buf[32];
gmp_scanf ("%31s (%Ff,%Ff)", buf, x, y);

All the standard C scanf types behave the same as in the C library scanf, and can be freely intermixed with the GMP extensions. In the current implementation the standard parts of the format string are simply handed to scanf and only the GMP extensions handled directly.

The flags accepted are as follows. a and ' will depend on support from the C library, and ' cannot be used with GMP types.

* read but don't store
a allocate a buffer (string conversions)
' group digits, GLIBC style (not GMP types)

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 input.

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
Z mpz_t, integer conversions

The conversions accepted are as follows. p and [ will depend on support from the C library, the rest are standard.

c character or characters
d decimal integer
e E f g G float
i integer with base indicator
n characters written so far
o octal integer
p pointer
s string of non-whitespace characters
u decimal integer
x X hex integer
[ string of characters in a set

e, E, f, g and G are identical, they all read either fixed point or scientific format, and either e or E for the exponent in scientific format.

x and X are identical, both accept both upper and lower case hexadecimal.

o, u, x and X all read positive or negative values. For the standard C types these are described as "unsigned" conversions, but that merely affects certain overflow handling, negatives are still allowed (see strtoul, Parsing of Integers). For GMP types there are no overflows, and d and u are identical.

Q type reads the numerator and (optional) denominator as given. If the value might not be in canonical form then mpq_canonicalize must be called before using it in any calculations (see Rational Number Functions).

Qi will read a base specification separately for the numerator and denominator. For example 0x10/11 would be 16/11, whereas 0x10/0x11 would be 16/17.

n can be used with any of the types above, even the GMP types. * to suppress assignment is allowed, though the field would then do nothing at all.

Other conversions or types that might be accepted by the C library scanf cannot be used through gmp_scanf.

Whitespace is read and discarded before a field, except for c and [ conversions.

For float conversions, the decimal point character (or string) expected 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 input.