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))
- : #(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 #[1 2 3])
> (list->array '((1 2 3) (4 5)))
- : #(struct:Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes
           (U (List One Positive-Byte Positive-Byte)
              (List Positive-Byte 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 #['(1 2 3) '(4 5)])
> (list->array #(2 2) '(1 2 3 4))
- : #(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 #[#[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))
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Integer)
       (-> Indexes Integer Void)
       (Vectorof Integer))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array #[1 2 3])
> (vector->array #((1 2 3) (4 5)))
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes
           (U (List One Positive-Byte Positive-Byte)
              (List Positive-Byte Positive-Byte)))
       (-> Indexes
           (U (List One Positive-Byte Positive-Byte)
              (List Positive-Byte Positive-Byte))
           Void)
       (Vectorof
        (U (List One Positive-Byte Positive-Byte)
           (List Positive-Byte Positive-Byte))))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array #['(1 2 3) '(4 5)])
> (vector->array #(2 2) #(1 2 3 4))
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Integer)
       (-> Indexes Integer Void)
       (Vectorof Integer))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(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?)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Symbol))
      #<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 'singleton)
> (list*->array '(0 1 2 3) byte?)
- : #(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>)
(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)))
- : #(struct:Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes (Listof Nonnegative-Real)))
      #<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>)
(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?)
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Symbol)
       (-> Indexes Symbol Void)
       (Vectorof Symbol))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array 'singleton)
> ((inst vector*->array Byte) #(0 1 2 3) byte?)
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Byte)
       (-> Indexes Byte Void)
       (Vectorof Byte))
      #<syntax:build/user/8.11.1/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(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)))
- : #(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-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])))
- : #(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-list->array (list (array #[0 1 2 3]) (array '!)))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes (U '! 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-list->array (list (array #[0 1 2 3]) (array '!)) 1)
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes (U '! 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 '!]])

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
     #(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>))
(list (array 0) (array 1) (array 2) (array 3))
> (array->array-list (array #[#[1 2] #[10 20]]))
- : (Listof
     #(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>))
(list (array #[1 2]) (array #[10 20]))
> (array->array-list (array #[#[1 2] #[10 20]]) 1)
- : (Listof
     #(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>))
(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.

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