6.8 Conversion

► |  | Math Library

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 | Arrays

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

► | 6.8 | Conversion

6.8.1 | Printing

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 contents ← 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))
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Byte))
> #<syntax:build/user/8.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/8.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/8.17/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.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/8.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/8.17/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.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/8.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/8.17/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.17/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.17/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.17/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.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/8.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/8.17/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.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/8.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/8.17/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.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/8.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/8.17/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.17/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.17/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.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/8.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/8.17/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.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/8.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/8.17/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.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/8.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/8.17/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.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:build/user/8.17/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:build/user/8.17/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:.../array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:.../array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:.../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:.../array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:.../array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:.../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:.../array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:.../array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:.../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.
top contents ← prev up next →