On this page:
array-transform
array-append*
array-axis-insert
array-axis-ref
array-axis-swap
array-axis-permute
array-reshape
array-flatten

6.12 Transformations

procedure

(array-transform arr ds proc)  (Array A)

  arr : (Array A)
  ds : In-Indexes
  proc : (Indexes -> In-Indexes)
Returns an array with shape ds and elements taken from arr, by composing arr’s procedure with proc.

Possibly the most useless, but simplest example of proc disregards its input indexes and returns constant indexes:
> (define arr (array #[#[0 1] #[2 'three]]))
> (array-transform arr #(3 3) (λ: ([js : Indexes]) #(1 1)))

- : (Array (U 'three Byte))

(array

 #[#['three 'three 'three]

   #['three 'three 'three]

   #['three 'three 'three]])

Doubling an array in every dimension by duplicating elements:
> (define arr (index-array #(3 3)))
> arr

- : (Array Index)

(array #[#[0 1 2] #[3 4 5] #[6 7 8]])

> (array-transform
   arr
   (vector-map (λ: ([d : Index]) (* d 2)) (array-shape arr))
   (λ: ([js : Indexes])
     (vector-map (λ: ([j : Index]) (quotient j 2)) js)))

- : (Array Index)

(array

 #[#[0 0 1 1 2 2]

   #[0 0 1 1 2 2]

   #[3 3 4 4 5 5]

   #[3 3 4 4 5 5]

   #[6 6 7 7 8 8]

   #[6 6 7 7 8 8]])

When array-strictness is #f, the above result takes little more space than the original array.

Almost all array transformations, including Slicing, are implemented using array-transform or its unsafe counterpart.

procedure

(array-append* arrs [k])  (Array A)

  arrs : (Listof (Array A))
  k : Integer = 0
Appends the arrays in arrs along axis k. If the arrays’ shapes are not the same, they are broadcast first.

Examples:
> (define arr (array #[#[0 1] #[2 3]]))
> (define brr (array #[#['a 'b] #['c 'd]]))
> (array-append* (list arr brr))

- : (Array (U 'a 'b 'c 'd Byte))

(array #[#[0 1] #[2 3] #['a 'b] #['c 'd]])

> (array-append* (list arr brr) 1)

- : (Array (U 'a 'b 'c 'd Byte))

(array #[#[0 1 'a 'b] #[2 3 'c 'd]])

> (array-append* (list arr (array 'x)))

- : (Array (U 'x Byte))

(array #[#[0 1] #[2 3] #['x 'x]])

For an append-like operation that increases the dimension of the broadcast arrays, see array-list->array.

procedure

(array-axis-insert arr k [dk])  (Array A)

  arr : (Array A)
  k : Integer
  dk : Integer = 1
Inserts an axis of length dk before axis number k, which must be no greater than the dimension of arr.

Examples:
> (define arr (array #[#[0 1] #[2 3]]))
> (array-axis-insert arr 0)

- : (Array Byte)

(array #[#[#[0 1] #[2 3]]])

> (array-axis-insert arr 1)

- : (Array Byte)

(array #[#[#[0 1]] #[#[2 3]]])

> (array-axis-insert arr 2)

- : (Array Byte)

(array #[#[#[0] #[1]] #[#[2] #[3]]])

> (array-axis-insert arr 1 2)

- : (Array Byte)

(array #[#[#[0 1] #[0 1]] #[#[2 3] #[2 3]]])

procedure

(array-axis-ref arr k jk)  (Array A)

  arr : (Array A)
  k : Integer
  jk : Integer
Removes an axis from arr by keeping only row jk in axis k, which must be less than the dimension of arr.

Examples:
> (define arr (array #[#[0 1] #[2 3]]))
> (array-axis-ref arr 0 0)

- : (Array Byte)

(array #[0 1])

> (array-axis-ref arr 0 1)

- : (Array Byte)

(array #[2 3])

> (array-axis-ref arr 1 0)

- : (Array Byte)

(array #[0 2])

procedure

(array-axis-swap arr k0 k1)  (Array A)

  arr : (Array A)
  k0 : Integer
  k1 : Integer
Returns an array like arr, but with axes k0 and k1 swapped. In two dimensions, this is called a transpose.

Examples:
> (array-axis-swap (array #[#[0 1] #[2 3]]) 0 1)

- : (Array Byte)

(array #[#[0 2] #[1 3]])

> (define arr (indexes-array #(2 2 2)))
> arr

- : (Array Indexes)

(array

 #[#[#['#(0 0 0) '#(0 0 1)]

     #['#(0 1 0) '#(0 1 1)]]

   #[#['#(1 0 0) '#(1 0 1)]

     #['#(1 1 0) '#(1 1 1)]]])

> (array-axis-swap arr 0 1)

- : (Array Indexes)

(array

 #[#[#['#(0 0 0) '#(0 0 1)]

     #['#(1 0 0) '#(1 0 1)]]

   #[#['#(0 1 0) '#(0 1 1)]

     #['#(1 1 0) '#(1 1 1)]]])

> (array-axis-swap arr 1 2)

- : (Array Indexes)

(array

 #[#[#['#(0 0 0) '#(0 1 0)]

     #['#(0 0 1) '#(0 1 1)]]

   #[#['#(1 0 0) '#(1 1 0)]

     #['#(1 0 1) '#(1 1 1)]]])

procedure

(array-axis-permute arr perm)  (Array A)

  arr : (Array A)
  perm : (Listof Integer)
Returns an array like arr, but with axes permuted according to perm.

The list perm represents a mapping from source axis numbers to destination axis numbers: the source is the list position, the destination is the list element. For example, the permutation '(0 1 2) is the identity permutation for three-dimensional arrays, '(1 0) swaps axes 0 and 1, and '(3 1 2 0) swaps axes 0 and 3.

The permutation must contain each integer from 0 to (- (array-dims arr) 1) exactly once.

Examples:
> (array-axis-swap (array #[#[0 1] #[2 3]]) 0 1)

- : (Array Byte)

(array #[#[0 2] #[1 3]])

> (array-axis-permute (array #[#[0 1] #[2 3]]) '(1 0))

- : (Array Byte)

(array #[#[0 2] #[1 3]])

procedure

(array-reshape arr ds)  (Array A)

  arr : (Array A)
  ds : In-Indexes
Returns an array with elements in the same row-major order as arr, but with shape ds. The product of the indexes in ds must be (array-size arr).

Examples:
> (define arr (indexes-array #(2 3)))
> arr

- : (Array Indexes)

(array #[#['#(0 0) '#(0 1) '#(0 2)] #['#(1 0) '#(1 1) '#(1 2)]])

> (array-reshape arr #(3 2))

- : (Array Indexes)

(array #[#['#(0 0) '#(0 1)] #['#(0 2) '#(1 0)] #['#(1 1) '#(1 2)]])

> (array-reshape (index-array #(3 3)) #(9))

- : (Array Index)

(array #[0 1 2 3 4 5 6 7 8])

procedure

(array-flatten arr)  (Array A)

  arr : (Array A)
Returns an array with shape (vector (array-size arr)), with the elements of arr in row-major order.

Examples:
> (array-flatten (array 10))

- : (Array Positive-Byte)

(array #[10])

> (array-flatten (array #[#[0 1] #[2 3]]))

- : (Array Byte)

(array #[0 1 2 3])