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)))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes (U 'three Byte)))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(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
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Index))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(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)))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Index))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(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))
- : #(struct:Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes (U 'a 'b 'c 'd Byte)))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[0 1] #[2 3] #['a 'b] #['c 'd]])
> (array-append* (list arr brr) 1)
- : #(struct:Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes (U 'a 'b 'c 'd Byte)))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[0 1 'a 'b] #[2 3 'c 'd]])
> (array-append* (list arr (array 'x)))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes (U 'x Byte)))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(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)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[#[0 1] #[2 3]]])
> (array-axis-insert arr 1)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[#[0 1]] #[#[2 3]]])
> (array-axis-insert arr 2)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[#[0] #[1]] #[#[2] #[3]]])
> (array-axis-insert arr 1 2)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(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)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[0 1])
> (array-axis-ref arr 0 1)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[2 3])
> (array-axis-ref arr 1 0)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(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)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[0 2] #[1 3]])
> (define arr (indexes-array #(2 2 2)))
> arr
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Indexes))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(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)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Indexes))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(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)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Indexes))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(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)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[0 2] #[1 3]])
> (array-axis-permute (array #[#[0 1] #[2 3]]) '(1 0))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(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
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Indexes))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/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)]])
> (array-reshape arr #(3 2))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Indexes))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/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)]])
> (array-reshape (index-array #(3 3)) #(9))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Index))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(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))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[10])
> (array-flatten (array #[#[0 1] #[2 3]]))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[0 1 2 3])

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