4.3.3 Standard Formatted Input

(require 'scanf)

Function: scanf-read-list format

Function: scanf-read-list format port

Function: scanf-read-list format string

Macro: scanf format arg1 …

Macro: fscanf port format arg1 …

Macro: sscanf str format arg1 …

Each function reads characters, interpreting them according to the control string format argument.

scanf-read-list returns a list of the items specified as far as the input matches format. scanf, fscanf, and sscanf return the number of items successfully matched and stored. scanf, fscanf, and sscanf also set the location corresponding to arg1 … using the methods:

symbol

set!

car expression

set-car!

cdr expression

set-cdr!

vector-ref expression

vector-set!

substring expression

substring-move-left!

The argument to a substring expression in arg1 … must be a non-constant string. Characters will be stored starting at the position specified by the second argument to substring. The number of characters stored will be limited by either the position specified by the third argument to substring or the length of the matched string, whichever is less.

The control string, format, contains conversion specifications and other characters used to direct interpretation of input sequences. The control string contains:

• White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read (and discarded) up to the next non-white-space character.
• An ordinary character (not ‘%’) that must match the next character of the input stream.
• Conversion specifications, consisting of the character ‘%’, an optional assignment suppressing character ‘*’, an optional numerical maximum-field width, an optional ‘l’, ‘h’ or ‘L’ which is ignored, and a conversion code.

Unless the specification contains the ‘n’ conversion character (described below), a conversion specification directs the conversion of the next input field. The result of a conversion specification is returned in the position of the corresponding argument points, unless ‘*’ indicates assignment suppression. Assignment suppression provides a way to describe an input field to be skipped. An input field is defined as a string of characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted.

Note: This specification of format strings differs from the ANSI C and POSIX specifications. In SLIB, white space before an input field is not skipped unless white space appears before the conversion specification in the format string. In order to write format strings which work identically with ANSI C and SLIB, prepend whitespace to all conversion specifications except ‘[’ and ‘c’.

The conversion code indicates the interpretation of the input field; For a suppressed field, no value is returned. The following conversion codes are legal:

‘%’

A single % is expected in the input at this point; no value is returned.

‘d’, ‘D’

A decimal integer is expected.

‘u’, ‘U’

An unsigned decimal integer is expected.

‘o’, ‘O’

An octal integer is expected.

‘x’, ‘X’

A hexadecimal integer is expected.

‘i’

An integer is expected. Returns the value of the next input item, interpreted according to C conventions; a leading ‘0’ implies octal, a leading ‘0x’ implies hexadecimal; otherwise, decimal is assumed.

‘n’

Returns the total number of bytes (including white space) read by scanf. No input is consumed by %n.

‘f’, ‘F’, ‘e’, ‘E’, ‘g’, ‘G’

A floating-point number is expected. The input format for floating-point numbers is an optionally signed string of digits, possibly containing a radix character ‘.’, followed by an optional exponent field consisting of an ‘E’ or an ‘e’, followed by an optional ‘+’, ‘-’, or space, followed by an integer.

‘c’, ‘C’

Width characters are expected. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use ‘%1s’. If a field width is given, a string is returned; up to the indicated number of characters is read.

‘s’, ‘S’

A character string is expected The input field is terminated by a white-space character. scanf cannot read a null string.

‘[’

Indicates string data and the normal skip-over-leading-white-space is suppressed. The left bracket is followed by a set of characters, called the scanset, and a right bracket; the input field is the maximal sequence of input characters consisting entirely of characters in the scanset. ‘^’, when it appears as the first character in the scanset, serves as a complement operator and redefines the scanset as the set of all characters not contained in the remainder of the scanset string. Construction of the scanset follows certain conventions. A range of characters may be represented by the construct first-last, enabling ‘[0123456789]’ to be expressed ‘[0-9]’. Using this convention, first must be lexically less than or equal to last; otherwise, the dash stands for itself. The dash also stands for itself when it is the first or the last character in the scanset. To include the right square bracket as an element of the scanset, it must appear as the first character (possibly preceded by a ‘^’) of the scanset, in which case it will not be interpreted syntactically as the closing bracket. At least one character must match for this conversion to succeed.

The scanf functions terminate their conversions at end-of-file, at the end of the control string, or when an input character conflicts with the control string. In the latter case, the offending character is left unread in the input stream.