Indexing

This page is about the concept of extracting items from an array. See Index for the concept of a location in an array. See Bracket indexing, Index (function), Pick, and Select for the primitives designed for indexing.

In the APL array model, indexing refers to the operation of extracting one or more elements from an array based on some specification of indices. All indexing operations are subject to index origin in languages which have such a concept.

Rectangular indexing

Rectangular indexing selects indices along each axis of a given array. This indexing mode is usually implemented as Bracket indexing <source lang=apl inline>X[Y]</syntaxhighlight> and Squad indexing <source lang=apl inline>Y⌷X</syntaxhighlight>. Rectangular indexing has an important property: If rectangular indexing is applied to a matrix, the elements at four corners of a rectangle still form a rectangle in the result. This property generalizes to four elements of a higher-rank array for that share an index over all but two axes.

<source lang=apl>

     ⎕←mat←10⊥¨⍳3 4

11 12 13 14 21 22 23 24 31 32 33 34

     mat[1 1 2;]

11 12 13 14 11 12 13 14 21 22 23 24

     mat[2 3;1 4]

21 24 31 34 </syntaxhighlight>

Relationship to leading axis theory

For implementations that support leading axis theory, it is common to select cells or especially major cells of an array. In these implementations, Squad can be used with short left argument so that the omitted trailing axes can be selected as-is. A few implementations also support Select, the primitive dedicated to selecting major cells.

<source lang=apl>

     (⊂1 1 2)⌷mat

11 12 13 14 11 12 13 14 21 22 23 24 </syntaxhighlight>

Replicate as a special case

Various forms of Replicate can be used to select one or more indices over a single axis. <source lang=apl inline>X/Y</syntaxhighlight> applies to the last axis, <source lang=apl inline>X⌿Y</syntaxhighlight> to the first, and <source lang=apl inline>X/[K]Y</syntaxhighlight> applies to the K-th axis. All the other axes are kept intact. The main difference from other indexing primitives is that X does not specify the indices; instead, it specifies how many copies of the corresponding indices to include in the result.

<source lang=apl>

     2 1 0⌿mat

11 12 13 14 11 12 13 14 21 22 23 24 </syntaxhighlight>

Non-rectangular indexing

Non-rectangular indexing selects multi-dimensional indices from the entire array. This only works with nested array model because the index specification must contain vectors as its elements. A few APL implementations support this form of indexing as a mode of Bracket indexing.

<source lang=apl>

     mat[2 2⍴(1 1)(2 2)(1 3)(2 4)]

11 22 13 24 </syntaxhighlight>

Deep indexing

In nested array model, a need to access items through layers of nesting arises. Deep indexing uses a vector of indices over multiple layers to fetch a deeply nested item. This mode of indexing is supported by Pick, and as a mode of Bracket indexing in a few implementations.

<source lang=apl>

     ⎕←G←2 3⍴('ABC' 1)('DEF' 2)('GHI' 3)('JKL' 4)('MNO' 5)('PQR' 6)

┌───────┬───────┬───────┐ │┌───┬─┐│┌───┬─┐│┌───┬─┐│ ││ABC│1│││DEF│2│││GHI│3││ │└───┴─┘│└───┴─┘│└───┴─┘│ ├───────┼───────┼───────┤ │┌───┬─┐│┌───┬─┐│┌───┬─┐│ ││JKL│4│││MNO│5│││PQR│6││ │└───┴─┘│└───┴─┘│└───┴─┘│ └───────┴───────┴───────┘

     ((2 1)1)⊃G

JKL

     ((2 1)1 2)⊃G

K </syntaxhighlight>