Bracket indexing: Difference between revisions

From APL Wiki
Jump to navigation Jump to search
m (Text replacement - "<source" to "<syntaxhighlight")
m (Text replacement - "</source>" to "</syntaxhighlight>")
 
Line 1: Line 1:
{{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]</source> instead of a normal prefix function. The result of <syntaxhighlight lang=apl inline>X[Y]</source> is an array formed with items of X extracted by the [[index]] specification Y.
{{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, <syntaxhighlight lang=apl inline>X[Y]</source> 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]</source> is a Y-shaped array which contains the indexed results.
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>
<syntaxhighlight lang=apl>
Line 13: Line 13:
ABC
ABC
DEA
DEA
</source>
</syntaxhighlight>


For higher-[[rank]] array X with rank n, the notation <syntaxhighlight lang=apl inline>X[Y1;Y2;...;Yn]</source> selects the indexes of X over each axis. If some <syntaxhighlight lang=apl inline>Yk</source> is omitted, it implies all indices of k-th axis is selected, which is equivalent to specifying <syntaxhighlight lang=apl inline>⍳(⍴X)[k]</source>. The resulting shape is the concatenation of shapes of Y1, Y2, ..., Yn.
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>
<syntaxhighlight lang=apl>
Line 37: Line 37:
  50  60  70  80
  50  60  70  80
170 180 190 200
170 180 190 200
</source>
</syntaxhighlight>


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]</source> from a matrix X by single indexing.
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 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
</source>
</syntaxhighlight>


=== Reach indexing ===
=== Reach indexing ===
Line 96: Line 96:
│└───┴─┘│
│└───┴─┘│
└───────┘
└───────┘
</source>
</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 31 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.

      A2 3 410×⍳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)
      G2 3G,('MNO' 5)('PQR' 6)
      G
┌───────┬───────┬───────┐
│┌───┬─┐│┌───┬─┐│┌───┬─┐│
││ABC1│││DEF2│││GHI3││
│└───┴─┘│└───┴─┘│└───┴─┘│
├───────┼───────┼───────┤
│┌───┬─┐│┌───┬─┐│┌───┬─┐│
││JKL4│││MNO5│││PQR6││
│└───┴─┘│└───┴─┘│└───┴─┘│
└───────┴───────┴───────┘
 
      G[((1 2)1)((2 3)2)]
┌───┬─┐
DEF6
└───┴─┘
 
      G[2 2⍴⊂(2 2)2]
5 5
5 5
      G[⊂⊂1 1]
┌───────┐
│┌───┬─┐│
││ABC1││
│└───┴─┘│
└───────┘

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


APL built-ins [edit]
Primitive functions
Scalar
Monadic ConjugateNegateSignumReciprocalMagnitudeExponentialNatural LogarithmFloorCeilingFactorialNotPi TimesRollTypeImaginarySquare Root
Dyadic AddSubtractTimesDivideResiduePowerLogarithmMinimumMaximumBinomialComparison functionsBoolean functions (And, Or, Nand, Nor) ∙ GCDLCMCircularComplexRoot
Non-Scalar
Structural ShapeReshapeTallyDepthRavelEnlistTableCatenateReverseRotateTransposeRazeMixSplitEncloseNestCut (K)PairLinkPartitioned EnclosePartition
Selection FirstPickTakeDropUniqueIdentitySelectReplicateExpandSet functions (IntersectionUnionWithout) ∙ Bracket indexingIndex
Selector Index generatorGradeIndex OfInterval IndexIndicesDeal
Computational MatchNot MatchMembershipFindNub SieveEncodeDecodeMatrix InverseMatrix DivideFormatExecuteMaterialiseRange
Primitive operators Monadic EachCommuteConstantReplicateExpandReduceWindowed ReduceScanOuter ProductKeyI-BeamSpawnFunction axis
Dyadic BindCompositions (Compose, Reverse Compose, Beside, Withe, Atop, Over) ∙ Inner ProductPowerAtUnderRankDepthVariantStencilCut (J)
Quad names
Arrays Index originMigration levelAtomic vector
Functions Name classCase convertUnicode convert
Operators SearchReplace