stream-read-sequence

stream-read-sequence Generic Function

Summary

Reads a number of items from a stream into a sequence.

Package

stream

Signature

stream-read-sequence stream sequence start end => position

Method signatures

stream-read-sequence (stream t) (sequence t) (start t) (end t)

stream-read-sequence (stream stream) (sequence t) (start t) (end t)

stream-read-sequence (stream buffered-stream) (sequence t) (start t) (end t)

Arguments

`stream`⇩	A stream.
`sequence`⇩	A sequence.
`start`⇩	An integer.
`end`⇩	An integer.

Values

position

An integer.

Description

The generic function stream-read-sequence reads from stream into sequence. Elements from start in sequence are replaced by elements from stream until end in sequence or the end-of-file in stream is reached. The index of the first element in sequence that is not replaced is returned.

The method specializing stream on t just signals an error.

The method specializing stream on stream repeatedly reads elements from stream and stores them into sequence (starting from start) until it reaches end or it reaches the end-of-file of stream. The elements are read using stream-read-char if stream-element-type returns a subtype of character and stream-read-byte otherwise.

The method specializing stream on buffered-stream is optimized to be efficient, and is proper reliant on the implementation of buffered-stream. See the documentation for buffered-stream for details.

Notes

In the method for stream, if sequence is not of the appropriate type to receive the elements that come from stream, an error is signaled when it tries to store the element. For example, if sequence is a simple-base-string and stream has element type character, it will read and store elements as long as stream-read-char returns elements of type base-char, and will signal an error only when stream-read-char returns a non-base-char element. Similarly if the element type of sequence is (signed-byte 8) and the element type of stream is (unsigned-byte 8), it will work as long stream-read-byte returns elements less than 128.

The method for stream is not very efficient, and it forces the element type to be what stream-element-type returns. If you need more flexibility then you should write your own method specialized on your stream type, which can be also be made more efficient if it can make assumptions about sequence or stream.

Prior to LispWorks 8.0, there were also methods specialized on fundamental-character-output-stream and fundamental-binary-output-stream, which used stream-read-char and stream-read-byte respectively without checking the element type. These have been removed in LispWorks 8.0.