5.10 Streams protocols

5.10.1 Positionable stream protocol

This section describes the protocol for positionable streams.

A stream position can be thought of as a natural number that indicates how many elements into the stream the stream's current location is. However, it is not always the case that a single integer contains enough information to reposition a stream. Consider the case of an "uncompressing" file stream that requires additional state beyond simply the file position to be able to get the next input character from the compressed file.

The Streams module addresses this problem by introducing the class <stream-position>, which is subclassed by various kinds of stream implementations that need to maintain additional state. A stream can be repositioned as efficiently as possible when stream-position-setter is given a value previously returned by stream-position on that stream.

It is also legal to set the position of a stream to an integer position. However, for some types of streams, to do so might be slow, perhaps requiring the entire contents of the stream up to that point to be read.

<position-type>

Type

type-union(<stream-position>, <integer>)

: A type used to represent a position in a stream. In practice, positions within a stream are defined as instances of <integer>, but this type, together with the <stream-position> class, allows for cases where this might not be possible.

<stream-position>

Abstract class

: A direct subclass of <object>. It is used in rare cases to represent positions within streams that cannot be represented as instances of <integer>, such as a stream that supports compression.

stream-position

Open generic function

stream-position positionable-stream => position

: Returns the current position of positionable-stream for reading or writing.

stream-position-setter

Open generic function

stream-position-setter position positionable-stream => new-position

: Changes the stream's position to position, for reading or writing.
: The following are all possible values of position: an integer between 0 and positionable-stream.stream-size, a valid <stream-position>, #"start", or #"end".
: Note: You cannot use stream-position-setter to set the position past the current last element of the stream: use adjust-stream-position instead.

adjust-stream-position

Open generic function

adjust-stream-position positionable-stream delta #key from 
=> new-position

: Moves the position of positionable-stream to be offset delta elements from the position indicated by from. The new position is returned. The delta offset must be an instance of <integer>.
: The value of from can be one of the symbols #"current", #"start", and #"end". The default is #"current".
: Using adjust-stream-position to set the position of a stream to be beyond its current last element grows the underlying aggregate to a new size.

G.f. method

as integer-class stream-position => integer

: Coerces a <stream-position> to an integer. The integer-class argument is the class <integer>.

stream-size

Open generic function

stream-size positionable-stream => size

: Returns the number of elements in positionable-stream.
: For input streams, this is the number of elements that were available when the stream was created. It is unaffected by any read operations that might have been performed on the stream.
: For output and input-output streams, this is the number of elements that were available when the stream was created (just as with input streams), added to the number of elements written past the end of the stream (regardless of any repositioning operations).

stream-contents

Open generic function

stream-contents positionable-stream #key clear-contents? => sequence

: Returns a sequence that contains all of positionable-stream's elements from its start to its end, regardless of its current position. The type of the returned sequence is as for read. See page 44.
: The clear-contents? argument only applies to writeable sequence streams. If clear-contents? is #t (the default for streams to which it is applicable), this function sets the size of the stream to zero, and the position to the stream's start. Thus the next call to stream-contents will return only the elements written after the previous call to stream-contents. The clear-contents? argument is not defined for file streams, or any other external stream. It is also an error to apply it to input-only streams.
: Note: You must use read-to-end for input streams.

unread-element

Open generic function

unread-element positionable-stream element => element

: Returns element to positionable-stream so that the next call to
read-element returns element. It is an error if element was not the last element read from the stream. You may not call unread-element more than once without an intervening read operation (that is, you cannot unread more than one element at a time).