indices() and range() functions

[innovate-invent]

It can be quite useful to generate an array of sequential numbers, especially when wanting to use them in subsequent logic as array indexes.

The function to do this would follow the python equivalent of array[number] range(number start[, number stop[, number step]]).

Input vs Actual values used

start	stop	step	start	stop	step
>=0	null	null	0	start	1
<0	null	null	0	start	-1
<=stop	*	*	start	stop	max(1, step)
>stop	*	*	start	stop	min(-1, step)

examples:
search("foo", let({root: @}, map(&[@, root[@]], range(length(@)))) -> [[0, "f"],[1, "o"],[2, "o"]]
search("", range(-10)) -> [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
search("", range(0)) -> []

additionally the pattern range(length(@)) will likely occur so often that it would be advantageous to allow range(@) to be equivalent if @ is a type with length (array|object|string).

[springcomp]

I so like PowerShell syntax, although you cannot select a step:

1..100 |% { Write-Host $_ }

To generate the range from 1 to 100 included.

[springcomp]

The range() and indices() Functions

JEP
Author	Nolan Woods, Maxime Labelle
Status	draft
Created	23-06-2023

Abstract

This JEP proposes a set of functions to produce an array of numbers, most commonly used for iteration a given number of times.

Specification

indices

array[number] indices(array|string $subject)

The indices() function produces an array of numbers that represent the indices of elements within the given $subject.

If $subject is an array, indices() returns an array of numbers, each of which represents the zero-based index of each array element.

By extension, if $subject is a string, the indices() function returns an array of numbers, each of which represents a zero-based index of its corresponding sequence of code points.

Notes

An object in JMESPath is defined as an unordered collection of key-value pairs. For this reason, the indices() function is not defined for objects.

Examples

Expression	Result
indices(`[]`)	[]
indices(`[2, 4, 6]`)	[0, 1, 2]
indices('foo')	[0, 1, 2]
indices('')	[]

range

array[number] range(number $num[, number $stop[, number $step]])

The range() function produces an array of numbers. It is equivalent to the Python function with the same name.

The $stop and $step arguments are optional.

If the $stop argument is not specified, the range() function returns an array of numbers from 0 included to $num excluded in increasing order.

If the $stop argument is specified, however, the range() function returns an array containing the set of numbers from$num included to $stop excluded, in relative order given by the sign of the $step value, skipping numbers in increments of the $step value.

If not specified, the $step argument defaults to +1 step increment.
If $step is 0 or is not an integer, the error invalid-value MUST be raised.

More formally, the range() function returns an array such that an item from the array r at each index is determined by the formulæ:

• r[index] = $num + $step × index ∀ index ∈ ℕ: index >= 0
• r[index] < $stop ∀ $step ∈ ℕ: $step > 0
• r[index] > $stop ∀ $step ∈ ℕ: $step < 0

Examples

Expression	Result
range(`5`)	[0, 1, 2, 3, 4]
range(`0`, `1`)	[]
range(`0`, `5`)	[0, 1, 2, 3, 4]
range(`-3`, `4`)	[-3, -2, -1, 0, 1, 2]
range(`0`, `-1`, `-1`)	[]
range(`0`, `-5`, `-2`)	[0, -2, -4]
range(`3`, `-4`)	[]

Compliance Tests

A new range.json file will be added to the compliance test suite.

History

Date	Description
23-Jun-2023	Initial draft.
28-Jun-2023	range() has now the same semantics as the Python function.
28-Jun-2023	indices() no longer accepts objects as arguments.

[kit494way]

If $subject is an object, the indices() function is equivalent to the following expression range(values($subject)).

According to the document, the value() function is not guaranteed to return values in specific order.
So, I think it is better to return null if $subject is an object.

[springcomp]

You are making a good point.
Maybe we should exclude support for object, indeed.

[gibson042]

The proposed behavior of range seems to go beyond what is necessary and confusingly deviates from other languages. Absent compelling use cases, I don't think range(`-3`) or range(`3`, `-4`) should produce non-empty arrays (vs. respective explicit replacements such as range(`-2`, `1`)/map(&@ - `2`, range(`3`))/reverse(map(&@ * `-1`, range(`3`))) and reverse(range(`-3`, `4`)))—instead, the implicit step should be fixed at +1 as in Python, and there should be no argument reordering (but an explicit step parameter should be considered anyway, because the modulus filter trick is really only convenient when starting from 0).

Even so, there are edge cases to consider:

• argument with non-zero fractional part, e.g. range(`4.2`)
• large argument, e.g. range(`1e100`) (the maximum size of an array is limited in many languages, including JavaScript and Python)

[springcomp]

I updated the proposal to match the semantics of the Python range() function.

Can you help include wording around the maximum size for an array. I think we are straying into implementation defined territory. For instance, this should equally apply to slice numbers.