(index ("generator" 0) ("make-iota-generator" 227) ("make-range-generator" 866) ("make-coroutine-generator" 1596) ("list->generator" 2771) ("vector->generator" 2771) ("reverse-vector->generator" 2771) ("string->generator" 2771) ("bytevector->generator" 2771) ("make-for-each-generator" 4590) ("make-unfold-generator" 5750) ("gcons*" 6860) ("gappend" 7201) ("gcombine" 7561) ("gfilter" 8245) ("gremove" 8245) ("gtake" 8495) ("gdrop" 8495) ("gtake-while" 9282) ("gdrop-while" 9282) ("gdelete" 9836) ("gdelete-neighbor-dups" 10313) ("gindex" 10848) ("gselect" 11486) ("generator->list" 12103) ("generator->reverse-list" 12542) ("generator->vector" 13012) ("generator->vector!" 13457) ("generator->string" 13761) ("generator-fold" 14256) ("generator-for-each" 15325) ("generator-find" 15859) ("generator-count" 16219) ("generator-any" 16415) ("generator-every" 16707) ("generator-unfold" 17087))
(def (sig (procedure "(generator arg ...)" (id generator))) (p "The simplest finite generator. Generates each of its arguments in turn. When no arguments are provided, it returns an empty generator that generates no values."))
(def (sig (procedure "(make-iota-generator count [start [step]])" (id make-iota-generator))) (p "Creates a finite generator of a sequence of " (tt "count") " numbers. The sequence begins with " (tt "start") " (which defaults to 0) and increases by " (tt "step") " (which defaults to 1).  If both " (tt "start") " and " (tt "step") " are exact, it generates exact numbers; otherwise it generates inexact numbers. The exactness of " (tt "count") " doesn't affect the exactness of the results.") (highlight scheme "(generator->list (make-iota-generator 3 8))\n ⇒ (8 9 10)\n\n(generator->list (make-iota-generator 3 8 2))\n ⇒ (8 10 12)"))
(def (sig (procedure "(make-range-generator start [end [step]])" (id make-range-generator))) (p "Creates a generator of a sequence of numbers. The sequence begins with " (tt "start") ", increases by " (tt "step") " (default 1), and continues while the number is less than " (tt "end") ", or forever if end is omitted. If both " (tt "start") " and " (tt "step") " are exact, it generates exact numbers; otherwise it generates inexact numbers. The exactness of " (tt "end") " doesn't affect the exactness of the results.") (highlight scheme "(generator->list (make-range-generator 3) 4)\n ⇒ (3 4 5 6)\n(generator->list (make-range-generator 3 8))\n ⇒ (3 4 5 6 7)\n(generator->list (make-range-generator 3 8 2))\n ⇒ (3 5 7)"))
(def (sig (procedure "(make-coroutine-generator proc)" (id make-coroutine-generator))) (p "Creates a generator from a coroutine.") (p "The " (tt "proc") " argument is a procedure that takes one argument, " (tt "yield") ". When called, " (tt "make-coroutine-generator") " immediately returns a generator " (tt "g") ". When " (tt "g") " is called, " (tt "proc") " runs until it calls " (tt "yield") ". Calling " (tt "yield") " causes the execution of " (tt "proc") " to be suspended, and " (tt "g") " returns the value passed to " (tt "yield") ".") (p "Whether this generator is finite or infinite depends on the behavior of " (tt "proc") ".  If " (tt "proc") " returns, it is the end of the sequence — " (tt "g") " returns an end-of-file object from then on. The return value of " (tt "proc") " is ignored.") (p "The following code creates a generator that produces a series 0, 1, and 2 (effectively the same as " (tt "(make-range-generator 0 3)") " and binds it to " (tt "g") ".") (highlight scheme "(define g\n  (make-coroutine-generator\n   (lambda (yield)\n     (let loop ((i 0))\n       (when (< i 3) (yield i) (loop (+ i 1)))))))\n\n(generator->list g) ⇒ (0 1 2)"))
(def (sig (procedure "(list->generator lis)" (id list->generator)) (procedure "(vector->generator vec [start [end]])" (id vector->generator)) (procedure "(reverse-vector->generator vec [start [end]])" (id reverse-vector->generator)) (procedure "(string->generator str [start [end]])" (id string->generator)) (procedure "(bytevector->generator bytevector [start [end]])" (id bytevector->generator))) (p "These procedures return generators that yield each element of the given argument. Mutating the underlying object will affect the results of the generator.") (highlight scheme "(generator->list (list->generator '(1 2 3 4 5)))\n ⇒ (1 2 3 4 5)\n(generator->list (vector->generator '#(1 2 3 4 5)))\n ⇒ (1 2 3 4 5)\n(generator->list (reverse-vector->generator '#(1 2 3 4 5)))\n ⇒ (5 4 3 2 1)\n(generator->list (string->generator \"abcde\"))\n ⇒ (#\\a #\\b #\\c #\\d #\\e)") (p "The generators returned by the constructors are exhausted once all elements are retrieved; the optional " (tt "start") "-th and " (tt "end") "-th arguments can limit the range the generator walks across.") (p "For " (tt "reverse-vector->generator") ", the first value is the element right before the " (tt "end") "-th element, and the last value is the " (tt "start") "-th element. For all the other constructors, the first value the generator yields is the " (tt "start") "-th element, and it ends right before the " (tt "end") "-th element.") (highlight scheme "(generator->list (vector->generator '#(a b c d e) 2))\n ⇒ (c d e)\n(generator->list (vector->generator '#(a b c d e) 2 4))\n ⇒ (c d)\n(generator->list (reverse-vector->generator '#(a b c d e) 2))\n ⇒ (e d c)\n(generator->list (reverse-vector->generator '#(a b c d e) 2 4))\n ⇒ (d c)\n(generator->list (reverse-vector->generator '#(a b c d e) 0 2))\n ⇒ (b a)"))
(def (sig (procedure "(make-for-each-generator for-each obj)" (id make-for-each-generator))) (p "A generator constructor that converts any collection " (tt "obj") " to a generator that returns its elements using a " (tt "for-each") " procedure appropriate for " (tt "obj") ". This must be a procedure that when called as " (tt "(for-each proc obj)") " calls " (tt "proc") " on each element of " (tt "obj") ". Examples of such procedures are " (tt "for-each") ", " (tt "string-for-each") ", and " (tt "vector-for-each") " from R7RS. The value returned by " (tt "for-each") " is ignored. The generator is finite if the collection is finite, which would typically be the case.") (p "The collections need not be conventional ones (lists, strings, etc.) as long as " (tt "for-each") " can invoke a procedure on everything that counts as a member. For example, the following procedure allows " (tt "for-each-generator") " to generate the digits of an integer from least to most significant:") (highlight scheme "(define (for-each-digit proc n)\n  (when (> n 0)\n    (let-values (((div rem) (truncate/ n 10)))\n      (proc rem)\n      (for-each-digit proc div))))"))
(def (sig (procedure "(make-unfold-generator stop? mapper successor seed)" (id make-unfold-generator))) (p "A generator constructor similar to SRFI 1's " (tt "unfold") ".") (p "The " (tt "stop?") " predicate takes a " (tt "seed") " value and determines whether to stop. The " (tt "mapper") " procedure calculates a value to be returned by the generator from a seed value. The " (tt "successor") " procedure calculates the next seed value from the current seed value.") (p "For each call of the resulting generator, " (tt "stop?") " is called with the current seed value. If it returns true, then the generator returns an end-of-file object. Otherwise, it applies " (tt "mapper") " to the current seed value to get the value to return, and uses " (tt "successor") " to update the seed value.") (p "This generator is finite unless " (tt "stop?") " never returns true.") (highlight scheme "(generator->list (make-unfold-generator\n                      (lambda (s) (> s 5))\n                      (lambda (s) (* s 2))\n                      (lambda (s) (+ s 1))\n                      0))\n ⇒ (0 2 4 6 8 10)"))
(def (sig (procedure "(gcons* item ... gen)" (id gcons*))) (p "Returns a generator that adds " (tt "items") " in front of " (tt "gen") ". Once the " (tt "items") " have been consumed, the generator is guaranteed to tail-call " (tt "gen") ".") (highlight scheme "(generator->list (gcons* 'a 'b (make-range-generator 0 2)))\n ⇒ (a b 0 1)"))
(def (sig (procedure "(gappend gen ...)" (id gappend))) (p "Returns a generator that yields the items from the first given generator, and once it is exhausted, from the second generator, and so on.") (highlight scheme "(generator->list (gappend (make-range-generator 0 3) (make-range-generator 0 2)))\n ⇒ (0 1 2 0 1)\n(generator->list (gappend))\n ⇒ ()"))
(def (sig (procedure "(gcombine proc seed gen gen2 ...)" (id gcombine))) (p "A generator for mapping with state. It yields a sequence of sub-folds over " (tt "proc") ".") (p "The " (tt "proc") " argument is a procedure that takes as many arguments as the input generators plus one. It is called as " (tt "(proc v1 v2 … seed)") ", where " (tt "v1") ", " (tt "v2") ", ... are the values yielded from the input generators, and " (tt "seed") " is the current seed value. It must return two values, the yielding value and the next seed. The result generator is exhausted when any of the " (tt "genn") " generators is exhausted, at which time all the others are in an undefined state."))
(def (sig (procedure "(gfilter pred gen)" (id gfilter)) (procedure "(gremove pred gen)" (id gremove))) (p "Return generators that yield the items from the source generator, except those on which " (tt "pred") " answers false or true respectively."))
(def (sig (procedure "(gtake gen k [padding])" (id gtake)) (procedure "(gdrop gen k)" (id gdrop))) (p "These are generator analogues of SRFI 1 " (tt "take") " and " (tt "drop") ". " (tt "gtake") " returns a generator that yields (at most) the first " (tt "k") " items of the source generator, while " (tt "gdrop") " returns a generator that skips the first " (tt "k") " items of the source generator.") (p "These won't complain if the source generator is exhausted before generating " (tt "k") " items. By default, the generator returned by " (tt "gtake") " terminates when the source generator does, but if you provide the padding argument, then the returned generator will yield exactly " (tt "k") " items, using the padding value as needed to provide sufficient additional values."))
(def (sig (procedure "(gtake-while pred gen)" (id gtake-while)) (procedure "(gdrop-while pred gen)" (id gdrop-while))) (p "The generator analogues of SRFI-1 " (tt "take-while") " and " (tt "drop-while") ". The generator returned from " (tt "gtake-while") " yields items from the source generator as long as " (tt "pred") " returns true for each. The generator returned from " (tt "gdrop-while") " first reads and discards values from the source generator while " (tt "pred") " returns true for them, then starts yielding items returned by the source."))
(def (sig (procedure "(gdelete item gen [=])" (id gdelete))) (p "Creates a generator that returns whatever " (tt "gen") " returns, except for any items that are the same as " (tt "item") " in the sense of " (tt "=,") " which defaults to " (tt "equal?") ". The " (tt "=") " predicate is passed exactly two arguments, of which the first was generated by gen before the second.") (highlight scheme "(generator->list (gdelete 3 (generator 1 2 3 4 5 3 6 7)))\n ⇒ (1 2 4 5 6 7)"))
(def (sig (procedure "(gdelete-neighbor-dups gen [=])" (id gdelete-neighbor-dups))) (p "Creates a generator that returns whatever " (tt "gen") " returns, except for any items that are equal to the preceding item in the sense of " (tt "=") ", which defaults to " (tt "equal?") ". The " (tt "=") " predicate is passed exactly two arguments, of which the first was generated by " (tt "gen") " before the second.") (highlight scheme "(generator->list (gdelete-neighbor-dups (list->generator '(a a b c a a a d c))))\n  ⇒ (a b c a d c)"))
(def (sig (procedure "(gindex value-gen index-gen)" (id gindex))) (p "Creates a generator that returns elements of " (tt "value-gen") " specified by the indices (non-negative exact integers) generated by " (tt "index-gen") ". It is an error if the indices are not strictly increasing, or if any index exceeds the number of elements generated by " (tt "value-gen") ". The result generator is exhausted when either generator is exhausted, at which time the other is in an undefined state.") (highlight scheme "(generator->list (gindex (list->generator '(a b c d e f))\n                         (list->generator '(0 2 4))))\n ⇒ (a c e)"))
(def (sig (procedure "(gselect value-gen truth-gen)" (id gselect))) (p "Creates a generator that returns elements of " (tt "value-gen") " that correspond to the values generated by " (tt "truth-gen") ". If the current value of " (tt "truth-gen") " is true, the current value of " (tt "value-gen") " is generated, but otherwise not. The result generator is exhausted when either generator is exhausted, at which time the other is in an undefined state.") (highlight scheme "(generator->list (gselect (list->generator '(a b c d e f))\n                          (list->generator '(#t #f #f #t #t #f))))\n ⇒ (a d e)"))
(def (sig (procedure "(generator->list generator [k])" (id generator->list))) (p "Reads items from generator and returns a newly allocated list of them. By default, it reads until the generator is exhausted.") (p "If an optional argument " (tt "k") " is given, it must be a non-negative integer, and the list ends when either " (tt "k") " items are consumed, or generator is exhausted; therefore generator can be infinite in this case."))
(def (sig (procedure "(generator->reverse-list generator [k])" (id generator->reverse-list))) (p "Reads items from generator and returns a newly allocated list of them in reverse order. By default, this reads until the generator is exhausted.") (p "If an optional argument " (tt "k") " is given, it must be a non-negative integer, and the list ends when either " (tt "k") " items are read, or generator is exhausted; therefore generator can be infinite in this case."))
(def (sig (procedure "(generator->vector generator [k])" (id generator->vector))) (p "Reads items from generator and returns a newly allocated vector of them. By default, it reads until the generator is exhausted.") (p "If an optional argument " (tt "k") " is given, it must be a non-negative integer, and the list ends when either " (tt "k") " items are consumed, or generator is exhausted; therefore generator can be infinite in this case."))
(def (sig (procedure "(generator->vector! vector at generator)" (id generator->vector!))) (p "Reads items from generator and puts them into vector starting at index " (tt "at") ", until vector is full or generator is exhausted. Generator can be infinite. The number of elements generated is returned."))
(def (sig (procedure "(generator->string generator [k])" (id generator->string))) (p "Reads items from generator and returns a newly allocated string of them. It is an error if the items are not characters. By default, it reads until the generator is exhausted.") (p "If an optional argument " (tt "k") " is given, it must be a non-negative integer, and the string ends when either " (tt "k") " items are consumed, or generator is exhausted; therefore generator can be infinite in this case."))
(def (sig (procedure "(generator-fold proc seed gen1 gen2 ...)" (id generator-fold))) (p "Works like SRFI 1 " (tt "fold") " on the values generated by the generator arguments.") (p "When one generator is given, for each value " (tt "v") " generated by " (tt "gen") ", " (tt "proc") " is called as " (tt "(proc v r)") ", where " (tt "r") " is the current accumulated result; the initial value of the accumulated result is " (tt "seed") ", and the return value from " (tt "proc") " becomes the next accumulated result. When " (tt "gen") " is exhausted, the accumulated result at that time is returned from " (tt "generator-fold") ".") (p "When more than one generator is given, " (tt "proc") " is invoked on the values returned by all the generator arguments followed by the current accumulated result. The procedure terminates when any of the " (tt "genn") " generators is exhausted, at which time all the others are in an undefined state.") (highlight scheme "(with-input-from-string \"a b c d e\"\n  (lambda () (generator-fold cons 'z read)))\n ⇒ (e d c b a . z)"))
(def (sig (procedure "(generator-for-each proc gen gen2 …)" (id generator-for-each))) (p "A generator analogue of " (tt "for-each") " that consumes generated values using side effects. Repeatedly applies proc on the values yielded by " (tt "gen") ", " (tt "gen2") " ... until any one of the generators is exhausted. The values returned from proc are discarded. The procedure terminates when any of the " (tt "genn") " generators is exhausted, at which time all the others are in an undefined state. Returns an unspecified value."))
(def (sig (procedure "(generator-find pred gen)" (id generator-find))) (p "Returns the first item from the generator " (tt "gen") " that satisfies the predicate " (tt "pred") ", or " (tt "#f") " if no such item is found before gen is exhausted. If " (tt "gen") " is infinite, " (tt "generator-find") " will not return if it cannot find an appropriate item."))
(def (sig (procedure "(generator-count pred gen)" (id generator-count))) (p "Returns the number of items available from the generator " (tt "gen") " that satisfy the predicate " (tt "pred") "."))
(def (sig (procedure "(generator-any pred gen)" (id generator-any))) (p "Applies " (tt "pred") " to each item from " (tt "gen") ". As soon as it yields a true value, the value is returned without consuming the rest of " (tt "gen") ". If " (tt "gen") " is exhausted, returns " (tt "#f") "."))
(def (sig (procedure "(generator-every pred gen)" (id generator-every))) (p "Applies " (tt "pred") " to each item from " (tt "gen") ". As soon as it yields a false value, the value is returned without consuming the rest of " (tt "gen") ". If " (tt "gen") " is exhausted, returns the last value returned by " (tt "pred") ", or " (tt "#t") " if " (tt "pred") " was never called."))
(def (sig (procedure "(generator-unfold gen unfold arg ...)" (id generator-unfold))) (p "Equivalent to " (tt "(unfold eof-object? (lambda (x) x) (lambda (x) (gen)) (gen) arg ...)") ". The values of " (tt "gen") " are unfolded into the collection that " (tt "unfold") " creates.") (p "The signature of the " (tt "unfold") " procedure is " (tt "(unfold stop? mapper successor seed args ...)") ". Note that the " (tt "vector-unfold") " and " (tt "vector-unfold-right") " of SRFI 43 and SRFI 133 do not have this signature and cannot be used with this procedure. To unfold into a vector, use SRFI 1's " (tt "unfold") " and then apply " (tt "list->vector") " to the result.") (highlight scheme ";; Iterates over string and unfolds into a list using SRFI 1 unfold\n(generator-unfold (make-for-each-generator string-for-each \"abc\") unfold)\n ⇒ (#\\a #\\b #\\c)"))
