Bracket indexing: Difference between revisions
m (Text replacement - "http://help.dyalog.com" to "https://help.dyalog.com") |
m (Text replacement - "</source>" to "</syntaxhighlight>") |
||
| (2 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{Built-in|Bracket indexing|<nowiki>[]</nowiki>}}, or simply '''Indexing''', is a special [[primitive function]] which uses the | {{Built-in|Bracket indexing|<nowiki>[]</nowiki>}}, or simply '''Indexing''', is a special [[primitive function]] which uses the postcircumfix notation <syntaxhighlight lang=apl inline>X[Y]</syntaxhighlight> instead of a normal prefix function. The result of <syntaxhighlight lang=apl inline>X[Y]</syntaxhighlight> is an array formed with items of X extracted by the [[index]] specification Y. | ||
== Indexing modes == | == Indexing modes == | ||
| Line 5: | Line 5: | ||
=== Simple indexing === | === Simple indexing === | ||
Most APL implementations support only this mode of indexing. In its simplest form, < | Most APL implementations support only this mode of indexing. In its simplest form, <syntaxhighlight lang=apl inline>X[Y]</syntaxhighlight> on vector X and scalar Y extracts the item of X at index Y. In general, Y can be an array of any shape, with each item being a valid index in X; then <syntaxhighlight lang=apl inline>X[Y]</syntaxhighlight> is a Y-shaped array which contains the indexed results. | ||
< | <syntaxhighlight lang=apl> | ||
'ABCDE'[2] | 'ABCDE'[2] | ||
B | B | ||
| Line 13: | Line 13: | ||
ABC | ABC | ||
DEA | DEA | ||
</ | </syntaxhighlight> | ||
For higher-[[rank]] array X with rank n, the notation < | For higher-[[rank]] array X with rank n, the notation <syntaxhighlight lang=apl inline>X[Y1;Y2;...;Yn]</syntaxhighlight> selects the indexes of X over each axis. If some <syntaxhighlight lang=apl inline>Yk</syntaxhighlight> is omitted, it implies all indices of k-th axis is selected, which is equivalent to specifying <syntaxhighlight lang=apl inline>⍳(⍴X)[k]</syntaxhighlight>. The resulting shape is the concatenation of shapes of Y1, Y2, ..., Yn. | ||
< | <syntaxhighlight lang=apl> | ||
⎕←A←2 3 4⍴10×⍳24 | ⎕←A←2 3 4⍴10×⍳24 | ||
10 20 30 40 | 10 20 30 40 | ||
| Line 37: | Line 37: | ||
50 60 70 80 | 50 60 70 80 | ||
170 180 190 200 | 170 180 190 200 | ||
</ | </syntaxhighlight> | ||
The major limitation of this indexing mode is that it only supports rectangular selection. For example, it is not possible to form < | The major limitation of this indexing mode is that it only supports rectangular selection. For example, it is not possible to form <syntaxhighlight lang=apl inline>X[1;1],X[2;2]</syntaxhighlight> from a matrix X by single indexing. | ||
=== Choose indexing === | === Choose indexing === | ||
| Line 45: | Line 45: | ||
In this mode, the index specification Y is a [[depth]]-2 [[nested array]]. Each item of Y is a vector whose length is the rank of X, and the result is a collection of items of X selected by each item of Y. | In this mode, the index specification Y is a [[depth]]-2 [[nested array]]. Each item of Y is a vector whose length is the rank of X, and the result is a collection of items of X selected by each item of Y. | ||
< | <syntaxhighlight lang=apl> | ||
M | M | ||
10 20 30 40 | 10 20 30 40 | ||
| Line 62: | Line 62: | ||
'Z'[3⍴⊂⍬] ⍝ Scalar X can be indexed using enclosed empty vector | 'Z'[3⍴⊂⍬] ⍝ Scalar X can be indexed using enclosed empty vector | ||
ZZZ | ZZZ | ||
</ | </syntaxhighlight> | ||
=== Reach indexing === | === Reach indexing === | ||
| Line 68: | Line 68: | ||
In this mode, Y is a depth-3 nested array. Each item of Y is a vector of nested vectors which specify the index at each level of nesting (which is equivalent to the indexing by [[Pick]]). This allows to extract multiple items from a deeply nested array with a single indexing operation. | In this mode, Y is a depth-3 nested array. Each item of Y is a vector of nested vectors which specify the index at each level of nesting (which is equivalent to the indexing by [[Pick]]). This allows to extract multiple items from a deeply nested array with a single indexing operation. | ||
< | <syntaxhighlight lang=apl> | ||
G←('ABC' 1)('DEF' 2)('GHI' 3)('JKL' 4) | G←('ABC' 1)('DEF' 2)('GHI' 3)('JKL' 4) | ||
G←2 3⍴G,('MNO' 5)('PQR' 6) | G←2 3⍴G,('MNO' 5)('PQR' 6) | ||
| Line 96: | Line 96: | ||
│└───┴─┘│ | │└───┴─┘│ | ||
└───────┘ | └───────┘ | ||
</ | </syntaxhighlight> | ||
== Implementation support == | == Implementation support == | ||
Latest revision as of 22:28, 10 September 2022
[]
|
Bracket indexing ([]), or simply Indexing, is a special primitive function which uses the postcircumfix notation X[Y] instead of a normal prefix function. The result of X[Y] is an array formed with items of X extracted by the index specification Y.
Indexing modes
Simple indexing
Most APL implementations support only this mode of indexing. In its simplest form, X[Y] on vector X and scalar Y extracts the item of X at index Y. In general, Y can be an array of any shape, with each item being a valid index in X; then X[Y] is a Y-shaped array which contains the indexed results.
'ABCDE'[2]
B
'ABCDE'[2 3⍴1 2 3 4 5 1]
ABC
DEA
For higher-rank array X with rank n, the notation X[Y1;Y2;...;Yn] selects the indexes of X over each axis. If some Yk is omitted, it implies all indices of k-th axis is selected, which is equivalent to specifying ⍳(⍴X)[k]. The resulting shape is the concatenation of shapes of Y1, Y2, ..., Yn.
⎕←A←2 3 4⍴10×⍳24
10 20 30 40
50 60 70 80
90 100 110 120
130 140 150 160
170 180 190 200
210 220 230 240
A[1;1;1]
10
A[2;3 2;4 1]
240 210
200 170
A[;2;]
50 60 70 80
170 180 190 200
The major limitation of this indexing mode is that it only supports rectangular selection. For example, it is not possible to form X[1;1],X[2;2] from a matrix X by single indexing.
Choose indexing
In this mode, the index specification Y is a depth-2 nested array. Each item of Y is a vector whose length is the rank of X, and the result is a collection of items of X selected by each item of Y.
M
10 20 30 40
50 60 70 80
M[⊂1 2]
20
M[2 2⍴⊂2 4]
80 80
80 80
M[(2 1)(1 2)]
50 20
'Z'[3⍴⊂⍬] ⍝ Scalar X can be indexed using enclosed empty vector
ZZZ
Reach indexing
In this mode, Y is a depth-3 nested array. Each item of Y is a vector of nested vectors which specify the index at each level of nesting (which is equivalent to the indexing by Pick). This allows to extract multiple items from a deeply nested array with a single indexing operation.
G←('ABC' 1)('DEF' 2)('GHI' 3)('JKL' 4)
G←2 3⍴G,('MNO' 5)('PQR' 6)
G
┌───────┬───────┬───────┐
│┌───┬─┐│┌───┬─┐│┌───┬─┐│
││ABC│1│││DEF│2│││GHI│3││
│└───┴─┘│└───┴─┘│└───┴─┘│
├───────┼───────┼───────┤
│┌───┬─┐│┌───┬─┐│┌───┬─┐│
││JKL│4│││MNO│5│││PQR│6││
│└───┴─┘│└───┴─┘│└───┴─┘│
└───────┴───────┴───────┘
G[((1 2)1)((2 3)2)]
┌───┬─┐
│DEF│6│
└───┴─┘
G[2 2⍴⊂(2 2)2]
5 5
5 5
G[⊂⊂1 1]
┌───────┐
│┌───┬─┐│
││ABC│1││
│└───┴─┘│
└───────┘
Implementation support
Dyalog APL and NARS2000 support all three modes of indexing. NARS2000 even supports mixing Choose and Reach indexing modes. J does not have this notation at all.
See also
External links
Documentation