5.6 Reading from and writing to streams

5.6.1 Reading from streams

The following are the basic functions for reading from streams.

read-element

Open generic function

read-element input-stream #key on-end-of-stream => element-or-eof

: Returns the next element in input-stream. If the stream is not at its end, the stream is advanced in preparation for a subsequent read operation.
: The on-end-of-stream keyword allows you to specify a value to be returned if the stream is at its end. If this is not supplied, read-element signals an <end-of-stream-error> condition on reading the end of the stream.
: If no input is available and the stream is not at its end, read-element waits until input becomes available.
: See also unread-element, page 58.

read

Open generic function

read input-stream n #key on-end-of-stream => sequence-or-eof

: Returns a sequence of the next n elements from input-stream.
: The type of the sequence returned depends on the type of the stream's underlying aggregate. For instances of <sequence-stream>, the type of the result is given by type-for-copy of the underlying aggregate. For instances of <file-stream>, the result is a vector that can contain elements of the type returned by calling stream-element-type on the stream.
: The stream position is advanced so that the next call to any function that reads from or writes to input-stream acts on the stream position immediately following the last of the n elements read.
: If the stream is not at its end, read waits until input becomes available.
: If the end of the stream is reached before all n elements have been read, the behavior is as follows.
: If on-end-of-stream was supplied, it is returned as the value of read.
: If on-end-of-stream argument was not supplied, and at least one element was read from the stream, then an <incomplete-read-error> condition is signalled. When signalling this condition, read supplies two values: a sequence of the elements that were read successfully, and n.
: If on-end-of-stream was not supplied, and no elements were read from the stream, an <end-of-stream-error> condition is signalled.
: The second of these is in some sense the most general behavior, in that the first and third cases could, in principle, be duplicated by using the second case, handling the signalled <incomplete-read-error>, and returning appropriate results.

A number of other functions are available for reading from streams. See peek, page 81, read-into!, page 85, discard-input, page 66, and stream-input-available?, page 96.