6.1 Quick Start

6.1 Quick Start🔗ℹ

Arrays can be created from expressions denoting each element’s value using the array macro:

> (array #[0 1 2 3 4])
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[0 1 2 3 4])
> (array #[#['first 'row 'data] #['second 'row 'data]])
- : #(struct:Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes (U 'data 'first 'row 'second)))
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#['first 'row 'data] #['second 'row 'data]])
> (array "This array has zero axes and one element")
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes String))
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array "This array has zero axes and one element")

They can also be created using build-array to specify a shape and procedure:

> (define arr
    (build-array #(4 5) (λ: ([js : Indexes])
                          (match-define (vector j0 j1) js)
                          (+ j0 j1))))
> arr
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Nonnegative-Fixnum))
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[0 1 2 3 4] #[1 2 3 4 5] #[2 3 4 5 6] #[3 4 5 6 7]])

Other ways to create arrays are to convert them from lists and vectors using list->array, list*->array, vector->array and vector*->array, and to generate them in a loop using for/array: and for*/array:.

Arrays can be indexed using array-ref, and settable arrays can be mutated using array-set!:

> (array-ref arr #(2 3))
- : Integer [more precisely: Nonnegative-Fixnum]
5
> (define brr (array->mutable-array arr))
> (array-set! brr #(2 3) -1000)
> brr
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Integer)
       (-> Indexes Integer Void)
       (Vectorof Integer))
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array #[#[0 1 2 3 4] #[1 2 3 4 5] #[2 3 4 -1000 6] #[3 4 5 6 7]])

However, both of these activities are discouraged in favor of functional, whole-array operations.

Arrays can be mapped over and otherwise operated on pointwise:

> (array-map (λ: ([n : Natural]) (* 2 n)) arr)
- : #(struct:Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Nonnegative-Integer))
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[0 2 4 6 8] #[2 4 6 8 10] #[4 6 8 10 12] #[6 8 10 12 14]])
> (array+ arr arr)
- : #(struct:Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Nonnegative-Integer))
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[0 2 4 6 8] #[2 4 6 8 10] #[4 6 8 10 12] #[6 8 10 12 14]])

When arrays have different shapes, they can often be broadcast, or stretched, to be the same shape before applying the pointwise operation:

> (array* arr (array 2))
- : #(struct:Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Nonnegative-Integer))
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[0 2 4 6 8] #[2 4 6 8 10] #[4 6 8 10 12] #[6 8 10 12 14]])
> (array* arr (array #[0 2 0 2 0]))
- : #(struct:Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Nonnegative-Integer))
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[0 2 0 6 0] #[0 4 0 8 0] #[0 6 0 10 0] #[0 8 0 12 0]])

By default, zero-dimensional arrays like (array 2) can be broadcast to any shape. See Broadcasting for details.

Arrays can be sliced to yield sub-arrays, using a list of slice specifications that correspond to array axes. For example, keeping every row of arr and every even-numbered column:

> (array-slice-ref arr (list (::) (:: 0 5 2)))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Nonnegative-Fixnum))
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.15.0.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[0 2 4] #[1 3 5] #[2 4 6] #[3 5 7]])

Here, :: has semantics almost, but not quite, entirely unlike in-range. See Slicing for details.

Functional code that uses whole-array operations often creates many short-lived, intermediate arrays whose elements are referred to only once. The overhead of allocating and filling storage for these arrays can be removed entirely by using nonstrict arrays, sometimes at the cost of making the code’s performance more difficult to reason about. Another bonus is that computations with nonstrict arrays have fewer synchronization points, meaning that they will be easier to parallelize as Racket’s support for parallel computation improves. See Nonstrict Arrays for details.

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