6.6 Types, Predicates and Accessors

syntax
(Array A)

The parent array type. Its type parameter is the type of the array’s elements.

The polymorphic Array type is covariant, meaning that (Array A) is a subtype of (Array B) if A is a subtype of B:

> (define arr (array #[1 2 3 4 5]))
> arr
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Byte))
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[1 2 3 4 5])
> (ann arr (Array Real))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Real))
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[1 2 3 4 5])
> (ann arr (Array Any))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Any))
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[1 2 3 4 5])

Because subtyping is transitive, the (Array A) in the preceeding subtyping rule can be replaced with any of (Array A)’s subtypes, including descendant types of Array. For example, (Mutable-Array A) is a subtype of (Array B) if A is a subtype of B:

> (define arr (mutable-array #[1 2 3 4 5]))
> arr
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Integer)
       (-> Indexes Integer Void)
       (Vectorof Integer))
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array #[1 2 3 4 5])
> (ann arr (Array Real))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Real))
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(mutable-array #[1 2 3 4 5])
> (ann arr (Array Any))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Any))
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(mutable-array #[1 2 3 4 5])

syntax
(Settable-Array A)

The parent type of arrays whose elements can be mutated. Functions like array-set! and array-slice-set! accept arguments of this type. Examples of subtypes are Mutable-Array, FlArray and FCArray.

This type is invariant, meaning that (Settable-Array A) is not a subtype of (Settable-Array B) if A and B are different types, even if A is a subtype of B:

> (define arr (mutable-array #[1 2 3 4 5]))
> arr
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Integer)
       (-> Indexes Integer Void)
       (Vectorof Integer))
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array #[1 2 3 4 5])
> (ann arr (Settable-Array Integer))
- : #(struct:Settable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Integer)
       (-> Indexes Integer Void)))
(mutable-array #[1 2 3 4 5])
> (ann arr (Settable-Array Real))
eval:93:0: Type Checker: type mismatch
  expected: #(struct:Settable-Array
              (Indexes
               Index
               (Boxof Boolean)
               (-> Void)
               (-> Indexes Real)
               (-> Indexes Real Void)))
  given: #(struct:Mutable-Array
           (Indexes
            Index
            (Boxof Boolean)
            (-> Void)
            (-> Indexes Integer)
            (-> Indexes Integer Void)
            (Vectorof Integer))
           #<syntax:build/user/8.5/pkgs/math-lib/math/privat
e/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
  in: Real

syntax
(Mutable-Array A)

The type of mutable arrays. Its type parameter is the type of the array’s elements.

Arrays of this type store their elements in a (Vectorof A):

> (define arr (mutable-array #[#[1 2] #[3 4]]))
> (vector-set! (mutable-array-data arr) 0 -10)
> arr
- : #(struct:Mutable-Array
      (Indexes
       Index
       (Boxof Boolean)
       (-> Void)
       (-> Indexes Integer)
       (-> Indexes Integer Void)
       (Vectorof Integer))
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
(mutable-array #[#[-10 2] #[3 4]])

Mutable arrays are always strict.

syntax
Indexes

The type of array shapes and array indexes produced by math/array functions. Defined as (Vectorof Index).

Example:

> (array-shape (array #[#[#[0]]]))
- : Indexes
'#(1 1 1)

syntax
In-Indexes

The type of array shapes and array indexes accepted by math/array functions. Defined as (U Indexes (Vectorof Integer)).

Examples:

> (define ds #(3 2))
> ds
- : (Immutable-Vector Positive-Byte Positive-Byte)
'#(3 2)
> (make-array ds (void))
- : #(struct:Array
      (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Void))
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
      #<syntax:build/user/8.5/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
(array #[#[#<void> #<void>] #[#<void> #<void>] #[#<void> #<void>]])

This makes indexes-accepting functions easier to use, because it is easier to convince Typed Racket that a vector contains Integer elements than that a vector contains Index elements.

In-Indexes is not defined as (Vectorof Integer) because mutable container types like Vector and Vectorof are invariant. In particular, (Vectorof Index) is not a subtype of (Vectorof Integer):

> (define js ((inst vector Index) 3 4 5))
> js
- : (Mutable-Vectorof Index)
'#(3 4 5)
> (ann js (Vectorof Integer))
eval:103:0: Type Checker: type mismatch
  expected: (Vectorof Integer)
  given: (Mutable-Vectorof Index)
  in: Integer
> (ann js In-Indexes)
- : In-Indexes
'#(3 4 5)

procedure
(array? v) → Boolean
  v : Any
procedure
(settable-array? v) → Boolean
  v : Any
procedure
(mutable-array? v) → Boolean
  v : Any

Predicates for the types Array, Settable-Array, and Mutable-Array.

Because Settable-Array and its descendants are invariant, settable-array? and its descendants’ predicates are generally not useful in occurrence typing. For example, if we know we have an Array but would like to treat it differently if it happens to be a Mutable-Array, we are basically out of luck:

> (: maybe-array-data (All (A) ((Array A) -> (U #f (Vectorof A)))))
> (define (maybe-array-data arr)
    (cond [(mutable-array? arr)  (mutable-array-data arr)]
          [else  #f]))
eval:106:0: Type Checker: Polymorphic function
`mutable-array-data' could not be applied to arguments:
Argument 1:
  Expected: (Mutable-Array A)
  Given:    (Struct Mutable-Array)
  in: #f

In general, predicates with a Struct filter do not give conditional branches access to a struct’s accessors. Because Settable-Array and its descendants are invariant, their predicates have Struct filters:

> array?
- : (-> Any Boolean : (Array Any))
#<procedure:Array?>
> settable-array?
- : (-> Any Boolean : (Struct Settable-Array))
#<procedure:Settable-Array?>
> mutable-array?
- : (-> Any Boolean : (Struct Mutable-Array))
#<procedure:Mutable-Array?>

procedure
(array-shape arr) → Indexes
arr : (Array A)

Returns arr’s shape, a vector of indexes that contains the lengths of arr’s axes.

Examples:

> (array-shape (array 0))
- : Indexes
'#()
> (array-shape (array #[0 1]))
- : Indexes
'#(2)
> (array-shape (array #[#[0 1]]))
- : Indexes
'#(1 2)
> (array-shape (array #[]))
- : Indexes
'#(0)

procedure
(array-size arr) → Index
arr : (Array A)

Returns the number of elements in arr, which is the product of its axis lengths.

Examples:

> (array-size (array 0))
- : Integer [more precisely: Index]
1
> (array-size (array #[0 1]))
- : Integer [more precisely: Index]
2
> (array-size (array #[#[0 1]]))
- : Integer [more precisely: Index]
2
> (array-size (array #[]))
- : Integer [more precisely: Index]
0

procedure
(array-dims arr) → Index
arr : (Array A)

Returns the number of arr’s dimensions. Equivalent to (vector-length (array-shape arr)).

procedure
(mutable-array-data arr) → (Vectorof A)
arr : (Mutable-Array A)

Returns the vector of data that arr contains.

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