5.11 The STREAMS module

read

Open generic function

Summary

Reads a number of elements from an input stream.

Signature

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

Arguments

input-stream: An instance of <stream>.
n: An instance of <integer>.
on-end-of-stream: An instance of <object>.

Values

sequence-or-eof: An instance of <sequence>, or an instance of <object> if the end of stream is reached.

Library

io

Module

streams

Description

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 subsequent reads start after the n elements.

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 a value for the on-end-of-stream argument was supplied, it is returned as the value of read.
If a value for the 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 signaled. When signaling this condition, read supplies two values: a sequence of the elements that were read successfully, and n.
If the on-end-of-stream argument was not supplied, and no elements were read from the stream, an <end-of-stream-error> condition is signalled.