►The Racket Reference
►4 Datatypes
▼4.14 Sequences and Streams
4.14.1 Sequences
4.14.2 Streams
4.14.3 Generators
On this page:
stream?
stream-empty?
stream-first
stream-rest
stream-cons
stream
in-stream
empty-stream
stream->list
stream-length
stream-ref
stream-tail
stream-append
stream-map
stream-andmap
stream-ormap
stream-for-each
stream-fold
stream-count
stream-filter
stream-add-between
gen:  stream
prop:  stream
  top  ← prev  up  next → 
4.14.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 #f 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)

Produces a lazy stream for which stream-first forces the evaluation of first-expr to produce the first element of the stream, and stream-rest forces the evaluation of rest-expr to produce a stream for the rest of the returned stream.

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

syntax

(stream expr ...)

A shorthand for nested stream-conses ending with empty-stream.

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.

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-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.

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 in between two elements where f returns a true 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.

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 should be implemented:

Examples:

> (define-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)
       (rest (list-stream-v stream)))])
> (define l1 (list-stream '(1 2)))
> (stream? l1)

#t

> (stream-first l1)

1

value

prop:stream : struct-type-property?

A deprecated structure type property used to define custom extensions to the stream API. Use gen:stream instead. Accepts a vector of three procedures taking the same arguments as the methods in gen:stream.

  top  ← prev  up  next →