3.18 Iterations and Comprehensions: for, for/list, ...
Iterations and Comprehensions in The Racket Guide introduces iterations and comprehensions.
The for iteration forms are based on SRFI-42 [SRFI-42].
3.18.1 Iteration and Comprehension Forms
syntax
(for (for-clause ...) body-or-break ... body)
for-clause = [id seq-expr] | [(id ...) seq-expr] | #:when guard-expr | #:unless guard-expr | #:do [do-body ...] | break-clause | #:splice (splicing-id . form) break-clause = #:break guard-expr | #:final guard-expr body-or-break = body | break-clause
seq-expr : sequence?
In the simple case, each for-clause has one of its first two forms, where [id seq-expr] is a shorthand for [(id) seq-expr]. In this simple case, the seq-exprs are evaluated left-to-right, and each must produce a sequence value (see Sequences).
The for form iterates by drawing an element from each sequence; if any sequence is empty, then the iteration stops, and #<void> is the result of the for expression. Otherwise a location is created for each id to hold the values of each element; the sequence produced by a seq-expr must return as many values for each iteration as corresponding ids.
The ids are then bound in the body, which is evaluated, and whose results are ignored. Iteration continues with the next element in each sequence and with fresh locations for each id.
A for form with zero for-clauses is equivalent to a single for-clause that binds an unreferenced id to a sequence containing a single element. All of the ids must be distinct according to bound-identifier=?.
If any for-clause has the form #:when guard-expr, then only the preceding clauses (containing no #:when, #:unless, or #:do) determine iteration as above, and the body is effectively wrapped as
(when guard-expr (for (for-clause ...) body ...+))
using the remaining for-clauses. A for-clause of the form #:unless guard-expr corresponds to the same transformation with unless in place of when. A for-clause of the form #:do [do-body ...] similarly creates nesting and corresponds to
(let () do-body ... (for (for-clause ...) body ...+))
where the do-body forms may introduce definitions that are visible in the remaining for-clauses.
A #:break guard-expr clause is similar to a #:unless guard-expr clause, but when #:break avoids evaluation of the bodys, it also effectively ends all sequences within the for form. A #:final guard-expr clause is similar to #:break guard-expr, but instead of immediately ending sequences and skipping the bodys, it allows at most one more element from each later sequence and at most one more evaluation of the following bodys. Among the bodys, besides stopping the iteration and preventing later body evaluations, a #:break guard-expr or #:final guard-expr clause starts a new internal-definition context.
A #:splice (splicing-id . form) clause is replaced by the sequence of forms that are produced by expanding (splicing-id . form), where splicing-id is bound using define-splicing-for-clause-syntax. The binding context of that expansion includes previous binding from any clause preceding both the #:splice form and a #:when, #:unless, #:do, #:break, or #:final form. The result of a #:splice expansion can include more #:splice forms to further interleave clause binding and expansion. Support for #:splice clauses is intended less for direct use in source for forms than for building new forms that expand to for.
In the case of list and stream sequences, the for form itself does not keep each element reachable. If a list or stream produced by a seq-expr is otherwise unreachable, and if the for body can no longer reference an id for a list element, then the element is subject to garbage collection. The make-do-sequence sequence constructor supports additional sequences that behave like lists and streams in this way.
If a seq-expr is a quoted literal list, vector, exact integer, string, byte string, immutable hash, or expands to such a literal, then it may be treated as if a sequence transformer such as in-list was used, unless the seq-expr has a true value for the 'for:no-implicit-optimization syntax property; in most cases this improves performance.
> (for ([i '(1 2 3)] [j "abc"] #:when (odd? i) [k #(#t #f)]) (display (list i j k))) (1 a #t)(1 a #f)(3 c #t)(3 c #f)
> (for ([i '(1 2 3)] #:do [(define neg-i (* i -1))] [j (list neg-i 0 i)]) (display (list j))) (-1)(0)(1)(-2)(0)(2)(-3)(0)(3)
> (for ([(i j) #hash(("a" . 1) ("b" . 20))]) (display (list i j))) (a 1)(b 20)
> (for ([i '(1 2 3)] [j "abc"] #:break (not (odd? i)) [k #(#t #f)]) (display (list i j k))) (1 a #t)(1 a #f)
> (for ([i '(1 2 3)] [j "abc"] #:final (not (odd? i)) [k #(#t #f)]) (display (list i j k))) (1 a #t)(1 a #f)(2 b #t)
> (for ([i '(1 2 3)] [j "abc"] [k #(#t #f)]) #:break (not (or (odd? i) k)) (display (list i j k))) (1 a #t)
> (for () (display "here")) here
> (for ([i '()]) (error "doesn't get here"))
Changed in version 6.7.0.4 of package base: Added support for the optional second result.
Changed in version 7.8.0.11: Added support for implicit optimization.
Changed in version 8.4.0.2: Added #:do.
Changed in version 8.4.0.3: Added #:splice.
syntax
(for/list (for-clause ...) body-or-break ... body)
> (for/list ([i '(1 2 3)] [j "abc"] #:when (odd? i) [k #(#t #f)]) (list i j k)) '((1 #\a #t) (1 #\a #f) (3 #\c #t) (3 #\c #f))
> (for/list ([i '(1 2 3)] [j "abc"] #:break (not (odd? i)) [k #(#t #f)]) (list i j k)) '((1 #\a #t) (1 #\a #f))
> (for/list () 'any) '(any)
> (for/list ([i '()]) (error "doesn't get here")) '()
syntax
(for/vector maybe-length (for-clause ...) body-or-break ... body)
maybe-length =
| #:length length-expr | #:length length-expr #:fill fill-expr
length-expr : exact-nonnegative-integer?
If the optional #:length clause is specified, the result of length-expr determines the length of the result vector. In that case, the iteration can be performed more efficiently, and it terminates when the vector is full or the requested number of iterations have been performed, whichever comes first. If length-expr specifies a length longer than the number of iterations, then the remaining slots of the vector are initialized to the value of fill-expr, which defaults to 0 (i.e., the default argument of make-vector).
> (for/vector ([i '(1 2 3)]) (number->string i)) '#("1" "2" "3")
> (for/vector #:length 2 ([i '(1 2 3)]) (number->string i)) '#("1" "2")
> (for/vector #:length 4 ([i '(1 2 3)]) (number->string i)) '#("1" "2" "3" 0)
> (for/vector #:length 4 #:fill "?" ([i '(1 2 3)]) (number->string i)) '#("1" "2" "3" "?")
The for/vector form may allocate a vector and mutate it after each iteration of body, which means that capturing a continuation during body and applying it multiple times may mutate a shared vector.
syntax
(for/hash (for-clause ...) body-or-break ... body)
syntax
(for/hasheq (for-clause ...) body-or-break ... body)
syntax
(for/hasheqv (for-clause ...) body-or-break ... body)
syntax
(for/hashalw (for-clause ...) body-or-break ... body)
> (for/hash ([i '(1 2 3)]) (values i (number->string i))) '#hash((1 . "1") (2 . "2") (3 . "3"))
Changed in version 8.5.0.3 of package base: Added the for/hashalw form.
syntax
(for/and (for-clause ...) body-or-break ... body)
> (for/and ([i '(1 2 3 "x")]) (i . < . 3)) #f
> (for/and ([i '(1 2 3 4)]) i) 4
> (for/and ([i '(1 2 3 4)]) #:break (= i 3) i) 2
> (for/and ([i '()]) (error "doesn't get here")) #t
syntax
(for/or (for-clause ...) body-or-break ... body)
> (for/or ([i '(1 2 3 "x")]) (i . < . 3)) #t
> (for/or ([i '(1 2 3 4)]) i) 1
> (for/or ([i '()]) (error "doesn't get here")) #f
syntax
(for/sum (for-clause ...) body-or-break ... body)
> (for/sum ([i '(1 2 3 4)]) i) 10
syntax
(for/product (for-clause ...) body-or-break ... body)
> (for/product ([i '(1 2 3 4)]) i) 24
syntax
(for/lists (id ... maybe-result) (for-clause ...) body-or-break ... body)
maybe-result =
| #:result result-expr
If a result-expr is provided, it is used as with for/fold when iteration terminates; otherwise, the result is as many lists as supplied ids.
The scope of id bindings is the same as for accumulator identifiers in for/fold. Mutating a id affects the accumulated lists, and mutating it in a way that produces a non-list can cause a final reverse for each id to fail.
> (for/lists (l1 l2 l3) ([i '(1 2 3)] [j "abc"] #:when (odd? i) [k #(#t #f)]) (values i j k))
'(1 1 3 3)
'(#\a #\a #\c #\c)
'(#t #f #t #f)
> (for/lists (acc) ([x '(tvp tofu seitan tvp tofu)] #:unless (member x acc)) x) '(tvp tofu seitan)
> (for/lists (firsts seconds #:result (list firsts seconds)) ([pr '((1 . 2) (3 . 4) (5 . 6))]) (values (car pr) (cdr pr))) '((1 3 5) (2 4 6))
Changed in version 7.1.0.2 of package base: Added the #:result form.
syntax
(for/first (for-clause ...) body-or-break ... body)
> (for/first ([i '(1 2 3 "x")] #:when (even? i)) (number->string i)) "2"
> (for/first ([i '()]) (error "doesn't get here")) #f
syntax
(for/last (for-clause ...) body-or-break ... body)
> (for/last ([i '(1 2 3 4 5)] #:when (even? i)) (number->string i)) "4"
> (for/last ([i '()]) (error "doesn't get here")) #f
syntax
(for/fold ([accum-id init-expr] ... maybe-result) (for-clause ...) body-or-break ... body)
maybe-result =
| #:result result-expr
> (for/fold ([sum 0] [rev-roots null]) ([i '(1 2 3 4)]) (values (+ sum i) (cons (sqrt i) rev-roots)))
10
'(2 1.7320508075688772 1.4142135623730951 1)
> (for/fold ([acc '()] [seen (hash)] #:result (reverse acc)) ([x (in-list '(0 1 1 2 3 4 4 4))]) (cond [(hash-ref seen x #f) (values acc seen)] [else (values (cons x acc) (hash-set seen x #t))])) '(0 1 2 3 4)
The binding and evaluation order of accum-ids and init-exprs follow the textual, left-to-right order relative to the for-clauses, except that (for historical reasons) accum-ids are not available in the for-clauses for the outermost iteration. The lifetimes of variables are not quite the same as the lexical nesting, however: the variable referenced by a accum-id has a fresh location in each iteration.
Changed in version 6.11.0.1 of package base: Added the #:result form.
Changed in version 8.11.1.3: Changed evaluation order to match textual left-to-right order,
including evaluating init-exprs before the first
for-clause’s right-hand side and fixing shadowing of
accum-id.
syntax
(for/foldr ([accum-id init-expr] ... accum-option ...) (for-clause ...) body-or-break ... body)
accum-option = #:result result-expr | #:delay | #:delay-as delayed-id | #:delay-with delayer-id
> (define (in-printing seq) (sequence-map (lambda (v) (println v) v) seq))
> (for/foldr ([acc '()]) ([v (in-printing (in-range 1 4))]) (println v) (cons v acc))
1
2
3
3
2
1
'(1 2 3)
Furthermore, unlike for/fold, the accum-ids are not bound within guard-exprs or body-or-break forms that appear before a break-clause.
While the aforementioned limitations make for/foldr less generally useful than for/fold, for/foldr provides the additional capability to iterate lazily via the #:delay, #:delay-as, and #:delay-with options, which can mitigate many of for/foldr’s disadvantages. If at least one such option is specified, the loop body is given explicit control over when iteration continues: by default, each accum-id is bound to a promise that, when forced, produces the accum-id’s current value.
In this mode, iteration does not continue until one such promise is forced,
which triggers any additional iteration necessary to produce a value. If the
loop body is lazy in its accum-ids—
> (for/foldr ([acc '()] #:delay) ([v (in-range 1 4)]) (printf "--> ~v\n" v) (begin0 (cons v (force acc)) (printf "<-- ~v\n" v)))
--> 1
--> 2
--> 3
<-- 3
<-- 2
<-- 1
'(1 2 3)
> (define resume (for/foldr ([acc '()] #:delay) ([v (in-range 1 5)]) (printf "--> ~v\n" v) (begin0 (cond [(= v 1) (force acc)] [(= v 2) acc] [else (cons v (force acc))]) (printf "<-- ~v\n" v))))
--> 1
--> 2
<-- 2
<-- 1
> (force resume)
--> 3
--> 4
<-- 4
<-- 3
'(3 4)
This extra control over iteration order allows for/foldr to both consume and construct infinite sequences, so long as it is at least sometimes lazy in its accumulators.
See also for/stream for a more convenient (albeit less flexible) way to lazily transform infinite sequences. (Internally, for/stream is defined in terms of for/foldr.)
> (define squares (for/foldr ([s empty-stream] #:delay) ([n (in-naturals)]) (stream-cons (* n n) (force s)))) > (stream->list (stream-take squares 10)) '(0 1 4 9 16 25 36 49 64 81)
The suspension introduced by the #:delay option does not ordinarily affect the loop’s eventual return value, but if #:delay and #:result are combined, the accum-ids will be delayed in the scope of the result-expr in the same way they are delayed within the loop body. This can be used to introduce an additional layer of suspension around the evaluation of the entire loop, if desired.
> (define evaluated-yet? #f)
> (define start (for/foldr ([acc (set! evaluated-yet? #t)] #:delay #:result acc) () (force acc))) > evaluated-yet? #f
> (force start) > evaluated-yet? #t
If the #:delay-as option is provided, then delayed-id is bound to an additional promise that returns the values of all accum-ids at once. When multiple accum-ids are provided, forcing this promise can be slightly more efficient than forcing the promises bound to the accum-ids individually.
If the #:delay-with option is provided, the given delayer-id is used to suspend nested iterations (instead of the default, delay). A form of the shape (delayer-id recur-expr) is constructed and placed in expression position, where recur-expr is an expression that, when evaluated, will perform the next iteration and return its result (or results). Sensible choices for delayer-id include lazy, delay/sync, delay/thread, or any of the other promise constructors from racket/promise, as well as thunk from racket/function. However, beware that choices such as thunk or delay/name may evaluate their subexpression multiple times, which can lead to nonsensical results for sequences that have state, as the state will be shared between all evaluations of the recur-expr.
If multiple accum-ids are given, the #:delay-with option is provided, and delayer-id is not bound to one of delay, lazy, delay/strict, delay/sync, delay/thread, or delay/idle, the accum-ids will not be bound at all, even within the loop body. Instead, the #:delay-as option must be specified to access the accumulator values via delayed-id.
Added in version 7.3.0.3 of package base.
syntax
(for* (for-clause ...) body-or-break ... body)
syntax
(for*/list (for-clause ...) body-or-break ... body)
syntax
(for*/lists (id ... maybe-result) (for-clause ...) body-or-break ... body)
syntax
(for*/vector maybe-length (for-clause ...) body-or-break ... body)
syntax
(for*/hash (for-clause ...) body-or-break ... body)
syntax
(for*/hasheq (for-clause ...) body-or-break ... body)
syntax
(for*/hasheqv (for-clause ...) body-or-break ... body)
syntax
(for*/hashalw (for-clause ...) body-or-break ... body)
syntax
(for*/and (for-clause ...) body-or-break ... body)
syntax
(for*/or (for-clause ...) body-or-break ... body)
syntax
(for*/sum (for-clause ...) body-or-break ... body)
syntax
(for*/product (for-clause ...) body-or-break ... body)
syntax
(for*/first (for-clause ...) body-or-break ... body)
syntax
(for*/last (for-clause ...) body-or-break ... body)
syntax
(for*/fold ([accum-id init-expr] ... maybe-result) (for-clause ...) body-or-break ... body)
syntax
(for*/foldr ([accum-id init-expr] ... accum-option ...) (for-clause ...) body-or-break ... body)
Changed in version 7.3.0.3 of package base: Added the for*/foldr form.
Changed in version 8.5.0.3: Added the for*/hashalw form.
3.18.2 Deriving New Iteration Forms
syntax
(for/fold/derived orig-datum ([accum-id init-expr] ... maybe-result) (for-clause ...) body-or-break ... body)
A macro that expands to for/fold/derived should typically use split-for-body to handle the possibility of macros and other definitions mixed with keywords like #:break.
> (require (for-syntax syntax/for-body) syntax/parse/define)
> (define-syntax-parse-rule (for/digits clauses body ... tail-expr) #:with original this-syntax #:with ((pre-body ...) (post-body ...)) (split-for-body this-syntax #'(body ... tail-expr)) (for/fold/derived original ([n 0] [k 1] #:result n) clauses pre-body ... (values (+ n (* (let () post-body ...) k)) (* k 10)))) ; If we misuse for/digits, we can get good error reporting ; because the use of orig-datum allows for source correlation:
> (for/digits [a (in-list '(1 2 3))] [b (in-list '(4 5 6))] (+ a b)) eval:4:0: for/digits: bad sequence binding clause
at: a
in: (for/digits (a (in-list (quote (1 2 3)))) (b (in-list
(quote (4 5 6)))) (+ a b))
> (for/digits ([a (in-list '(1 2 3))] [b (in-list '(2 4 6))]) (+ a b)) 963
; Another example: compute the max during iteration:
> (define-syntax-parse-rule (for/max clauses body ... tail-expr) #:with original this-syntax #:with ((pre-body ...) (post-body ...)) (split-for-body this-syntax #'(body ... tail-expr)) (for/fold/derived original ([current-max -inf.0]) clauses pre-body ... (define maybe-new-max (let () post-body ...)) (if (> maybe-new-max current-max) maybe-new-max current-max)))
> (for/max ([n '(3.14159 2.71828 1.61803)] [s '(-1 1 1)]) (* n s)) 2.71828
Changed in version 6.11.0.1 of package base: Added the #:result form.
syntax
(for*/fold/derived orig-datum ([accum-id init-expr] ... maybe-result) (for-clause ...) body-or-break ... body)
> (require (for-syntax syntax/for-body) syntax/parse/define)
> (define-syntax-parse-rule (for*/digits clauses body ... tail-expr) #:with original this-syntax #:with ((pre-body ...) (post-body ...)) (split-for-body this-syntax #'(body ... tail-expr)) (for*/fold/derived original ([n 0] [k 1] #:result n) clauses pre-body ... (values (+ n (* (let () post-body ...) k)) (* k 10))))
> (for*/digits [ds (in-list '((8 3) (1 1)))] [d (in-list ds)] d) eval:10:0: for*/digits: bad sequence binding clause
at: ds
in: (for*/digits (ds (in-list (quote ((8 3) (1 1))))) (d
(in-list ds)) d)
> (for*/digits ([ds (in-list '((8 3) (1 1)))] [d (in-list ds)]) d) 1138
Changed in version 6.11.0.1 of package base: Added the #:result form.
syntax
(for/foldr/derived orig-datum ([accum-id init-expr] ... accum-option ...) (for-clause ...) body-or-break ... body)
syntax
(for*/foldr/derived orig-datum ([accum-id init-expr] ... accum-option ...) (for-clause ...) body-or-break ... body)
Added in version 7.3.0.3 of package base.
syntax
(define-sequence-syntax id expr-transform-expr clause-transform-expr)
expr-transform-expr :
(or/c (-> identifier?) (syntax? . -> . syntax?))
clause-transform-expr : (syntax? . -> . syntax?)
When id is used in any other expression position, the result of expr-transform-expr is used. If it is a procedure of zero arguments, then the result must be an identifier other-id, and any use of id is converted to a use of other-id. Otherwise, expr-transform-expr must produce a procedure (of one argument) that is used as a macro transformer.
When the clause-transform-expr transformer is used, it is given a for-clause as an argument, where the clause’s form is normalized so that the left-hand side is a parenthesized sequence of identifiers. The right-hand side is of the form (id . rest). The result can be either #f, to indicate that the forms should not be treated specially (perhaps because the number of bound identifiers is inconsistent with the (id . rest) form), or a new for-clause to replace the given one. The new clause might use :do-in. To protect identifiers in the result of clause-transform-expr, use for-clause-syntax-protect instead of syntax-protect.
> (define (check-nat n) (unless (exact-nonnegative-integer? n) (raise-argument-error 'in-digits "exact-nonnegative-integer?" n)))
> (define-sequence-syntax in-digits (lambda () #'in-digits/proc) (lambda (stx) (syntax-case stx () [[(d) (_ nat)] #'[(d) (:do-in ([(n) nat]) (check-nat n) ([i n]) (not (zero? i)) ([(j d) (quotient/remainder i 10)]) #t #t [j])]] [_ #f])))
> (define (in-digits/proc n) (for/list ([d (in-digits n)]) d)) > (for/list ([d (in-digits 1138)]) d) '(8 3 1 1)
> (map in-digits (list 137 216)) '((7 3 1) (6 1 2))
syntax
(:do-in ([(outer-id ...) outer-expr] ...) outer-defn-or-expr ([loop-id loop-expr] ...) pos-guard ([(inner-id ...) inner-expr] ...) maybe-inner-defn-or-expr pre-guard post-guard (loop-arg ...))
maybe-inner-defn/expr =
| inner-defn-or-expr
Within a for, the pieces of the :do-in form are spliced into the iteration essentially as follows:
(let-values ([(outer-id ...) outer-expr] ...) outer-defn-or-expr (let loop ([loop-id loop-expr] ...) (if pos-guard (let-values ([(inner-id ...) inner-expr] ...) inner-defn-or-expr (if pre-guard (let body-bindings (if post-guard (loop loop-arg ...) done-expr)) done-expr)) done-expr)))
where body-bindings and done-expr are from the context of the :do-in use. The identifiers bound by the for clause are typically part of the ([(inner-id ...) inner-expr] ...) section. When inner-defn-or-expr is not provided (begin) is used in its place.
Beware that body-bindings and done-expr can contain arbitrary expressions, potentially including set! on outer-id or inner-id identifiers if they are visible in the original for form, so beware of depending on such identifiers in post-guard and loop-arg.
The actual loop binding and call has additional loop arguments to support iterations in parallel with the :do-in form, and the other pieces are similarly accompanied by pieces from parallel iterations.
For an example of :do-in, see define-sequence-syntax.
Changed in version 8.10.0.3 of package base: Added support for non-empty maybe-inner-defn-or-expr.
procedure
(for-clause-syntax-protect stx) → syntax?
stx : syntax?
Changed in version 8.2.0.4 of package base: Changed to just return stx instead of returning “armed” syntax.
syntax
(define-splicing-for-clause-syntax id proc-expr)
The procedure’s input is a syntax object that appears after #:splice. The result syntax object must be a parenthesized sequence of forms, and the forms are spliced in place of the #:splice clause in the enclosing for form.
> (define-splicing-for-clause-syntax cross3 (lambda (stx) (syntax-case stx () [(_ n m) #'([n (in-range 3)] #:when #t [m (in-range 3)])])))
> (for (#:splice (cross3 n m)) (println (list n m)))
'(0 0)
'(0 1)
'(0 2)
'(1 0)
'(1 1)
'(1 2)
'(2 0)
'(2 1)
'(2 2)
Added in version 8.4.0.3 of package base.
3.18.3 Iteration Expansion
| (require racket/for-clause) | package: base |
Added in version 8.11.1.4 of package base.
3.18.4 Do Loops
syntax
(do ([id init-expr step-expr-maybe] ...) (stop?-expr finish-expr ...) expr ...)
step-expr-maybe =
| step-expr
To initialize the loop, the init-exprs are evaluated in order and bound to the corresponding ids. The ids are bound in all expressions within the form other than the init-exprs.
After the ids have been bound, the stop?-expr is evaluated. If it produces #f, each expr is evaluated for its side-effect. The ids are then effectively updated with the values of the step-exprs, where the default step-expr for id is just id; more precisely, iteration continues with fresh locations for the ids that are initialized with the values of the corresponding step-exprs.
When stop?-expr produces a true value, then the finish-exprs are evaluated in order, and the last one is evaluated in tail position to produce the overall value for the do form. If no finish-expr is provided, the value of the do form is #<void>.