## 11 Formatted Input ¶

### 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 Format 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.

### 11.2 Formatted Input Functions ¶

Each of the following functions is similar to the corresponding C library function. The plain `scanf` forms take a variable argument list. The `vscanf` 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.

No overlap is permitted between the fmt string and any of the results produced.

Function: `int` gmp_scanf `(const char *fmt, …)` ¶
Function: `int` gmp_vscanf `(const char *fmt, va_list ap)` ¶

  Read from the standard input `stdin`.

Function: `int` gmp_fscanf `(FILE *fp, const char *fmt, …)` ¶
Function: `int` gmp_vfscanf `(FILE *fp, const char *fmt, va_list ap)` ¶

  Read from the stream fp.

Function: `int` gmp_sscanf `(const char *s, const char *fmt, …)` ¶
Function: `int` gmp_vsscanf `(const char *s, const char *fmt, va_list ap)` ¶

  Read from a null-terminated string s.

The return value from each of these functions is the same as the standard C99 `scanf`, namely the number of fields successfully parsed and stored. ‘`%n`’ fields and fields read but suppressed by ‘`*`’ don’t count towards the return value.

If end of input (or a file error) is reached before a character for a field or a literal, and if no previous non-suppressed fields have matched, then the return value is `EOF` instead of 0. A whitespace character in the format string is only an optional match and doesn’t induce an `EOF` in this fashion. Leading whitespace read and discarded for a field don’t count as characters for that field.

For the GMP types, input parsing follows C99 rules, namely one character of lookahead is used and characters are read while they continue to meet the format requirements. If this doesn’t provide a complete number then the function terminates, with that field not stored nor counted towards the return value. For instance with `mpf_t` an input ‘`1.23e-XYZ`’ would be read up to the ‘`X`’ and that character pushed back since it’s not a digit. The string ‘`1.23e-`’ would then be considered invalid since an ‘`e`’ must be followed by at least one digit.

For the standard C types, in the current implementation GMP calls the C library `scanf` functions, which might have looser rules about what constitutes a valid input.

Note that `gmp_sscanf` is the same as `gmp_fscanf` and only does one character of lookahead when parsing. Although clearly it could look at its entire input, it is deliberately made identical to `gmp_fscanf`, the same way C99 `sscanf` is the same as `fscanf`.

### 11.3 C++ Formatted Input ¶

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

Function: `istream&` operator>> `(istream& stream, mpz_t rop)` ¶

  Read rop from stream, using its `ios` formatting settings.

Function: `istream&` operator>> `(istream& stream, mpq_t rop)` ¶

  An integer like ‘`123`’ will be read, or a fraction like ‘`5/9`’. No whitespace is allowed around the ‘`/`’. If the fraction is not in canonical form then `mpq_canonicalize` must be called (see Rational Number Functions) before operating on it.

  As per integer input, an ‘`0`’ or ‘`0x`’ base indicator is read when none of `ios::dec`, `ios::oct` or `ios::hex` are set. This is done separately for numerator and denominator, so that for instance ‘`0x10/11`’ is 16/11 and ‘`0x10/0x11`’ is 16/17.

Function: `istream&` operator>> `(istream& stream, mpf_t rop)` ¶

  Read rop from stream, using its `ios` formatting settings.

  Hex or octal floats are not supported, but might be in the future, or perhaps it’s best to accept only what the standard float `operator>>` does.

Note that digit grouping specified by the `istream` locale is currently not accepted. Perhaps this will change in the future.

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

    mpz_t  z;
    ...
    cin >> z;

But note that `istream` input (and `ostream` output, see C++ Formatted Output) 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.