GNU Info

(gmp.info)Formatted Input Strings

---

Next: Formatted Input Functions Prev: Formatted Input Up: Formatted Input

---

Enter node , (file) or (file)node

Formatted Input Strings
=======================

   `gmp_scanf' and friends accept format strings similar to the
standard C `scanf' (Note: 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', Note: 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 (Note: 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' (*note Locales and Internationalization:
(libc)Locales.).  The C library will normally do the same for standard
float input.