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])

- : (Array Byte)

(array #[0 1 2 3 4])

> (array #[#['first 'row 'data] #['second 'row 'data]])

- : (Array (U 'data 'first 'row 'second))

(array #[#['first 'row 'data] #['second 'row 'data]])

> (array "This array has zero axes and one element")

- : (Array String)

(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

- : (Array Nonnegative-Fixnum)

(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

- : (Mutable-Array Integer)

(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)

- : (Array Nonnegative-Integer)

(array #[#[0 2 4 6 8] #[2 4 6 8 10] #[4 6 8 10 12] #[6 8 10 12 14]])

> (array+ arr arr)

- : (Array Nonnegative-Integer)

(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))

- : (Array Nonnegative-Integer)

(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]))

- : (Array Nonnegative-Integer)

(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)))

- : (Array Nonnegative-Fixnum)

(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.