Macro with-input-from-string

Syntax:

Arguments and Values:

var—a variable name.

string—a form; evaluated to produce a string.

index—a place.

start, end—bounding index designators of string. The defaults for start and end are 0 and nil, respectively.

declaration—a declare expression; not evaluated.

forms—an implicit progn.

result—the values returned by the forms.

Description:

Creates an input string stream, provides an opportunity to perform operations on the stream (returning zero or more values), and then closes the string stream.

21.2.0 12String is evaluated first, and var is bound to a character input string stream that supplies characters from the subsequence of the resulting string bounded by start and end. The body is executed as an implicit progn.

21.2.0 13The input string stream is automatically closed on exit from with-input-from-string, no matter whether the exit is normal or abnormal. The input string stream to which the variable var is bound has dynamic extent; its extent ends when the form is exited.

21.2.0 14 21.2.0 15 \beginlist \itemitem{\kwd{index}}

The index is a pointer within the string to be advanced. If with-input-from-string is exited normally, then index will have stored into itas its value the index into the string indicating the first character not read which is (length string) if all characters were used. The place specified by index is not updated as reading progresses, but only at the end of the operation.

This is redundant with "bounded". 21.2.0 16 \itemitem{\kwd{start}} \kwd{start} indicates the beginning of a substring of \param{string} to be used. If \kwd{start} is not supplied or \nil, the beginning position is 0. 21.2.0 17 \itemitem{\kwd{end}} \kwd{end} indicates the end of a substring of \param{string} to be used. If \kwd{end} is not supplied or \nil, the ending position is {\tt (length \param{string})}. \endlist

21.2.0 19start and index may both specify the same variable, which is a pointer within the string to be advanced, perhaps repeatedly by some containing loop.

The consequences are undefined if an attempt is made to assign the variable var. Sandra thinks this isn't needed. The compiler may choose to issue a warning if such an attempt is detected.

Examples:

 (with-input-from-string (s "XXX1 2 3 4xxx"
                             :index ind
                             :start 3 :end 10)
    (+ (read s) (read s) (read s))) → 6
 ind → 9
 (with-input-from-string (s "Animal Crackers" :index j :start 6)
   (read s)) → CRACKERS

Side Effects:

The value of the place named by index, if any, is modified.

Sandra thinks this is excessive. A \term{string stream} is created (upon entry) and closed (upon exit).

Affected By:

None.

Exceptional Situations:

None.

See Also:

make-string-input-stream, Section 3.6 (Traversal Rules and Side Effects)

Notes:

None.