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.