6.11 Indexing and Slicing

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

On this page:

array-ref
array-set!
array-indexes-ref
array-indexes-set!
array-slice-ref
array-slice-set!
Slice-Spec
Slice
: :
slice?
slice-start
slice-end
slice-step
slice->range-values
Slice-Dots
: : ...
slice-dots?
Slice-New-Axis
: : new
slice-new-axis?
slice-new-axis-length

top contents ← prev up next →

#### 6.11`` Indexing and Slicing🔗ℹ

> procedure (array-ref arr js) → A
> arr : (Array A)
> js : In-Indexes

Returns the element of arr at position js. If any index in js is negative or not less than its corresponding axis length, array-ref raises an error.

> procedure (array-set! arr js value) → Void
> arr : (Settable-Array A)
> js : In-Indexes
> value : A

Sets the element of arr at position js to value. If any index in js is negative or not less than its corresponding axis length, array-set! raises an error.

> procedure (array-indexes-ref arr idxs) → (Array A)
> arr : (Array A)
> idxs : (Array In-Indexes)

High-level explanation: Returns multiple elements from arr in a new array.

Lower-level explanation: Returns an array with same shape as idxs, whose elements are array-ref’d from arr using the indexes in idxs.

Examples:

> > (define arr (array #[#[1 2] #[10 20]]))
> > (define idxs (array #['#(0 0) '#(1 1)]))
> > (array-indexes-ref arr idxs)
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Byte))
> #<syntax:/usr/src/packages/BUILD/racket/src/racket-8.17/share/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:/usr/src/packages/BUILD/racket/src/racket-8.17/share/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:/usr/src/packages/BUILD/racket/src/racket-8.17/share/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[1 20])

Implementation-level explanation: (array-indexes-ref arr idxs) is equivalent to

> > (build-array (array-shape idxs)
> (λ: ([js : Indexes])
> (array-ref arr (array-ref idxs js))))
> - : #(struct:Array
> (Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Byte))
> #<syntax:/usr/src/packages/BUILD/racket/src/racket-8.17/share/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>
> #<syntax:/usr/src/packages/BUILD/racket/src/racket-8.17/share/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>
> #<syntax:/usr/src/packages/BUILD/racket/src/racket-8.17/share/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)
> (array #[1 20])

but faster.

> procedure (array-indexes-set! arr idxs vals) → Void
> arr : (Settable-Array A)
> idxs : (Array In-Indexes)
> vals : (Array A)

Indexes arr in the same way that array-indexes-ref does, but mutates elements. If idxs and vals do not have the same shape, they are broadcast first.

Examples:

> > (define arr (mutable-array #[#[1 2] #[10 20]]))
> > (define idxs (array #['#(0 0) '#(1 1)]))
> > (array-indexes-set! arr idxs (array -1))
> > arr
> - : #(struct:Mutable-Array
> (Indexes
> Index
> (Boxof Boolean)
> (-> Void)
> (-> Indexes Integer)
> (-> Indexes Integer Void)
> (Vectorof Integer))
> #<syntax:/usr/src/packages/BUILD/racket/src/racket-8.17/share/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
> (mutable-array #[#[-1 2] #[10 -1]])

When two indexes in idxs are the same, the element at that index is mutated more than once in some unspecified order.

> procedure (array-slice-ref arr specs) → (Array A)
> arr : (Array A)
> specs : (Listof Slice-Spec)

Returns a transformation of arr according to the list of slice specifications specs. See Slicing for a discussion and examples.

> procedure (array-slice-set! arr specs vals) → Void
> arr : (Settable-Array A)
> specs : (Listof Slice-Spec)
> vals : (Array A)

Like array-indexes-set!, but for slice specifications. Equivalent to

> (let ([idxs (array-slice-ref (indexes-array (array-shape arr)) specs)])
> (array-indexes-set! arr idxs vals))

Examples:

> > (define arr (array->mutable-array (axis-index-array #(5 5) 1)))
> > (array-slice-set! arr (list (:: 1 #f 2) (::)) (array 1))
> > arr
> - : #(struct:Mutable-Array
> (Indexes
> Index
> (Boxof Boolean)
> (-> Void)
> (-> Indexes Integer)
> (-> Indexes Integer Void)
> (Vectorof Integer))
> #<syntax:/usr/src/packages/BUILD/racket/src/racket-8.17/share/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
> (mutable-array
> #[#[0 1 2 3 4]
> #[1 1 1 1 1]
> #[0 1 2 3 4]
> #[1 1 1 1 1]
> #[0 1 2 3 4]])
> > (array-slice-set!
> arr (list (::) (:: 1 #f 2))
> (array-scale (array-slice-ref arr (list (::) (:: 1 #f 2))) -1))
> > arr
> - : #(struct:Mutable-Array
> (Indexes
> Index
> (Boxof Boolean)
> (-> Void)
> (-> Indexes Integer)
> (-> Indexes Integer Void)
> (Vectorof Integer))
> #<syntax:/usr/src/packages/BUILD/racket/src/racket-8.17/share/pkgs/math-lib/math/private/array/typed-mutable-array.rkt:14:13 prop:custom-write>)
> (mutable-array
> #[#[0 -1 2 -3 4]
> #[1 -1 1 -1 1]
> #[0 -1 2 -3 4]
> #[1 -1 1 -1 1]
> #[0 -1 2 -3 4]])

When a slice specification refers to an element in arr more than once, the element is mutated more than once in some unspecified order.

> syntax Slice-Spec

The type of a slice specification. Currently defined as

> (U (Sequenceof Integer) Slice Slice-Dots Integer Slice-New-Axis)

A (Sequenceof Integer) slice specification causes array-slice-ref to pick rows from an axis. An Integer slice specification causes array-slice-ref to remove an axis by replacing it with one of its rows.

See Slicing for an extended example.

> syntax Slice
> procedure (:: [end]) → Slice
> end : (U #f Integer) = #f
> (:: start end [step]) → Slice
> start : (U #f Integer)
> end : (U #f Integer)
> step : Integer = 1
> procedure (slice? v) → Boolean
> v : Any
> procedure (slice-start s) → (U #f Fixnum)
> s : Slice
> procedure (slice-end s) → (U #f Fixnum)
> s : Slice
> procedure (slice-step s) → Fixnum
> s : Slice

The type of in-range-like slice specifications, its constructor, predicate, and accessors.

array-slice-ref interprets a Slice like an in-range sequence object. When start or end is #f, it is interpreted as an axis-length-dependent endpoint.

> procedure (slice->range-values s dk) → (Values Fixnum Fixnum Fixnum)
> s : Slice
> dk : Index

Given a slice s and an axis length dk, returns the arguments to in-range that would produce an equivalent slice specification.

This is used internally by array-slice-ref to interpret a Slice object as a sequence of indexes.

> syntax Slice-Dots
> value ::... : Slice-Dots
> procedure (slice-dots? v) → Boolean
> v : Any

The type of greedy, multiple-axis-preserving slice specifications, its singleton value, and predicate.

> syntax Slice-New-Axis
> procedure (::new [dk]) → Slice-New-Axis
> dk : Integer = 1
> procedure (slice-new-axis? v) → Boolean
> v : Any
> procedure (slice-new-axis-length s) → Index
> s : Slice-New-Axis

The type of slice specifications that indicate inserting a new axis, its constructor, predicate, and accessor. The axis length dk must be nonnegative.
top contents ← prev up next →