Indices: Difference between revisions
| Line 64: | Line 64: | ||
=== Lessons === | === Lessons === | ||
[https://chat.stackexchange.com/transcript/52405?m=41724812#41724812 APL Cultivation] | * [https://chat.stackexchange.com/transcript/52405?m=41724812#41724812 APL Cultivation] | ||
=== Documentation === | === Documentation === | ||
[http://help.dyalog.com/latest/index.htm#Language/Primitive%20Functions/Where.htm Dyalog] | * [http://help.dyalog.com/latest/index.htm#Language/Primitive%20Functions/Where.htm Dyalog] | ||
* [http://wiki.nars2000.org/index.php/Indices NARS2000] | |||
[http://wiki.nars2000.org/index.php/Indices NARS2000] | * J [https://www.jsoftware.com/help/dictionary/dicapdot.htm Dictionary], [https://code.jsoftware.com/wiki/Vocabulary/icapdot NuVoc] | ||
* [https://github.com/kevinlawler/kona/wiki/Where Kona (K4)] | |||
J [https://www.jsoftware.com/help/dictionary/dicapdot.htm Dictionary], [https://code.jsoftware.com/wiki/Vocabulary/icapdot NuVoc] | |||
== References == | == References == | ||
Revision as of 15:45, 11 December 2019
- This page describes a primitive whose result is a list of indices. See Index for the page on indices themselves. See Index of for the index generator.
⍸
|
Indices (⍸), or Where, is a monadic primitive function which returns the indices of all ones in a Boolean array. More generally, Indices accepts an array of non-negative integers and copies each index the corresponding number of times.
Where on a Boolean argument was introduced in K as &, and it was extended to non-negative integers in J, with the name Indices (I.).
Examples
In all implementations, Indices gives the indices of ones in a Boolean vector.
⍸ 0 0 1 0 0 0 1 0 3 7
In nested APLs it returns nested indices when passed a matrix or higher-dimensional array.
⍸ 3 3⍴0 0 1 0 0 0 1 0
┌───┬───┐
│1 3│3 1│
└───┴───┘
⍸ 1 ⍝ An index into a scalar is empty!
┌┐
││
└┘
If numbers higher than 1 are allowed, they indicate that the index of the number is repeated. Negative numbers are never allowed.
⍸ 3 0 2 1 1 1 3 3
Description and APL model
Indices replicates each index in the argument by the number of times it appears. It is identical to the APL function:
Where ← {(,⍵)⌿,⍳⍴⍵}
The argument is restricted to be an array of non-negative integers, or, in Dyalog APL, Booleans.
Because Indices returns indices (like Iota), it is subject to index origin.
The only flat array language which implements Indices is J. Because J's Iota does not return multidimensional indices, J defines Indices to have function rank 1 so that only vector indices are used.
Mathematical interpretation
Indices may be viewed as a way to convert between two ways of writing multisets of array indices. The argument uses a dense representation indicating for each index the number of times it appears, and the result uses a sparse representation which lists all the indices contained in the set.
History
Idioms with similar behavior to Indices were widely used in APL long before it was made into a primitive. For example, the FinnAPL idiom library, first presented in 1984, lists X/⍳⍴X as "594. Indices of ones in logical vector X".
Where (&) with a Boolean argument was present in K by K2 in 1996,[1] and extended to non-negative integers by K4 in 2000. It was added to J for the domain of non-negative integer vectors as Indices (I.) in release 5.02 (2003), introducing the pairing of Indices and Interval Index now used in APL.[2]
Indices (⍸) was first introduced to APL, and the nested array model, by NARS2000. Originally defined only for vectors, the generalised definition (,R)/,⍳⍴1/R was introduced in about 2013 after some experimentation with alternatives.[3] Where (⍸) was added to Dyalog APL 16.0 (June 2017), with the nearly-identical definition {(,⍵)⌿,⍳⍴⍵}, but also with the restriction that the argument be Boolean. This restriction that was lifted to allow non-negative integers in 18.0 (2020). For a scalar I, Dyalog's definition gives I⍴⊂⍬ for ⍸I, while NARS2000 returned I⍴1. By January 2018, NARS2000 switched to Dyalog's definition, removing the discrepancy for scalar arguments.
External links
Lessons
Documentation
References
- ↑ Kx Systems. "K User Manual". 1998.
- ↑ Jsoftware. "I. Implements Indices. 2003.
- ↑ NARS2000 Wiki. Indices. Old revision: 2013-05-26.