Index Of

From APL Wiki
Revision as of 20:55, 10 September 2022 by Adám Brudzewsky (talk | contribs) (Text replacement - "<source" to "<syntaxhighlight")
Jump to navigation Jump to search
This page is about lookups. See Indexing, Indices, Index Generator, and Interval Index for other operations named after indices.

Index Of () is a dyadic primitive function which returns an array of indices where each item in the right argument appears in the left argument. If some item is not found, the corresponding index returned is one higher than the last index of the left argument. Index Of shares its glyph <syntaxhighlight lang=apl inline>⍳</source> with the monadic primitive function Index Generator.

Examples

The right argument can have any shape, but the left argument is usually restricted to a vector. The result is a simple integer array with the shape of the right argument, and each cell indicates at which index the corresponding item is found (or not found at all) in the left argument.

<syntaxhighlight lang=apl>

     ⎕←x←2 3 4⍴'ABCDZ'

ABCD ZABC DZAB

CDZA BCDZ ABCD

     'ABCD'⍳x

1 2 3 4 5 1 2 3 4 5 1 2

3 4 5 1 2 3 4 5 1 2 3 4 </source>

Both arguments can be nested arrays. Each item of the right argument is compared to that of the left argument via exact match.

<syntaxhighlight lang=apl>

     'CAT' 'DOG' 'MOUSE'⍳'DOG' 'BIRD'

2 4 </source>

The behavior on "not found" is useful for selection with fallback (analogous to the switch statement with a default branch in C-like languages). To achieve this, one can use <syntaxhighlight lang=apl inline>Z[X⍳Y]</source>, where <syntaxhighlight lang=apl inline>Z</source> is one item longer than <syntaxhighlight lang=apl inline>X</source>. The last item of <syntaxhighlight lang=apl inline>Z</source> corresponds to the fallback item. In the example below, L and R are mapped to the values -1 and 1, while anything else is garbage and mapped to the fallback value of 0.

<syntaxhighlight lang=apl>

     ¯1 1 0['LR'⍳'LLL?!RR*LRzL']

¯1 ¯1 ¯1 0 0 1 1 0 ¯1 1 0 ¯1 </source>

Properties

The result of Index Of depends on index origin and comparison tolerance.

Extensions for higher-rank left argument

Dyalog APL (since 14.0) and J follows the leading axis theory, and compares the major cells of X with cells of Y with the same rank. The resulting shape is <syntaxhighlight lang=apl inline>(1-≢⍴X)↓⍴Y</source>. Dyalog APL requires that the shapes of the cells to be compared be equal <syntaxhighlight lang=apl inline>(1↓⍴X)≡(1-≢⍴X)↑⍴Y</source>; otherwise LENGTH ERROR is raised. J simply treats them as not found.

NARS2000 simply compares items of X to the items of Y, and returns the nested array of shape of Y where each item indicates a multi-dimensional index in X. The index for not found items is <syntaxhighlight lang=apl inline>⎕IO+⍴X</source>. This also works with scalar X, though the result (an array filled with empty vectors) is not very meaningful.

GNU APL follows the convention of NARS2000, with the exception that the index for not found items is an empty vector (!) instead of <syntaxhighlight lang=apl inline>⎕IO+⍴X</source>.

External links

Tutorials

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