Index Generator

From APL Wiki
Revision as of 15:56, 30 March 2020 by Marshall (talk | contribs) (Created page with "{{Built-in|Index Generator|⍳}} or '''Interval''', often called by the name of its glyph '''Iota''', is a monadic primitive function which returns an array of i...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Index Generator () or Interval, often called by the name of its glyph Iota, is a monadic primitive function which returns an array of indices with shape given by the right argument. In the result, the element at each index is that index.

Originally, Iota was defined only on a single number. In APL/360, and all later APLs, ⍳l for a scalar l returns a simple numeric vector of length l counting from the index origin up. In nested APLs, this result may be seen as an array of scalar indices; NARS extended Iota to allow a vector argument by making the result for a non-singleton vector be an array of vector indices. Flat APLs do not use this extension, but may extend to multiple argument elements in different ways. A Dictionary of APL defines Iota to have function rank 0, and SHARP APL gives it rank 1 but requires each row (1-cell) of the argument to have length 1. In A+ and J Iota of a vector returns an array which counts up in ravel order, that is, it matches Iota of its bound, reshaped. A+ refers to this function as Interval while J calls it Integers.

Examples

⍳n returns the first n indices in order:

      ⍳ 5
1 2 3 4 5

This result depends on index origin: if the index origin is set to zero, it starts counting from zero instead:

      ⎕IO ← 0
      ⍳ 5
0 1 2 3 4

An argument of 0 produces the empty vector, Zilde:

      ⍳ 0

      ⍬ ≡ ⍳ 0
1

Vector arguments

In A+ and J, Iota always returns a simple array. The equivalence ⍳V V⍴⍳×/V defines the result for non-singleton vectors. If the argument is an empty vector, the result is a scalar: the index origin (which is always 0 in these languages).

   ⍳ 2 3 4
 0  1  2  3
 4  5  6  7
 8  9 10 11

12 13 14 15
16 17 18 19
20 21 22 23
   ⍳ 0⍴0
0
Works in: A+

We might call such a function a "ravel index generator" since the result is an array of scalar indices into its own ravel. In contrast, nested APLs, if they implement Iota for a vector argument (APL2 and APLX, for example, do not), use indices of elements:

      ⍳ 2 5
┌───┬───┬───┬───┬───┐
│1 1│1 2│1 3│1 4│1 5│
├───┼───┼───┼───┼───┤
│2 1│2 2│2 3│2 4│2 5│
└───┴───┴───┴───┴───┘
      ⍳⍬
┌┐
││
└┘
      (⊂⍬) ≡ ⍳⍬
1

The result of ⍳⍬ should have shape , implying it is a scalar, and its only element must be the only possible index into a scalar, the empty vector. This means it must be ⊂⍬. However, Dyalog APL returned the scalar ⎕IO instead prior to version 13.0.

Negative arguments

Two languages extend Iota to allow negative arguments. In both cases, the shape of the result is the absolute value of the argument.

In the nested APL NARS2000, negating one number in the argument subtracts that value from each index along the corresponding axis.

      ⍳2 ¯3
 1 ¯2  1 ¯1  1 0
 2 ¯2  2 ¯1  2 0
Works in: NARS2000, ⎕FEATURE[⎕IO]←1

In J, a negative number reverses the result along that axis.

   i. 2 _3
2 1 0
5 4 3
Works in: J

Scalar-vector discrepancy in nested APLs

In NARS and later nested APLs which share its definition, the result of Iota is simple when the argument is a singleton and nested otherwise. This is because, when the argument is a singleton, each index in the result is represented as a scalar rather than a 1-element vector. dzaima/APL breaks from this definition by using vector indices whenever the argument is a vector, and scalar indices if the argument is a scalar, so that the result is only simple if the argument was scalar. This definition has the property that the shape of each index matches the shape of the argument.

Such an extension breaks compatibility with earlier non-nested APLs: although these APLs required the argument of Iota to be a singleton, they always allowed a scalar or vector, and sometimes any singleton. This is because a shape to be passed to Iota would often naturally be a vector: for example, Shape always returns a vector, and a function such as Tally to return a scalar length did not exist.

NARS defines its extension using the equivalence ⍳R ⊃∘.,/⍳¨R based on an Outer Product reduction. For a singleton vector R, this does yield a simple result, because ∘.,/ leaves a singleton argument unchanged. However, this is arguably due to inconsistent design in Reduce: NARS's creator, Bob Smith, argues that Catenate reduction should yield a DOMAIN ERROR, and the same arguments apply to its Outer Product.[1]

History

The notation , "Interval", was used in Iverson notation for the vector of the first indices starting at index origin . Both arguments were optional, with being implied by conformability if omitted. It was adopted with the obvious alterations in APL\360, and extended to a vector argument for nested APLs by NARS and for flat arrays by A+.

External links

Documentation

References

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