Index (function): Difference between revisions

From APL Wiki
Jump to navigation Jump to search
m (Text replacement - "http://help.dyalog.com" to "https://help.dyalog.com")
m (Text replacement - "<source" to "<syntaxhighlight")
Line 1: Line 1:
:''This article describes a dyadic primitive function that performs indexing into an array. For the concept of array indices, see [[Index]]. For the concept of extracting items from an array, see [[Indexing]].''
:''This article describes a dyadic primitive function that performs indexing into an array. For the concept of array indices, see [[Index]]. For the concept of extracting items from an array, see [[Indexing]].''


{{Built-in|Index|⌷}}, also called '''Squad Indexing''' after the name of the [[glyph]], is a [[dyadic]] [[primitive function]]. The result of <source lang=apl inline>X⌷Y</source> is an array formed with items of Y extracted by the [[index]] specification X. Index is a proper [[function]] alternative to a mode of [[bracket indexing]] (which uses a dedicated syntax <source lang=apl inline>Y[X]</source>), making it usable within [[tacit programming]]. It shares its glyph with the monadic [[Materialise]] function.
{{Built-in|Index|⌷}}, also called '''Squad Indexing''' after the name of the [[glyph]], is a [[dyadic]] [[primitive function]]. The result of <syntaxhighlight lang=apl inline>X⌷Y</source> is an array formed with items of Y extracted by the [[index]] specification X. Index is a proper [[function]] alternative to a mode of [[bracket indexing]] (which uses a dedicated syntax <syntaxhighlight lang=apl inline>Y[X]</source>), making it usable within [[tacit programming]]. It shares its glyph with the monadic [[Materialise]] function.


== Examples ==
== Examples ==


The left [[argument]] X must be a [[vector]] whose length equals the [[rank]] of the right argument Y and [[depth]] does not exceed 2. Each element of X selects one or more indices over the corresponding [[axis]] of the right argument Y. The result is identical to that of [[bracket indexing]] in that <source lang=apl inline>Y[X1;X2;…;Xn] ≡ X1 X2 … Xn⌷Y</source>. The resulting [[shape]] equals the [[catenate|concatenation]] of the shapes of each element of X.
The left [[argument]] X must be a [[vector]] whose length equals the [[rank]] of the right argument Y and [[depth]] does not exceed 2. Each element of X selects one or more indices over the corresponding [[axis]] of the right argument Y. The result is identical to that of [[bracket indexing]] in that <syntaxhighlight lang=apl inline>Y[X1;X2;…;Xn] ≡ X1 X2 … Xn⌷Y</source>. The resulting [[shape]] equals the [[catenate|concatenation]] of the shapes of each element of X.


<source lang=apl>
<syntaxhighlight lang=apl>
       VEC←111 222 333 444
       VEC←111 222 333 444
       3⌷VEC
       3⌷VEC
Line 27: Line 27:
</source>
</source>


When used with [[function axis]] in the form of <source lang=apl inline>X⌷[K]Y</source>, K specifies a subset of [[axes]] of Y to apply indexing on. The axes not mentioned in K are selected without modification; this corresponds to omitted axes in bracket indexing.
When used with [[function axis]] in the form of <syntaxhighlight lang=apl inline>X⌷[K]Y</source>, K specifies a subset of [[axes]] of Y to apply indexing on. The axes not mentioned in K are selected without modification; this corresponds to omitted axes in bracket indexing.


<source lang=apl>
<syntaxhighlight lang=apl>
     ⎕←CUBE←10⊥¨⍳2 3 4
     ⎕←CUBE←10⊥¨⍳2 3 4
111 112 113 114
111 112 113 114
Line 52: Line 52:
</source>
</source>


In some dialects that support [[leading axis theory]], short X in <source lang=apl inline>X⌷Y</source> selects from leading axes of Y. In that case, the trailing axes are selected without modification.
In some dialects that support [[leading axis theory]], short X in <syntaxhighlight lang=apl inline>X⌷Y</source> selects from leading axes of Y. In that case, the trailing axes are selected without modification.


<source lang=apl>
<syntaxhighlight lang=apl>
       MAT←10⊥¨⍳3 4  ⍝ Same as the first example
       MAT←10⊥¨⍳3 4  ⍝ Same as the first example
       2⌷MAT  ⍝ Second axis omitted
       2⌷MAT  ⍝ Second axis omitted
Line 62: Line 62:
== Implementation support ==
== Implementation support ==


This form of indexing is supported in [[J]] as boxed left argument of '''From''' <source lang=j inline>{</source>.
This form of indexing is supported in [[J]] as boxed left argument of '''From''' <syntaxhighlight lang=j inline>{</source>.


== See also ==
== See also ==

Revision as of 22:02, 10 September 2022

This article describes a dyadic primitive function that performs indexing into an array. For the concept of array indices, see Index. For the concept of extracting items from an array, see Indexing.

Index (), also called Squad Indexing after the name of the glyph, is a dyadic primitive function. The result of <syntaxhighlight lang=apl inline>X⌷Y</source> is an array formed with items of Y extracted by the index specification X. Index is a proper function alternative to a mode of bracket indexing (which uses a dedicated syntax <syntaxhighlight lang=apl inline>Y[X]</source>), making it usable within tacit programming. It shares its glyph with the monadic Materialise function.

Examples

The left argument X must be a vector whose length equals the rank of the right argument Y and depth does not exceed 2. Each element of X selects one or more indices over the corresponding axis of the right argument Y. The result is identical to that of bracket indexing in that <syntaxhighlight lang=apl inline>Y[X1;X2;…;Xn] ≡ X1 X2 … Xn⌷Y</source>. The resulting shape equals the concatenation of the shapes of each element of X.

<syntaxhighlight lang=apl>

     VEC←111 222 333 444
     3⌷VEC

333

     (⊂4 3)⌷VEC

444 333

     (⊂2 3⍴3 1 4 1 2 3)⌷VEC

333 111 444 111 222 333

     ⎕←MAT←10⊥¨⍳3 4

11 12 13 14 21 22 23 24 31 32 33 34

     3(2 1)⌷MAT

32 31

     ⍴(2 1⍴1)(3 4⍴2)⌷MAT

2 1 3 4 </source>

When used with function axis in the form of <syntaxhighlight lang=apl inline>X⌷[K]Y</source>, K specifies a subset of axes of Y to apply indexing on. The axes not mentioned in K are selected without modification; this corresponds to omitted axes in bracket indexing.

<syntaxhighlight lang=apl>

    ⎕←CUBE←10⊥¨⍳2 3 4

111 112 113 114 121 122 123 124 131 132 133 134

211 212 213 214 221 222 223 224 231 232 233 234

     2⌷[1]CUBE

211 212 213 214 221 222 223 224 231 232 233 234

     2⌷[3]CUBE

112 122 132 212 222 232

     CUBE[;;2] ≡ 2⌷[3]CUBE

1 </source>

In some dialects that support leading axis theory, short X in <syntaxhighlight lang=apl inline>X⌷Y</source> selects from leading axes of Y. In that case, the trailing axes are selected without modification.

<syntaxhighlight lang=apl>

     MAT←10⊥¨⍳3 4  ⍝ Same as the first example
     2⌷MAT  ⍝ Second axis omitted

21 22 23 24

</source>

Works in: Dyalog APL

Implementation support

This form of indexing is supported in J as boxed left argument of From <syntaxhighlight lang=j inline>{</source>.

See also

External links

Documentation


APL built-ins [edit]
Primitives (Timeline) Functions
Scalar
Monadic ConjugateNegateSignumReciprocalMagnitudeExponentialNatural LogarithmFloorCeilingFactorialNotPi TimesRollTypeImaginarySquare Root
Dyadic AddSubtractTimesDivideResiduePowerLogarithmMinimumMaximumBinomialComparison functionsBoolean functions (And, Or, Nand, Nor) ∙ GCDLCMCircularComplexRoot
Non-Scalar
Structural ShapeReshapeTallyDepthRavelEnlistTableCatenateReverseRotateTransposeRazeMixSplitEncloseNestCut (K)PairLinkPartitioned EnclosePartition
Selection FirstPickTakeDropUniqueIdentityStopSelectReplicateExpandSet functions (IntersectionUnionWithout) ∙ Bracket indexingIndexCartesian ProductSort
Selector Index generatorGradeIndex OfInterval IndexIndicesDealPrefix and suffix vectors
Computational MatchNot MatchMembershipFindNub SieveEncodeDecodeMatrix InverseMatrix DivideFormatExecuteMaterialiseRange
Operators Monadic EachCommuteConstantReplicateExpandReduceWindowed ReduceScanOuter ProductKeyI-BeamSpawnFunction axis
Dyadic BindCompositions (Compose, Reverse Compose, Beside, Withe, Atop, Over) ∙ Inner ProductDeterminantPowerAtUnderRankDepthVariantStencilCutDirect definition (operator)
Quad names Index originComparison toleranceMigration levelAtomic vector