Janet 1.40.1-1449ad8 Documentation
(Other Versions:
1.40.0
1.39.1
1.38.0
1.37.1
1.36.0
1.35.0
1.34.0
1.31.0
1.29.1
1.28.0
1.27.0
1.26.0
1.25.1
1.24.0
1.23.0
1.22.0
1.21.0
1.20.0
1.19.0
1.18.1
1.17.1
1.16.1
1.15.0
1.13.1
1.12.2
1.11.1
1.10.1
1.9.1
1.8.1
1.7.0
1.6.0
1.5.1
1.5.0
1.4.0
1.3.1
)
generators
Eager evaluation costs a lot of memory when you need to process lots of data in a chain of eagerly evaluated functions as shown below.
(->> big-data
(map inc)
(filter even?)
# ... more eagerly evaluated functions
)The above code can create huge intermediate results which will be discarded by garbage collector later. You can avoid creating huge intermediate results with lazily evaluated generator functions in this module. Unlike lazy sequences in haskell and clojure, fiber-based generators don't cache values and don't leak memory.
A generator is an iterable coroutine which yields individual values whenever it is resumed, potentially until its internal values are exhausted, at which point it's considered dead. A coroutine is just another name for a fiber. A fiber is an iterable type that can be consumed by any of janet's core functions that expect iterable data types. A generator function can consume other generators and fully realized iterable data types produced by janet's core functions. In other words, iterables can generally be used interchangeably regardless of whether they are evaluated eagerly or lazily.
This operation makes them very useful for:
- Asynchronous behaviour
- Memory-sensitive applications, where it's not necessary to keep an entire sequence in memory at once
- Infinite sequences
Note: Certain functions (specifically run and to-array) will create an infinite loop if their argument is
an infinite generator!
Reference
generators/concat generators/cycle generators/drop generators/drop-until generators/drop-while generators/filter generators/from-iterable generators/interleave generators/interpose generators/keep generators/map generators/mapcat generators/partition generators/partition-by generators/range generators/run generators/take generators/take-until generators/take-while generators/to-array
(concat & iterables) Returns a coroutine that yields elements of the first given iterable, and then elements of the second given iterable, and so on until elements of the last given iterable are yielded.
(cycle iterable) Returns a coroutine that yields `iterable` elements and repetitively loops back to the beginning when finished. If `iterable` is a fiber, cycle cannot loop back to the beginning. Don't pass a fiber to cycle.
(drop n iterable) Returns a coroutine that drops the first `n` elements from `iterable` and yields the rest of the elements.
(drop-until pred iterable) Return a coroutine that drops `iterable` elements until `(pred element)` becomes truthy.
(drop-while pred iterable) Returns a coroutine that drops `iterable` elements while `(pred element)` is truthy.
(filter pred iterable) Returns a coroutine that yields only `iterable` elements for which `(pred element)` is truthy.
(from-iterable iterable) Returns a coroutine that yields elements of `iterable`.
(interleave iterable & iterables) Returns a coroutine that yields the first elements of iterables, and then the second elements of iterables, and then the third elements of iterables, and so on until any of the given iterables doesn't have any more element.
(interpose sep iterable) Returns a coroutine that yields `iterable` elements. sep is yielded between each element.
(keep pred iterable & iterables) Returns a coroutine that yields truthy results among (pred first-element-of-iterable ;first-elements-of-iterables), (pred second-element-of-iterable ;second-elements-of-iterables), (pred third-element-of-iterable ;third-elements-of-iterables), and so on until any of the given iterables doesn't have any more element.
(map f iterable & iterables) Returns a coroutine that yields (f first-element-of-iterable ;first-elements-of-iterables), (f second-element-of-iterable ;second-elements-of-iterables), (f third-element-of-iterable ;third-elements-of-iterables), and so on until any of the given iterables doesn't have any more element.
(mapcat f iterable & iterables) Returns a coroutine that yields elements of (f first-element-of-iterable ;first-elements-of-iterables), elements of (f second-element-of-iterable ;second-elements-of-iterables), elements of (f third-element-of-iterable ;third-elements-of-iterables), and so on until any of the given iterables doesn't have any more element.
(partition n iterable) Returns a coroutine that partitions `iterable` into arrays of size `n` and yields the arrays.
(partition-by f iterable) Returns a coroutine that partitions `iterable` elements into arrays by a representative function `f` and yields the arrays. Partitions split when (f current-element) differs from (f previous-element).
(range from to &opt step) Returns a coroutine that yields a range. step is the optional step size. The default step size is 1.
(take n iterable) Returns a coroutine that yields the first `n` elements from `iterable`.
(take-until pred iterable) Returns a coroutine that yields `iterable` elements until `(pred element)` becomes truthy.
(take-while pred iterable) Returns a coroutine that yields `iterable` elements while `(pred element)` is truthy.
(to-array iterable) Collect `iterable` elements into a new array.