### 11.1 Formatted Input Strings

`gmp_scanf` and friends accept format strings similar to the standard C `scanf` (see Formatted Input in The GNU C Library Reference Manual). 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)
> `'` | grouped 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 int`, `double` 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
> `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 read 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 upper or lower case ‘`e`’ for the exponent in scientific format.

C99 style hex float format (`printf %a`, see Formatted Output Strings) is always accepted for `mpf_t`, but for the standard float types it will depend on the C library.

‘`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 (per `strtoul`, see Parsing of Integers in The GNU C Library Reference Manual). For GMP types there are no overflows, so ‘`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 in that case it would 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 in The GNU C Library Reference Manual). The C library will normally do the same for standard float input.

The format string is only interpreted as plain `char`s, multibyte characters are not recognised. Perhaps this will change in the future.