2.21.4 The (streams primitive) library

The (streams primitive) library provides two mutually–recursive abstract data types: An object of the stream abstract data type is a promise that, when forced, is either stream-null or is an object of type stream-pair. An object of the stream-pair abstract data type contains a stream-car and a stream-cdr, which must be a stream. The essential feature of streams is the systematic suspensions of the recursive promises between the two data types.

alpha stream
  :: (promise stream-null)
  |  (promise (alpha stream-pair))

alpha stream-pair
  :: (promise alpha) x (promise (alpha stream))

The object stored in the stream-car of a stream-pair is a promise that is forced the first time the stream-car is accessed; its value is cached in case it is needed again. The object may have any type, and different stream elements may have different types. If the stream-car is never accessed, the object stored there is never evaluated. Likewise, the stream-cdr is a promise to return a stream, and is only forced on demand.

This library provides eight operators: constructors for stream-null and stream-pairs, type recognizers for streams and the two kinds of streams, accessors for both fields of a stream-pair, and a lambda that creates procedures that return streams.

Function: stream-null

Return a promise that, when forced, is a single object, distinguishable from all other objects, that represents the null stream. stream-null is immutable and unique.

Syntax: stream-cons object stream

A macro that accepts an object and a stream and creates a newly–allocated stream containing a promise that, when forced, is a stream-pair with the object in its stream-car and the stream in its stream-cdr.

stream-cons must be syntactic, not procedural, because neither object nor stream is evaluated when stream-cons is called. Since stream is not evaluated, when the stream-pair is created, it is not an error to call stream-cons with a stream argument that is not of type stream; however, doing so will cause an error later when the stream-cdr of the stream-pair is accessed.

Once created, a stream-pair is immutable; there is no stream-set-car! or stream-set-cdr! that modifies an existing stream-pair. There is no dotted–pair or improper stream as with lists.

Function: stream? object

Return #t if the object is a stream and #f otherwise. If object is a stream, stream? does not force its promise.

If (stream? obj) is #t, then one of (stream-null? obj) and (stream-pair? obj) will be #t and the other will be #f; if (stream? obj) is #f, both (stream-null? obj) and (stream-pair? obj) will be #f.

Function: stream-null? object

Return #t if the object is the distinguished null stream and #f otherwise. If object is a stream, stream-null? must force its promise in order to distinguish stream-null from stream-pair.

Function: stream-pair? object

Take an object and return #t if it is a stream-pair constructed by stream-cons and #f otherwise. If object is a stream, stream-pair? must force its promise in order to distinguish stream-null from stream-pair.

Function: stream-car stream

Return the object stored in the stream-car of stream. stream-car signals an error if the object passed to it is not a stream-pair. Calling stream-car causes the object stored there to be evaluated if it has not yet been; the object’s value is cached in case it is needed again.

Function: stream-cdr stream

Return the stream stored in the stream-cdr of stream. stream-cdr signals an error if the object passed to it is not a stream-pair. Calling stream-cdr does not force the promise containing the stream stored in the stream-cdr of the stream.

Syntax: stream-lambda args . body

Create a procedure that returns a promise to evaluate the body of the procedure. The last body expression to be evaluated must yield a stream.

As with normal lambda, args may be a single variable name, in which case all the formal arguments are collected into a single list, or a list of variable names, which may be null if there are no arguments, proper if there are an exact number of arguments, or dotted if a fixed number of arguments is to be followed by zero or more arguments collected into a list.

body must contain at least one expression, and may contain internal definitions preceding any expressions to be evaluated.