►The Racket Reference
►4 Datatypes
▼4.17 Sequences and Streams
4.17.1 Sequences
4.17.2 Streams
4.17.3 Generators
On this page:
stream?
stream-empty?
stream-first
stream-rest
stream-cons
stream-lazy
stream-force
stream
stream*
in-stream
empty-stream
stream->list
stream-length
stream-ref
stream-tail
stream-take
stream-append
stream-map
stream-andmap
stream-ormap
stream-for-each
stream-fold
stream-count
stream-filter
stream-add-between
for/  stream
for*/  stream
gen:  stream
prop:  stream
stream/  c
  top  contents    up   
4.17.2 Streams🔗ℹ

A stream is a kind of sequence that supports functional iteration via stream-first and stream-rest. The stream-cons form constructs a lazy stream, but plain lists can be used as streams, and functions such as in-range and in-naturals also create streams.

 (require racket/stream) package: base
The bindings documented in this section are provided by the racket/stream and racket libraries, but not racket/base.

procedure

(stream? v) → boolean?

  v : any/c
Returns #t if v can be used as a stream, #f otherwise.

procedure

(stream-empty? s) → boolean?

  s : stream?
Returns #t if s has no elements, #f otherwise.

procedure

(stream-first s) → any

  s : (and/c stream? (not/c stream-empty?))
Returns the value(s) of the first element in s.

procedure

(stream-rest s) → stream?

  s : (and/c stream? (not/c stream-empty?))
Returns a stream that is equivalent to s without its first element.

syntax

(stream-cons first-expr rest-expr)

(stream-cons #:eager first-expr rest-expr)
(stream-cons first-expr #:eager rest-expr)
(stream-cons #:eager first-expr #:eager rest-expr)
Produces a stream whose first element is determined by first-expr and whose rest is determined by rest-expr.

If first-expr is not preceded by #:eager, then first-expr is not evaluated immediately. Instead, stream-first on the result stream forces the evaluation of first-expr (once) to produce the first element of the stream. If evaluating first-expr raises an exception or tries to force itself, then an exn:fail:contract exception is raised, and future attempts to force evaluation will trigger another exception.

If rest-expr is not preceded by #:eager, then rest-expr is not evaluated immediately. Instead, stream-rest on the result stream produces another stream that is like the one produced by (stream-lazy rest-expr).

The first element of the stream as produced by first-expr can be multiple values. The rest-expr must produce a stream when it is evaluated, otherwise the exn:fail:contract? exception is raised.

Changed in version 8.0.0.12 of package base: Added #:eager options.
Changed in version 8.8.0.7: Changed to allow multiple values.

syntax

(stream-lazy stream-expr)

(stream-lazy #:who who-expr stream-expr)
Similar to (delay stream-expr), but the result is a stream instead of a promise, and stream-expr must produce a stream when it is eventually forced. The stream produced by stream-lazy has the same content as the stream produced by stream-expr; that is, operations like stream-first on the result stream will force stream-expr and retry on its result.

If evaluating stream-expr raises an exception or tries to force itself, then an exn:fail:contract exception is raised, and future attempts to force evaluation will trigger another exception.

If who-expr is provided, it is evaluated when constructing the delayed stream. If stream-expr later produces a value that is not a stream, and if who-expr produced a symbol value, then the symbol is used for the error message.

Added in version 8.0.0.12 of package base.

procedure

(stream-force s) → stream?

  s : stream?
Forces the evaluation of a delayed stream from stream-lazy, from the stream-rest of a stream-cons, etc., returning the forced stream. If s is not a delayed stream, then s is returned.

Normally, stream-force is not needed, because operations like stream-first, stream-rest, and stream-empty? force a delayed stream as needed. In rare cases, stream-force can be useful to reveal the underlying implementation of a stream (e.g., a stream that is an instance of a structure type that has the prop:stream property).

Added in version 8.0.0.12 of package base.

syntax

(stream elem-expr ...)

 
elem-expr = (values single-expr ...)
  | single-expr
A shorthand for nested stream-conses ending with empty-stream. As a match pattern, stream matches a stream with as many elements as elem-exprs, and each element must match the corresponding elem-expr pattern. The pattern elem-expr can be (values single-expr ...), which matches against multiple valued elements in the stream.

Changed in version 8.8.0.7 of package base: Changed to allow multiple values.

syntax

(stream* elem-expr ... tail-expr)

A shorthand for nested stream-conses, but the tail-expr must produce a stream when it is forced, and that stream is used as the rest of the stream instead of empty-stream. Similar to list* but for streams. As a match pattern, stream* is similar to a stream pattern, but the tail-expr pattern matches the “rest” of the stream after the last elem-expr.

Added in version 6.3 of package base.
Changed in version 8.0.0.12: Changed to delay rest-expr even if zero exprs are provided.
Changed in version 8.8.0.7: Changed to allow multiple values.

procedure

(in-stream s) → sequence?

  s : stream?
Returns a sequence that is equivalent to s.
An in-stream application can provide better performance for streams iteration when it appears directly in a for clause.
See for for information on the reachability of stream elements during an iteration.

Changed in version 6.7.0.4 of package base: Improved element-reachability guarantee for streams in for.

value

empty-stream : stream?

A stream with no elements.

procedure

(stream->list s) → list?

  s : stream?
Returns a list whose elements are the elements of s, each of which must be a single value. If s is infinite, this function does not terminate.

procedure

(stream-length s) → exact-nonnegative-integer?

  s : stream?
Returns the number of elements of s. If s is infinite, this function does not terminate.

In the case of lazy streams, this function forces evaluation only of the sub-streams, and not the stream’s elements.

procedure

(stream-ref s i) → any

  s : stream?
  i : exact-nonnegative-integer?
Returns the ith element of s (which may be multiple values).

procedure

(stream-tail s i) → stream?

  s : stream?
  i : exact-nonnegative-integer?
Returns a stream equivalent to s, except that the first i elements are omitted.

In case extracting elements from s involves a side effect, they will not be extracted until the first element is extracted from the resulting stream.

procedure

(stream-take s i) → stream?

  s : stream?
  i : exact-nonnegative-integer?
Returns a stream of the first i elements of s.

procedure

(stream-append s ...) → stream?

  s : stream?
Returns a stream that contains all elements of each stream in the order they appear in the original streams. The new stream is constructed lazily, while the last given stream is used in the tail of the result.

procedure

(stream-map f s) → stream?

  f : procedure?
  s : stream?
Returns a stream that contains f applied to each element of s. The new stream is constructed lazily.

procedure

(stream-andmap f s) → boolean?

  f : (-> any/c ... boolean?)
  s : stream?
Returns #t if f returns a true result on every element of s. If s is infinite and f never returns a false result, this function does not terminate.

procedure

(stream-ormap f s) → boolean?

  f : (-> any/c ... boolean?)
  s : stream?
Returns #t if f returns a true result on some element of s. If s is infinite and f never returns a true result, this function does not terminate.

procedure

(stream-for-each f s) → void?

  f : (-> any/c ... any)
  s : stream?
Applies f to each element of s. If s is infinite, this function does not terminate.

procedure

(stream-fold f i s) → any/c

  f : (-> any/c any/c ... any/c)
  i : any/c
  s : stream?
Folds f over each element of s with i as the initial accumulator. If s is infinite, this function does not terminate. The f function takes the accumulator as its first argument and the next stream element as its second.

procedure

(stream-count f s) → exact-nonnegative-integer?

  f : procedure?
  s : stream?
Returns the number of elements in s for which f returns a true result. If s is infinite, this function does not terminate.

procedure

(stream-filter f s) → stream?

  f : (-> any/c ... boolean?)
  s : stream?
Returns a stream whose elements are the elements of s for which f returns a true result. Although the new stream is constructed lazily, if s has an infinite number of elements where f returns a false result, then operations on this stream will not terminate during the infinite sub-stream.

procedure

(stream-add-between s e) → stream?

  s : stream?
  e : any/c
Returns a stream whose elements are the elements of s, but with e between each pair of elements in s. The new stream is constructed lazily.

syntax

(for/stream (for-clause ...) body-or-break ... body)

syntax

(for*/stream (for-clause ...) body-or-break ... body)

Iterates like for/list and for*/list, respectively, but the results are lazily collected into a stream instead of a list.

Unlike most for forms, these forms are evaluated lazily, so each body will not be evaluated until the resulting stream is forced. This allows for/stream and for*/stream to iterate over infinite sequences, unlike their finite counterparts.

Examples:
> (for/stream ([i '(1 2 3)]) (* i i))

#<stream>

> (stream->list (for/stream ([i '(1 2 3)]) (* i i)))

'(1 4 9)

> (stream-ref (for/stream ([i '(1 2 3)]) (displayln i) (* i i)) 1)

2

4

> (stream-ref (for/stream ([i (in-naturals)]) (* i i)) 25)

625

> (stream-ref (for/stream ([i (in-naturals)]) (values i (add1 i))) 10)

10

11

Added in version 6.3.0.9 of package base.
Changed in version 8.8.0.7: Changed to allow multiple values.

value

gen:stream : any/c

Associates three methods to a structure type to implement the generic interface (see Generic Interfaces) for streams.

To supply method implementations, the #:methods keyword should be used in a structure type definition. The following three methods must be implemented:

Examples:
> (struct list-stream (v)
    #:methods gen:stream
    [(define (stream-empty? stream)
       (empty? (list-stream-v stream)))
     (define (stream-first stream)
       (first (list-stream-v stream)))
     (define (stream-rest stream)
       (list-stream (rest (list-stream-v stream))))])
> (define l1 (list-stream '(1 2)))
> (stream? l1)

#t

> (stream-first l1)

1

Changed in version 8.7.0.5 of package base: Added a check so that omitting any of stream-empty?, stream-first, and stream-rest is now a syntax error.

value

prop:stream : struct-type-property?

A structure type property used to define custom extensions to the stream API. Using the prop:stream property is discouraged; use the gen:stream generic interface instead. Accepts a vector of three procedures taking the same arguments as the methods in gen:stream.

procedure

(stream/c c) → contract?

  c : contract?
Returns a contract that recognizes streams. All elements of the stream must match c.

If the c argument is a flat contract or a chaperone contract, then the result will be a chaperone contract. Otherwise, the result will be an impersonator contract.

When an stream/c contract is applied to a stream, the result is not eq? to the input. The result will be either a chaperone or impersonator of the input depending on the type of contract.

Contracts on streams are evaluated lazily by necessity (since streams may be infinite). Contract violations will not be raised until the value in violation is retrieved from the stream. As an exception to this rule, streams that are lists are checked immediately, as if c had been used with listof.

If a contract is applied to a stream, and that stream is subsequently used as the tail of another stream (as the second parameter to stream-cons), the new elements will not be checked with the contract, but the tail’s elements will still be enforced.

Added in version 6.1.1.8 of package base.

  top  contents    up