- This page is about the array theory concept. See Indexing, Indices, Index Generator, Index of, and Interval Index for operations named after indices.
In the APL array model, an index is a vector of integers which indicates an element of an array. The term "index" may also refer to a scalar index along an axis, or (particularly in leading axis theory) the index of a cell. Indices are subject to index origin in languages which have such a concept.
The correspondence between indices and elements of an array is one of the foundational concepts of APL. The indices for an array encapsulate its multidimensional structure by defining its axes, and also define the ordering within each axis. One definition of an array is simply a map (function) which specifies an element for each index, where the possible indices are determined by the array's shape.
An index is a vector of integers each of which is greater than or equal to the index origin. For a particular array, the index of an element has length equal to that array's rank, and it is less than the array's shape plus the index origin in every element. In APL we can write
(⍴i) ≡ ⍴⍴A ∧/ (⎕IO≤i) ∧ (i<(⍴A)-⎕IO)
to describe the possible indices
i for an array
The elements of an array then correspond one-to-one with valid indices for that array (while two elements may have the same value as arrays, they are still considered to be different elements). Using Squad indexing, the element at index
i is the sole element of scalar
Index of an axis
The indices and shape of an array both contain one element for each axis. Because these objects are vectors, each has an element ordering and indices of its own. These indices are called axis indices, and in addition to their implicit use in ordering the shape and index vectors, they are also used directly to refer to axes, for example in dyadic Transpose and when specifying a function axis.
In some cases, such as Laminate, function axis may allow a non-integer value. Such a value indicates an axis that exists in the result but not in the argument. It must lie strictly between
⎕IO+r for an array of rank
r. For a specified axis
i, the axis will be inserted between axes
⌈i, or before every axis if
⌊i is not a valid axis and after every axis if
⌈i is not a valid axis (for an empty array, both exceptions hold).
The ravel of an array can be used to define another kind of index selecting one of its elements. The ravel index is a scalar (although it could equivalently be defined as a singleton vector) which corresponds to an ordinary index by the relation
r is the ravel index and
i the ordinary index of an element in
A. Using Encode and Decode we may write
(⍴A)⊤r assuming index origin 0.
Index along an axis
Each of the values in an index corresponds to one axis of the indexed array. When considered in isolation, one of these values (a scalar number) is called an index along the corresponding axis. Selecting from the array using this index produces an array whose rank is one smaller than the initial array (and it cannot be done to a scalar, as there are no axes along which to index). This array is sometimes called a "slice" or hyperplane of the array. Selecting on the first axis gives a major cell, one kind of hyperplane.
The set of possible indices into an array as a whole is the cartesian product of the possible indices into each axis.
Index of a cell
In leading axis theory an array's shape may be split in two with leading axes forming the frame and trailing axes forming the shape of each cell. A vector of indices for the axes in the frame only selects a cell of the array. Squad indexing supports this kind of selection using a short simple left argument. Using a frame with the same length as that argument, the given indices correspond to leading axes of the right argument—the ones in the frame—and those axes are not present in the result. All the indices into a cell, corresponding to trailing axes, are implicit, and those axes are unchanged.
|APL features |
|Built-ins||Primitive function ∙ Primitive operator ∙ Quad name|
|Array model||Shape ∙ Rank ∙ Depth ∙ Bound ∙ Index (Indexing) ∙ Axis ∙ Ravel ∙ Ravel order ∙ Element ∙ Scalar ∙ Vector ∙ Matrix ∙ Simple scalar ∙ Simple array ∙ Nested array ∙ Cell ∙ Major cell ∙ Subarray ∙ Empty array ∙ Prototype|
|Data types||Number (Boolean, Complex number) ∙ Character (String) ∙ Box ∙ Namespace|
|Concepts and paradigms||Leading axis theory ∙ Scalar extension ∙ Conformability ∙ Leading axis agreement ∙ Scalar function ∙ Pervasion ∙ Glyph ∙ Identity element ∙ Complex floor ∙ Total array ordering|
|Errors||LIMIT ERROR ∙ RANK ERROR ∙ SYNTAX ERROR ∙ DOMAIN ERROR ∙ LENGTH ERROR ∙ INDEX ERROR ∙ VALUE ERROR|