Index Of

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

      ⎕←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

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

      'CAT' 'DOG' 'MOUSE'⍳'DOG' 'BIRD'
2 4

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 Z[X⍳Y], where Z is one item longer than X. The last item of Z 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.

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

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 (1-≢⍴X)↓⍴Y. Dyalog APL requires that the shapes of the cells to be compared be equal (1↓⍴X)≡(1-≢⍴X)↑⍴Y; 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 ⎕IO+⍴X. 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 ⎕IO+⍴X.

External links

Tutorials

• APL Cultivation

Documentation

• Dyalog
• NARS2000
• APLX
• J Dictionary, Nuvoc
• BQN