Index Of: Difference between revisions
(→Documentation: BQN link) |
m (Text replacement - "<source" to "<syntaxhighlight") |
||
| Line 1: | Line 1: | ||
:''This page is about lookups. See [[Indexing]], [[Indices]], [[Index Generator]], and [[Interval Index]] for other operations named after indices.'' | :''This page is about lookups. See [[Indexing]], [[Indices]], [[Index Generator]], and [[Interval Index]] for other operations named after indices.'' | ||
{{Built-in|Index Of|⍳}} is a [[dyadic]] [[primitive function]] which returns an array of [[index|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]] < | {{Built-in|Index Of|⍳}} is a [[dyadic]] [[primitive function]] which returns an array of [[index|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 == | == Examples == | ||
| Line 6: | Line 6: | ||
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. | 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' | ⎕←x←2 3 4⍴'ABCDZ' | ||
ABCD | ABCD | ||
| Line 27: | Line 27: | ||
Both arguments can be [[nested array|nested arrays]]. Each item of the right argument is compared to that of the left argument via [[match|exact match]]. | Both arguments can be [[nested array|nested arrays]]. Each item of the right argument is compared to that of the left argument via [[match|exact match]]. | ||
< | <syntaxhighlight lang=apl> | ||
'CAT' 'DOG' 'MOUSE'⍳'DOG' 'BIRD' | 'CAT' 'DOG' 'MOUSE'⍳'DOG' 'BIRD' | ||
2 4 | 2 4 | ||
</source> | </source> | ||
The behavior on "not found" is useful for selection with fallback (analogous to the [[wikipedia:switch statement|switch statement]] with a default branch in C-like languages). To achieve this, one can use < | The behavior on "not found" is useful for selection with fallback (analogous to the [[wikipedia:switch statement|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 0['LR'⍳'LLL?!RR*LRzL'] | ||
¯1 ¯1 ¯1 0 0 1 1 0 ¯1 1 0 ¯1 | ¯1 ¯1 ¯1 0 0 1 1 0 ¯1 1 0 ¯1 | ||
| Line 45: | Line 45: | ||
== Extensions for higher-[[rank]] left argument == | == Extensions for higher-[[rank]] left argument == | ||
[[Dyalog APL]] (since 14.0) and [[J]] follows the [[leading axis theory]], and compares the [[major cell|major cells]] of X with [[cells]] of Y with the same rank. The resulting shape is < | [[Dyalog APL]] (since 14.0) and [[J]] follows the [[leading axis theory]], and compares the [[major cell|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 < | [[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 < | [[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 == | == External links == | ||
Revision as of 20:55, 10 September 2022
- 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