Index: Difference between revisions

From APL Wiki
Jump to navigation Jump to search
m (Text replacement - "</source>" to "</syntaxhighlight>")
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
:''This page is about the array theory concept. See [[Indexing]], [[Indices]], [[Index Generator]], [[Index of]], and [[Interval Index]] for operations named after indices.''
:''This page is about the array theory concept. See [[Index (function)]], [[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.
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.
Line 8: Line 8:


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
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
<source lang=apl>
<syntaxhighlight lang=apl>
(⍴i) ≡ ⍴⍴A
(⍴i) ≡ ⍴⍴A
∧/ (⎕IO≤i) ∧ (i<(⍴A)-⎕IO)
∧/ (⎕IO≤i) ∧ (i<(⍴A)-⎕IO)
</source>
</syntaxhighlight>
to describe the possible indices <source lang=apl inline>i</source> for an array <source lang=apl inline>A</source>.
to describe the possible indices <syntaxhighlight lang=apl inline>i</syntaxhighlight> for an array <syntaxhighlight lang=apl inline>A</syntaxhighlight>.


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 <source lang=apl inline>i</source> is the sole element of [[scalar]] <source lang=apl inline>i⌷A</source>.
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 <syntaxhighlight lang=apl inline>i</syntaxhighlight> is the sole element of [[scalar]] <syntaxhighlight lang=apl inline>i⌷A</syntaxhighlight>.


When indexing into a [[scalar]] array, there is only one valid index: the [[empty]] numeric vector <source lang=apl inline>⍴0</source>, or [[Zilde]]. There are no valid indices for an [[empty]] array, because it has no elements.
When indexing into a [[scalar]] array, there is only one valid index: the [[empty]] numeric vector <syntaxhighlight lang=apl inline>⍴0</syntaxhighlight>, or [[Zilde]]. There are no valid indices for an [[empty]] array, because it has no elements.


=== Index of an axis ===
=== Index of an axis ===
Line 22: Line 22:
The indices and [[shape]] of an array both contain one element for each axis. Because these objects are [[vector]]s, 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]].
The indices and [[shape]] of an array both contain one element for each axis. Because these objects are [[vector]]s, 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 <source lang=apl inline>⎕IO-1</source> and <source lang=apl inline>⎕IO+r</source> for an array of [[rank]] <source lang=apl inline>r</source>. For a specified axis <source lang=apl inline>i</source>, the axis will be inserted between axes <source lang=apl inline>⌊i</source> and <source lang=apl inline>⌈i</source>, or before every axis if <source lang=apl inline>⌊i</source> is not a valid axis and after every axis if <source lang=apl inline>⌈i</source> is not a valid axis (for an [[empty array]], both exceptions hold).
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 <syntaxhighlight lang=apl inline>⎕IO-1</syntaxhighlight> and <syntaxhighlight lang=apl inline>⎕IO+r</syntaxhighlight> for an array of [[rank]] <syntaxhighlight lang=apl inline>r</syntaxhighlight>. For a specified axis <syntaxhighlight lang=apl inline>i</syntaxhighlight>, the axis will be inserted between axes <syntaxhighlight lang=apl inline>⌊i</syntaxhighlight> and <syntaxhighlight lang=apl inline>⌈i</syntaxhighlight>, or before every axis if <syntaxhighlight lang=apl inline>⌊i</syntaxhighlight> is not a valid axis and after every axis if <syntaxhighlight lang=apl inline>⌈i</syntaxhighlight> is not a valid axis (for an [[empty array]], both exceptions hold).


=== Ravel index ===
=== Ravel index ===


The [[ravel]] of an array can be used to define another kind of index selecting one of its [[element]]s. 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 <source lang=apl inline>r⌷A</source> {{←→}} <source lang=apl inline>i⌷,A</source> where <source lang=apl inline>r</source> is the ravel index and <source lang=apl inline>i</source> the ordinary index of an element in <source lang=apl inline>A</source>. Using [[Encode]] and [[Decode]] we may write <source lang=apl inline>r</source> {{←→}} <source lang=apl inline>(⍴A)⊥i</source> and <source lang=apl inline>i</source> {{←→}} <source lang=apl inline>(⍴A)⊤r</source> assuming index origin 0.
The [[ravel]] of an array can be used to define another kind of index selecting one of its [[element]]s. 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 <syntaxhighlight lang=apl inline>r⌷A</syntaxhighlight> {{←→}} <syntaxhighlight lang=apl inline>i⌷,A</syntaxhighlight> where <syntaxhighlight lang=apl inline>r</syntaxhighlight> is the ravel index and <syntaxhighlight lang=apl inline>i</syntaxhighlight> the ordinary index of an element in <syntaxhighlight lang=apl inline>A</syntaxhighlight>. Using [[Encode]] and [[Decode]] we may write <syntaxhighlight lang=apl inline>r</syntaxhighlight> {{←→}} <syntaxhighlight lang=apl inline>(⍴A)⊥i</syntaxhighlight> and <syntaxhighlight lang=apl inline>i</syntaxhighlight> {{←→}} <syntaxhighlight lang=apl inline>(⍴A)⊤r</syntaxhighlight> assuming index origin 0.


The correspondence between indices and ravel indices is governed by [[ravel order]]. For more information, see [[Axis ordering]].
The correspondence between indices and ravel indices is governed by [[ravel order]]. For more information, see [[Axis ordering]].

Latest revision as of 22:05, 10 September 2022

This page is about the array theory concept. See Index (function), 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.

Element index

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 A.

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 i⌷A.

When indexing into a scalar array, there is only one valid index: the empty numeric vector ⍴0, or Zilde. There are no valid indices for an empty array, because it has no elements.

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-1 and ⎕IO+r for an array of rank r. For a specified axis i, the axis will be inserted between axes ⌊i and ⌈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).

Ravel index

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⌷A i⌷,A where r is the ravel index and i the ordinary index of an element in A. Using Encode and Decode we may write r (⍴A)⊥i and i (⍴A)⊤r assuming index origin 0.

The correspondence between indices and ravel indices is governed by ravel order. For more information, see Axis ordering.

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.

External links


APL features [edit]
Built-ins Primitives (functions, operators) ∙ Quad name
Array model ShapeRankDepthBoundIndex (Indexing) ∙ AxisRavelRavel orderElementScalarVectorMatrixSimple scalarSimple arrayNested arrayCellMajor cellSubarrayEmpty arrayPrototype
Data types Number (Boolean, Complex number) ∙ Character (String) ∙ BoxNamespaceFunction array
Concepts and paradigms Conformability (Scalar extension, Leading axis agreement) ∙ Scalar function (Pervasion) ∙ Identity elementComplex floorArray ordering (Total) ∙ Tacit programming (Function composition, Close composition) ∙ GlyphLeading axis theoryMajor cell search
Errors LIMIT ERRORRANK ERRORSYNTAX ERRORDOMAIN ERRORLENGTH ERRORINDEX ERRORVALUE ERROREVOLUTION ERROR