6.7 Construction

► |  | Math Library

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 | Arrays

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

On this page:

array
mutable-array
make-array
build-array
array->mutable-array
mutable-array-copy
indexes-array
index-array
axis-index-array
diagonal-array

top contents ← prev up next →

### 6.7 Construction🔗ℹ

> syntax (array #[#[...] ...] maybe-type-ann)
> maybe-type-ann |  | = |  |
> |  | | |  | : type

Creates an Array from nested rows of expressions.

The vector syntax #[...] delimits rows. These may be nested to any depth, and must have a rectangular shape. Using square parentheses is not required, but is encouraged to help visually distinguish array contents from array indexes and other vectors. (See the examples for indexes-array for an illustration.)

Examples:

> > (array 0)
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Zero))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array 0)
> > (array #[0 1 2 3])
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[0 1 2 3])
> > (array #[#[1 2 3] #[4 5 6]])
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Byte))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[#[1 2 3] #[4 5 6]])
> > (array #[#[1 2 3] #[4 5]])
> eval:121:0: array: expected rectangular data
> at: #(#(1 2 3) #(4 5))
> in: (array/syntax array list unsafe-list->array #(#(1 2 3)
> #(4 5)))

As with the list constructor, the type chosen for the array is the narrowest type all the elements can have. Unlike list, because array is syntax, instantiating array with the desired element type is a syntax error:

> > (list 1 2 3)
> - : (List One Positive-Byte Positive-Byte)
> '(1 2 3)
> > (array #[1 2 3])
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Byte))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[1 2 3])
> > ((inst list Real) 1 2 3)
> - : (Listof Real)
> '(1 2 3)
> > ((inst array Real) #[1 2 3])
> eval:125:0: array: not allowed as an expression
> in: array

There are two easy ways to annotate the element type:

> > (array #[1 2 3] : Real)
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Real))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[1 2 3])
> > (ann (array #[1 2 3]) (Array Real))
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Real))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[1 2 3])

Annotating should rarely be necessary because the Array type is covariant.

Normally, the datums within literal vectors are implicitly quoted. However, when used within the array form, the datums must be explicitly quoted.

> > #(this is okay)
> - : (Immutable-Vector 'this 'is 'okay)
> '#(this is okay)
> > (array #[not okay])
> eval:129:0: Type Checker: missing type for top-level
> identifier;
> either undefined or missing a type annotation
> identifier: okay
> in: #(not okay)
> > (array #['this 'is 'okay])
> - : #(struct:Array
> (Indexes
> Index
> (Boxof Boolean)
> (-> Void)
> (-> Indexes (U 'is 'okay 'this)))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #['this 'is 'okay])
> > (array #['#(an) '#(array) '#(of) '#(vectors)])
> - : #(struct:Array
> (Indexes
> Index
> (Boxof Boolean)
> (-> Void)
> (-> Indexes
> (U (Immutable-Vector 'an)
> (Immutable-Vector 'array)
> (Immutable-Vector 'of)
> (Immutable-Vector 'vectors))))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #['#(an) '#(array) '#(of) '#(vectors)])

Arrays returned by array are strict. Another way to create immutable, strict arrays from literal data is to use list->array.

> syntax (mutable-array #[#[...] ...] maybe-type-ann)
> maybe-type-ann |  | = |  |
> |  | | |  | : type

Creates a Mutable-Array from nested rows of expressions.

The semantics are almost identical to array’s, except the result is mutable:

> > (define arr (mutable-array #[0 1 2 3]))
> > arr
> - : #(struct:Mutable-Array
> (Indexes
> Index
> (Boxof Boolean)
> (-> Void)
> (-> Indexes Integer)
> (-> Indexes Integer Void)
> (Vectorof Integer))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
> (mutable-array #[0 1 2 3])
> > (array-set! arr #(0) 10)
> > arr
> - : #(struct:Mutable-Array
> (Indexes
> Index
> (Boxof Boolean)
> (-> Void)
> (-> Indexes Integer)
> (-> Indexes Integer Void)
> (Vectorof Integer))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
> (mutable-array #[10 1 2 3])

Because mutable arrays are invariant, this form additionally accepts a type annotation for the array’s elements:

> > (define arr (mutable-array #[0 1 2 3] : Real))
> > arr
> - : #(struct:Mutable-Array
> (Indexes
> Index
> (Boxof Boolean)
> (-> Void)
> (-> Indexes Real)
> (-> Indexes Real Void)
> (Vectorof Real))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
> (mutable-array #[0 1 2 3])
> > (array-set! arr #(0) 10.0)
> > arr
> - : #(struct:Mutable-Array
> (Indexes
> Index
> (Boxof Boolean)
> (-> Void)
> (-> Indexes Real)
> (-> Indexes Real Void)
> (Vectorof Real))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
> (mutable-array #[10.0 1 2 3])

Another way to create mutable arrays from literal data is to use vector->array.

> procedure (make-array ds value) → (Array A)
> ds : In-Indexes
> value : A

Returns an array with shape ds, with every element’s value as value. Analogous to make-vector.

Examples:

> > (make-array #() 5)
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Byte))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array 5)
> > (make-array #(1 2) 'sym)
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes 'sym))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[#['sym 'sym]])
> > (make-array #(4 0 2) "Invisible")
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes String))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[#[] #[] #[] #[]])

The arrays returned by make-array do not allocate storage for their elements and are strict.

> procedure (build-array ds proc) → (Array A)
> ds : In-Indexes
> proc : (Indexes -> A)

Returns an array with shape ds and procedure proc. Analogous to build-vector.

> procedure (array->mutable-array arr) → (Mutable-Array A)
> arr : (Array A)

Returns a mutable array with the same elements as arr. The result is a copy of arr, even when arr is mutable.

> procedure (mutable-array-copy arr) → (Mutable-Array A)
> arr : (Mutable-Array A)

Like (array->mutable-array arr), but restricted to mutable arrays. It is also faster.

> procedure (indexes-array ds) → (Array Indexes)
> ds : In-Indexes

Returns an array with shape ds, with each element set to its position in the array.

Examples:

> > (indexes-array #())
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Indexes))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array '#())
> > (indexes-array #(4))
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Indexes))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #['#(0) '#(1) '#(2) '#(3)])
> > (indexes-array #(2 3))
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Indexes))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/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)]])
> > (indexes-array #(4 0 2))
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Indexes))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[#[] #[] #[] #[]])

The resulting array does not allocate storage for its return value’s elements, and is strict. (It is essentially the identity function for the domain ds.)

> procedure (index-array ds) → (Array Index)
> ds : In-Indexes

Returns an array with shape ds, with each element set to its row-major index in the array.

Examples:

> > (index-array #(2 3))
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Index))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[#[0 1 2] #[3 4 5]])
> > (array-flatten (index-array #(2 3)))
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Index))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[0 1 2 3 4 5])

As with indexes-array, the result does not allocate storage for its elements, and is strict.

> procedure (axis-index-array ds axis) → (Array Index)
> ds : In-Indexes
> axis : Integer

Returns an array with shape ds, with each element set to its position in axis axis. The axis number axis must be nonnegative and less than the number of axes (the length of ds).

Examples:

> > (axis-index-array #(3 3) 0)
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Index))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[#[0 0 0] #[1 1 1] #[2 2 2]])
> > (axis-index-array #(3 3) 1)
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Index))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[#[0 1 2] #[0 1 2] #[0 1 2]])
> > (axis-index-array #() 0)
> axis-index-array: contract violation
> expected: Index < 0
> given: 0
> argument position: 2nd
> other arguments...:
> '#()

As with indexes-array, the result does not allocate storage for its elements, and is strict.

> > procedure
> > (diagonal-array |  | dims |  |  |  |
> > |  | axes-length |  |  |  |
> > |  | on-value |  |  |  |
> > |  | off-value) |  | → |  | (Array A)
> dims : Integer
> axes-length : Integer
> on-value : A
> off-value : A

Returns an array with dims axes, each with length axes-length. (For example, the returned array for dims = 2 is square.) The elements on the diagonal (i.e. at indexes of the form (vector j j ...) for j < axes-length) have the value on-value; the rest have off-value.

Example:

> > (diagonal-array 2 7 1 0)
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes (U One Zero)))
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/9.0/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array
> #[#[1 0 0 0 0 0 0]
> #[0 1 0 0 0 0 0]
> #[0 0 1 0 0 0 0]
> #[0 0 0 1 0 0 0]
> #[0 0 0 0 1 0 0]
> #[0 0 0 0 0 1 0]
> #[0 0 0 0 0 0 1]])

As with indexes-array, the result does not allocate storage for its elements, and is strict.
top contents ← prev up next →