Stage 1 Draft / April 6, 2023

Range proposal

27 Control Abstraction Objects

27.1 Iteration

27.1.2 Properties of the Iterator Constructor

27.1.2.1 Iterator.range ( start, end, option )

  1. If start is a Number, return ? CreateNumericRangeIterator(start, end, option, number-range).
  2. If start is a BigInt, return ? CreateNumericRangeIterator(start, end, option, bigint-range).
  3. Throw a TypeError exception.

27.1.3 The NumericRangeIterator Object

A NumericRangeIterator object is an iterator that yields numbers. There is not a named constructor for NumericRangeIterator objects. Instead, NumericRangeIterator objects are created by the CreateNumericRangeIterator abstract operation as needed.

27.1.3.1 CreateNumericRangeIterator ( start, end, option, type )

The abstract operation CreateNumericRangeIterator takes arguments start (a Number or a BigInt), end (an ECMAScript language value), option (an ECMAScript language value), and type (number-range or bigint-range). It performs the following steps when called:

  1. If start is NaN, throw a RangeError exception.
  2. If end is NaN, throw a RangeError exception.
  3. If type is number-range, then
    1. Assert: start is a Number.
    2. If end is not a Number, throw a TypeError exception.
    3. Let zero be 0.
    4. Let one be 1.
  4. Else,
    1. Assert: start is a BigInt. Editor's Note
      Allowing all kinds of number (bigint, decimals, ...) to range from a finite number to infinity.
    2. If end is not +∞𝔽 or -∞𝔽 and end is not a BigInt, throw a TypeError exception.
    3. Let zero be 0n.
    4. Let one be 1n.
  5. If start is +∞𝔽 or -∞𝔽, throw a RangeError exception.
  6. Let ifIncrease be end > start.
  7. Let inclusiveEnd be false.
  8. If option is undefined or null, let step be undefined.
  9. Else if option is an Object, then
    1. Let step be ? Get(option, "step").
    2. Let inclusiveEnd be ToBoolean(? Get(option, "inclusive")).
  10. Else if type is number-range and option is a Number, let step be option.
  11. Else if type is bigint-range and option is a BigInt, let step be option.
  12. Else, throw a TypeError exception.
  13. If step is undefined or null, then
    1. If ifIncrease is true, let step be one.
    2. Else let step be -one.
  14. If step is NaN, throw a RangeError exception.
  15. If type is number-range and step is not a Number, throw a TypeError exception.
  16. Else if type is bigint-range and step is not a BigInt, throw a TypeError exception.
  17. If step is +∞𝔽 or -∞𝔽, throw a RangeError exception.
  18. If step is zero and start is not equal to end, throw a RangeError exception.
  19. Let closure be a new Abstract Closure with no parameters that captures start, end, step, inclusiveEnd, zero, one and performs the following steps when called:
    1. Let ifIncrease be end > start.
    2. Let ifStepIncrease be step > zero.
    3. If ifIncrease is not equal to ifStepIncrease, return undefined.
    4. Let hitsEnd be false.
    5. Let currentCount be zero.
    6. NOTE: You can debug these steps at https://tc39.es/proposal-Number.range/playground.html .
    7. Repeat, while hitsEnd is false,
      1. Let currentYieldingValue be start + (step * currentCount).
      2. If currentYieldingValue equal to end, Set hitsEnd to true.
      3. Set currentCount to currentCount + one. NOTE: Prevent value overflow.
      4. Let endCondition be false.
      5. If ifIncrease is true, then
        1. If inclusiveEnd is true, set endCondition be currentYieldingValue > end.
        2. Else set endCondition be currentYieldingValue >= end.
      6. Else,
        1. If inclusiveEnd is true, set endCondition be end > currentYieldingValue.
        2. Else set endCondition be end >= currentYieldingValue.
      7. If endCondition is true, return undefined.
      8. Perform ? Yield(currentYieldingValue).
    8. Return undefined.
  20. Let iterator be CreateIteratorFromClosure(closure, "%NumericRangeIteratorPrototype%", %NumericRangeIteratorPrototype%).
  21. Return iterator.

27.1.3.2 The %NumericRangeIteratorPrototype% Object

The %NumericRangeIteratorPrototype% object:

27.1.3.2.1 %NumericRangeIterator%.next ( )

  1. Return ? GeneratorResume(this value, empty, "%NumericRangeIteratorPrototype%").

27.1.3.2.2 %NumericRangeIteratorPrototype%.[@@toStringTag]

The initial value of the @@toStringTag property is the String value "NumericRangeIterator".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.