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.