8.10 Streams🔗ℹ

A stream is a stateless sequence that supports Stream.first and Stream.rest operations. Accessing Stream.first multiple times for the same stream will produce the same result, and calling Stream.rest multiple times for the same stream will produce the same new stream that omits the first element. Lists, pair lists, and sequenceable ranges are streams, as well as lazy streams constructed using Stream.cons.

A stream is indexable using […] to access a stream element by position via #%index.

A Stream.expect_of(ann, ...) annotation is the same as Stream, but elements drawn from the stream via Stream.first have the static information of the anns (where multiple anns correspond to multiple values for each element, such as the key and value from a map). The extracted elements are not checked or converted, however, and each ann is used only for its static information.

Static information associated by Stream or Stream.expect_of makes an expression acceptable as a sequence to for in static mode.

The Stream.first and Stream.rest properties require non-empty streams. The Stream.is_empty method reports whether stm is empty.

> Stream.first([1, 2, 3])

1

> Stream.rest([1, 2, 3])

[2, 3]

> Stream.is_empty([1, 2, 3])

#false

> Stream.first([])

Stream.first: value does not satisfy annotation

annotation: Stream && !satisfying(Stream.is_empty)

value: []

> Stream.rest([])

Stream.rest: value does not satisfy annotation

annotation: Stream && !satisfying(Stream.is_empty)

value: []

If first_expr ir rest_expr is prefixed with ~eager, then the expression is evaluated at the time the stream is constructed, instead of delaying until the result is demanded.

The Stream.cons binding form matches a non-empty stream, and it binds first_bind and rest_bind to the first and rest of the matched stream—but not demanding the first or rest if first_bind or rest_bind is literally _, respectively.