Generator Utilitiesπ i
Primitives and utilities for working with generators.
This module provides general-purpose utilities to achieve standard "list-like" transformations with generators without losing the laziness and constant-memory guarantees that generators provide. Alternative bindings for many of those found in racket/generator are included here, so that importing both is generally not necessary.
This module additionally provides a generic interface gen:generator representing a generator, as well as a particular generator type gen implementing that interface. The former allows supporting generator semantics in custom types and the latter is a rich generator type usable as a drop-in replacement for built-in generators, which comes with some conveniences.
Caveat: These utilities are not suitable for use with coroutines, i.e. in cases where there is bidirectional communication with a generator. This is because the utilities wrap underlying generators with intermediary ones in some cases, and values sent to them are not conveyed to the underlying generators.
1Constructorsπ i
A type representing a generator. All generators returned by this module are of this type, and they function identically to built-in generators, except that this type also implements
gen:collection , enabling convenient construction using the generic construction operator
: .
Examples:
> (g2)
> (g2)
> (g2)
> (g2)
> (g2)
Constructors for
generators, analogous to
null ,
cons , and
list for lists.
generator-null serves as the null constructor as well as the identity value in composing generators, while
generator-cons constructs a new generator from an arbitrary value and an existing generator.
make-generator is a variadic constructor analogous to
list . If a
return value is provided to
generator-null , it is used as the return value of the generator once it is exhausted – that is, as the return value for any generator with this empty generator instance at its tail.
Note that these constructors are not lazy. In order to construct a generator from a sequence lazily, use generate instead.
These constructors could either be used directly or via the generic construction operator : – see gen for examples of this.
Examples:
Identical to
generator except that it produces a
gen rather than a built-in generator type. This module also re-provides the
yield procedure from
racket/generator, so importing that module is unnecessary in many common cases.
3Predicatesπ i
Predicates to assert whether a generator is "empty" or "done."
generator-empty? is a statement about the "contents" of the generator, whereas
generator-done? is a statement about the "state" of the generator. This distinction is made because Racket generators evaluate to two different kinds of values – first, the values that are
yielded from within the generator, and second, the return value of the generator which is not explicitly yielded. For the purposes of this interface, the yielded values are treated as the contents of the generator. Thus, if a generator yields no further values but nevertheless evaluates to a nontrivial return value, it is still considered empty. Explicitly,
generator-done? is equivalent to
(eq? 'done(generator-state g)). A generator that has exhausted all of its values but has not yet evaluated its return value is
empty but not
done.
generator-empty? returns both a boolean value indicating whether the generator is empty or not, as well as a fresh generator intended to supplant the original generator in the calling context. This is necessary because checking for emptiness requires invoking the generator to inspect the first element, which mutates the original generator. The returned generator is equivalent to the original generator prior to the mutation, modulo the aforementioned caveat about coroutines.
In general, favor using generator-done? .
Examples:
"Peek" at the first value in the generator without modifying it. Of course, inspecting the first element in a generator must necessarily modify it. To preserve the illusion that no mutation has taken place, a generator equivalent to the original one prior to mutation is returned along with the peeked-at value. This returned generator is expected to be used in place of the original one in the calling context as it will be functionally equivalent to the original one, modulo the
aforementioned caveat about coroutines. Additionally, peeking does not protect against invocation side-effects. If invoking
g results in a side-effect, that would still happen if you peek at it. But it won’t happen a second time since the replacement generator only includes the return value from the original invocation, and not the side effect.
Examples:
4Utilitiesπ i
Analogous to
map , returns a fresh generator whose values are the elements of
g transformed under
f.
Examples:
Analogous to
filter , returns a fresh generator whose values are the elements of
g for which the predicate
f is true.
Examples:
Analogous to
fold , returns a fresh generator whose values are the steps in the aggregation of the elements of
g under the folding function
f.
Examples:
Analogous to
append , returns a fresh generator whose values are the elements of
a followed by the elements of
b.
Examples:
Analogous to
cycle , returns an infinite generator whose values are the elements of
g, repeated when exhausted. If a
stop value is provided, the elements are drawn from
g until
stop is encountered. This utility uses memory proportional to the size of the repeated sequence.
Examples:
> (g)
> (g)
> (g)
> (g)
> (g)
Analogous to
repeat , returns an infinite generator whose values are
v repeated indefinitely.
Examples:
Analogous to
zip-with,
generator-zip-with returns a fresh generator whose values are the elements of the input generators combined using the function
f.
f must accept a number of arguments equal to the number of provided generators.
generator-zip simply combines the generator values using
list . The generation stops when one of the input generators runs out of values.
Examples:
Returns a fresh generator whose values are the elements of the input generators taken in turn, one at a time. The generation stops when one of the input generators runs out of values.
Examples:
> (g)
> (g)
> (g)
> (g)
> (g)
> (g)
Returns a fresh generator whose values are the elements of g "flattened" by one level.
Examples:
Returns a fresh generator whose values are the "flattened" elements of
g. This is equivalent to repeatedly applying
generator-join until the values are no longer sequences.
Examples:
Yield all values from a provided generator. This should only be used inside a generator.
Examples:
5Transformersπ i
Returns a generator that generates
seq. See
->generator for some considerations here.
To go in the "other direction" and transform a generator into a sequence, use in-producer .
Examples:
> (g)
> (g)
> (g)
> (g)
> (g)
> (g)
To go in the "other direction" and transform a sequence into a generator, use generate .
Examples:
6Interfaceπ i
A
generic interface for generators that encompasses built-in generators but also enables providing generator semantics in custom types.
Examples:
#:transparent
((api-reader-sourceself)))
(-generator-state(api-reader-sourcesource)))])
> (g)
To implement this interface for custom types, the following method needs to be implemented:
Describes the state of the generator. The implementation should mirror
generator-state.
Examples: