5.11 The STREAMS module

stream-contents

Open generic function

Summary

Returns a sequence containing all the elements of a positionable stream.

Signature

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

Arguments

positionable-stream

An instance of <positionable-stream>.

clear-contents?

An instance of <boolean>. Default value: #t.

Values

sequence: An instance of <sequence>.

Library

io

Module

streams

Description

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 is only applicable to writeable sequence streams, and is not defined for file-streams or any other external stream. It returns an error if applied to an input only stream. If clear-contents? is #t (the default for cases where the argument is defined), 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.

Note that the sequence returned never shares structure with any underlying sequence that might be used in the future by the stream. For instance, the string returned by calling stream-contents on an output <string-stream> will not be the same string as that being used to represent the string stream.

Example

The following forms bind stream to an output stream over an empty string and create the string "I see!", using the function stream-contents to access all of the stream's elements.

let stream = make(<byte-string-stream>, 
                  direction: #"output");
write-element(stream, 'I');
write-element(stream, ' ');
write(stream, "see");
write-element(stream, '!');
stream-contents(stream);