6.9 Comprehensions and Sequences

Sometimes sequential processing is unavoidable, so math/array provides loops and sequences.

syntax
(for/array: maybe-shape maybe-fill (for:-clause ...) maybe-type-ann
  body ...+)
syntax
(for*/array: maybe-shape maybe-fill (for:-clause ...) maybe-type-ann
  body ...+)

maybe-shape =
| #:shape ds

maybe-fill =
| #:fill fill

maybe-type-ann =
| : body-type

   ds : In-Indexes
   fill : body-type

Creates arrays by generating elements in a for-loop or for*-loop. Unlike other Typed Racket loop macros, these accept a body annotation, which declares the type of elements. They do not accept an annotation for the entire type of the result.

Examples:

> (for/array: ([x  (in-range 3)] [y  (in-range 3)]) : Integer
    (+ x y))
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Integer)
       (-> Indexes Integer Void)
       (Vectorof Integer))
      #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array #[0 2 4])
> (for*/array: ([x  (in-range 3)] [y  (in-range 3)]) : Integer
    (+ x y))
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Integer)
       (-> Indexes Integer Void)
       (Vectorof Integer))
      #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array #[0 1 2 1 2 3 2 3 4])

The shape of the result is independent of the loop clauses: note that the last example does not have shape #(3 3), but shape #(9). To control the shape, use the #:shape keyword:

> (for*/array: #:shape #(3 3) ([x  (in-range 3)]
                               [y  (in-range 3)]) : Integer
    (+ x y))
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Integer)
       (-> Indexes Integer Void)
       (Vectorof Integer))
      #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array #[#[0 1 2] #[1 2 3] #[2 3 4]])

If the loop does not generate enough elements, the rest are filled with the first generated value:

> (for*/array: #:shape #(4) ([x  (in-range 1 3)]) x)
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Any)
       (-> Indexes Any Void)
       (Vectorof Any))
      #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array #[1 2 1 1])

To change this behavior, use the #:fill keyword:

> (for*/array: #:shape #(4) #:fill -1 ([x  (in-range 1 3)]) x)
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Any)
       (-> Indexes Any Void)
       (Vectorof Any))
      #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array #[1 2 -1 -1])

In the last two examples, the array’s type is (Mutable-Array Any) because a body annotation was not given.

syntax
(for/array maybe-shape maybe-fill (for-clause ...)
body ...+)
syntax
(for*/array maybe-shape maybe-fill (for-clause ...)
body ...+)

Untyped versions of the loop macros.

procedure
(in-array arr) → (Sequenceof A)
arr : (Array A)

Returns a sequence of arr’s elements in row-major order.

Examples:

> (define arr (array #[#[1 2] #[10 20]]))
> (for/list: : (Listof Integer) ([x (in-array arr)]) x)
- : (Listof Integer)
'(1 2 10 20)

procedure
(in-array-axis arr [axis]) → (Sequenceof (Array A))
arr : (Array A)
axis : Integer = 0

Like array->array-list, but returns a sequence.

Examples:

> (define arr (array #[#[1 2] #[10 20]]))
> (sequence->list (in-array-axis arr))
- : (Listof
     #(struct:Array
       (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Byte))
       #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
       #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
       #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>))
(list (array #[1 2]) (array #[10 20]))
> (sequence->list (in-array-axis arr 1))
- : (Listof
     #(struct:Array
       (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Byte))
       #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
       #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
       #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>))
(list (array #[1 10]) (array #[2 20]))

procedure
(in-array-indexes ds) → (Sequenceof Indexes)
ds : In-Indexes

Returns a sequence of indexes for shape ds, in row-major order.

Examples:

> (for/array: #:shape #(3 3) ([js  (in-array-indexes #(3 3))]) : Indexes
    js)
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Indexes)
       (-> Indexes Indexes Void)
       (Vectorof Indexes))
      #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array
#[#['#(0 0) '#(0 1) '#(0 2)]
   #['#(1 0) '#(1 1) '#(1 2)]
   #['#(2 0) '#(2 1) '#(2 2)]])
> (for*/array: #:shape #(3 3) ([j0  (in-range 3)]
                               [j1  (in-range 3)]) : In-Indexes
    (vector j0 j1))
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes In-Indexes)
       (-> Indexes In-Indexes Void)
       (Vectorof In-Indexes))
      #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array
#[#['#(0 0) '#(0 1) '#(0 2)]
   #['#(1 0) '#(1 1) '#(1 2)]
   #['#(2 0) '#(2 1) '#(2 2)]])
> (indexes-array #(3 3))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Indexes))
      #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.7/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array
#[#['#(0 0) '#(0 1) '#(0 2)]
   #['#(1 0) '#(1 1) '#(1 2)]
   #['#(2 0) '#(2 1) '#(2 2)]])

1	Constants and Elementary Functions
2	Flonums
3	Special Functions
4	Number Theory
5	Arbitrary-Precision Floating-Point Numbers (Bigfloats)
6	Arrays
7	Matrices and Linear Algebra
8	Statistics Functions
9	Probability Distributions
10	Stuff That Doesn’t Belong Anywhere Else

6.1	Quick Start
6.2	Definitions
6.3	Broadcasting
6.4	Slicing
6.5	Nonstrict Arrays
6.6	Types, Predicates and Accessors
6.7	Construction
6.8	Conversion
6.9	Comprehensions and Sequences
6.10	Pointwise Operations
6.11	Indexing and Slicing
6.12	Transformations
6.13	Folds, Reductions and Expansions
6.14	Other Array Operations
6.15	Subtypes
6.16	Strictness