Indexing

From APL Wiki
Jump to navigation Jump to search
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 X[Y] and Squad indexing YX. 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.

      mat10¨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

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.

      (1 1 2)mat
11 12 13 14
11 12 13 14
21 22 23 24

Replicate as a special case

Various forms of Replicate can be used to select one or more indices over a single axis. X/Y applies to the last axis, XY to the first, and X/[K]Y 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.

      2 1 0mat
11 12 13 14
11 12 13 14
21 22 23 24

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.

      mat[2 2(1 1)(2 2)(1 3)(2 4)]
11 22
13 24

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.

      G2 3('ABC' 1)('DEF' 2)('GHI' 3)('JKL' 4)('MNO' 5)('PQR' 6)
┌───────┬───────┬───────┐
│┌───┬─┐│┌───┬─┐│┌───┬─┐│
││ABC1│││DEF2│││GHI3││
│└───┴─┘│└───┴─┘│└───┴─┘│
├───────┼───────┼───────┤
│┌───┬─┐│┌───┬─┐│┌───┬─┐│
││JKL4│││MNO5│││PQR6││
│└───┴─┘│└───┴─┘│└───┴─┘│
└───────┴───────┴───────┘
      ((2 1)1)G
JKL
      ((2 1)1 2)G
K


APL features [edit]
Built-ins Primitive functionPrimitive operatorQuad name
Array model ShapeRankDepthBoundIndex (Indexing) ∙ AxisRavelRavel orderElementScalarVectorMatrixSimple scalarSimple arrayNested arrayCellMajor cellSubarrayEmpty arrayPrototype
Data types Number (Boolean, Complex number) ∙ Character (String) ∙ BoxNamespace
Concepts and paradigms Leading axis theoryScalar extensionConformabilityScalar functionPervasionGlyphIdentity elementComplex floorTotal array ordering
Errors LIMIT ERRORRANK ERRORSYNTAX ERRORDOMAIN ERRORLENGTH ERRORINDEX ERRORVALUE ERROR