►Math Library
▼6 Arrays
►6.8 Conversion
On this page:
Listof*
Vectorof*
list->array
array->list
vector->array
array->vector
list*->array
array->list*
vector*->array
array->vector*
array-list->array
array->array-list
6.8.1 Printing
array-custom-printer
print-array
  top  ← prev  up  next → 

6.8 Conversion

syntax

(Listof* A)

Equivalent to (U A (Listof A) (Listof (Listof A)) ...) if infinite unions were allowed. This is used as an argument type to list*->array and as the return type of array->list*.

syntax

(Vectorof* A)

Like (Listof* A), but for vectors. See vector*->array and array->vector*.

procedure

(list->array lst) → (Array A)

  lst : (Listof A)
(list->array ds lst) → (Array A)
  ds : In-Indexes
  lst : (Listof A)

procedure

(array->list arr) → (Listof A)

  arr : (Array A)
Convert lists to immutable arrays and back.

The two-argument variant of list->array assumes the elements in lst are in row-major order.

For array->list, if arr has no axes or more than one axis, it is (conceptually) flattened before being converted to a list.

Examples:
> (list->array '(1 2 3))

- : (Array Positive-Byte)

(array #[1 2 3])

> (list->array '((1 2 3) (4 5)))

- : (Array

     (U (List One Positive-Byte Positive-Byte)

        (List Positive-Byte Positive-Byte)))

(array #['(1 2 3) '(4 5)])

> (list->array #(2 2) '(1 2 3 4))

- : (Array Positive-Byte)

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

> (array->list (array #[1 2 3]))

- : (Listof Positive-Byte)

'(1 2 3)

> (array->list (array 10))

- : (Listof Positive-Byte)

'(10)

> (array->list (array #[#[1 2 3] #[4 5 6]]))

- : (Listof Positive-Byte)

'(1 2 3 4 5 6)

For conversion between nested lists and multidimensional arrays, see list*->array and array->list*. For conversion from flat values to mutable arrays, see vector->array.

The arrays returned by list->array are always strict.

procedure

(vector->array vec) → (Mutable-Array A)

  vec : (Vectorof A)
(vector->array ds vec) → (Mutable-Array A)
  ds : In-Indexes
  vec : (Vectorof A)

procedure

(array->vector arr) → (Vectorof A)

  arr : (Array A)
Like list->array and array->list, but for vectors.

Examples:
> (vector->array #(1 2 3))

- : (Mutable-Array Integer)

(mutable-array #[1 2 3])

> (vector->array #((1 2 3) (4 5)))

- : (Mutable-Array

     (U (List One Positive-Byte Positive-Byte)

        (List Positive-Byte Positive-Byte)))

(mutable-array #['(1 2 3) '(4 5)])

> (vector->array #(2 2) #(1 2 3 4))

- : (Mutable-Array Integer)

(mutable-array #[#[1 2] #[3 4]])

> (array->vector (array #[1 2 3]))

- : (Vectorof Integer)

'#(1 2 3)

> (array->vector (array 10))

- : (Vectorof Integer)

'#(10)

> (array->vector (array #[#[1 2 3] #[4 5 6]]))

- : (Vectorof Integer)

'#(1 2 3 4 5 6)

For conversion between nested vectors and multidimensional arrays, see vector*->array and array->vector*.

procedure

(list*->array lsts pred?) → (Array A)

  lsts : (Listof* A)
  pred? : ((Listof* A) -> Any : A)
Converts a nested list of elements of type A to an array. The predicate pred? identifies elements of type A. The shape of lsts must be rectangular.

Examples:
> (list*->array 'singleton symbol?)

- : (Array Symbol)

(array 'singleton)

> (list*->array '(0 1 2 3) byte?)

- : (Array Byte)

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

> (list*->array (list (list (list 5) (list 2 3))
                      (list (list 4.0) (list 1.4 0.2 9.3)))
                (make-predicate (Listof Nonnegative-Real)))

- : (Array (Listof Nonnegative-Real))

(mutable-array #[#['(5) '(2 3)] #['(4.0) '(1.4 0.2 9.3)]])

There is no well-typed Typed Racket function that behaves like list*->array but does not require pred?. Without an element predicate, there is no way to prove to the type checker that list*->array’s implementation correctly distinguishes elements from rows.

The arrays returned by list*->array are always strict.

procedure

(array->list* arr) → (Listof* A)

  arr : (Array A)
The inverse of list*->array.

procedure

(vector*->array vecs pred?) → (Mutable-Array A)

  vecs : (Vectorof* A)
  pred? : ((Vectorof* A) -> Any : A)
Like list*->array, but accepts nested vectors of elements.

Examples:
> (vector*->array 'singleton symbol?)

- : (Mutable-Array Symbol)

(mutable-array 'singleton)

> ((inst vector*->array Byte) #(0 1 2 3) byte?)

- : (Mutable-Array Byte)

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

As in the last example, Typed Racket often needs help inferring vector*->array’s type parameters.

procedure

(array->vector* arr) → (Vectorof* A)

  arr : (Array A)
Like array->list*, but produces nested vectors of elements.

procedure

(array-list->array arrs [axis]) → (Array A)

  arrs : (Listof (Array A))
  axis : Integer = 0
Concatenates arrs along axis axis to form a new array. If the arrays have different shapes, they are broadcast first. The axis number axis must be nonnegative and no greater than the number of axes in the highest dimensional array in arrs.

Examples:
> (array-list->array (list (array 0) (array 1) (array 2) (array 3)))

- : (Array Byte)

(array #[0 1 2 3])

> (array-list->array (list (array 0) (array 1) (array 2) (array 3)) 1)

array-list->array: expected axis Index <= 0; given 1

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

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

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

> (array-list->array (list (array #[0 1 2 3]) (array '!)))

- : (Array (U '! Byte))

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

> (array-list->array (list (array #[0 1 2 3]) (array '!)) 1)

- : (Array (U '! Byte))

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

This function is a left inverse of array->array-list. (It cannot be a right inverse because broadcasting cannot be undone.)

For a similar function that does not increase the dimension of the broadcast arrays, see array-append*.

procedure

(array->array-list arr [axis]) → (Listof (Array A))

  arr : (Array A)
  axis : Integer = 0
Turns one axis of arr into a list of arrays. Each array in the result has the same shape. The axis number axis must be nonnegative and less than the number of arr’s axes.

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

- : (Listof (Array Byte))

(list (array 0) (array 1) (array 2) (array 3))

> (array->array-list (array #[#[1 2] #[10 20]]))

- : (Listof (Array Positive-Byte))

(list (array #[1 2]) (array #[10 20]))

> (array->array-list (array #[#[1 2] #[10 20]]) 1)

- : (Listof (Array Positive-Byte))

(list (array #[1 10]) (array #[2 20]))

> (array->array-list (array 10))

array->array-list: expected axis Index < 0; given 0

6.8.1 Printing

parameter

(array-custom-printer) → 
(All (A) ((Array A)
          Symbol
          Output-Port
          (U Boolean 0 1) -> Any))
(array-custom-printer print-array) → void?
  print-array : 
(All (A) ((Array A)
          Symbol
          Output-Port
          (U Boolean 0 1) -> Any))
A parameter whose value is used to print subtypes of Array.

procedure

(print-array arr name port mode) → Any

  arr : (Array A)
  name : Symbol
  port : Output-Port
  mode : (U Boolean 0 1)
Prints an array using array syntax, using name instead of 'array as the head form. This function is set as the value of array-custom-printer when math/array is first required.

Well-behaved Array subtypes do not call this function directly to print themselves. They call the current array-custom-printer:
> ((array-custom-printer)
   (array #[0 1 2 3])
   'my-cool-array
   (current-output-port)
   #t)

(my-cool-array #[0 1 2 3])

See prop:custom-write for the meaning of the port and mode arguments.

  top  ← prev  up  next →