Stage 4 Draft / January 24, 2022

Relative Indexing Method

We provide a new method, at(), that is on the prototype of the built-in indexable objects: Array, String, and TypedArrays objects. The method supports relative indexing from the end when passed a negative index.

1 Additions to Properties of the Array Prototype Object

1.1 Array.prototype.at ( index )

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let relativeIndex be ? ToInteger(index).
  4. If relativeIndex ≥ 0, then
    1. Let k be relativeIndex.
  5. Else,
    1. Let k be len + relativeIndex.
  6. If k < 0 or k ≥ len, then return undefined.
  7. Return ? Get(O, ! ToString(k)).

2 Modifications to Properties of the Array Prototype Object

2.1 Array.prototype [ @@unscopables ]

The initial value of the @@unscopables data property is an object created by the following steps:

  1. Let unscopableList be ! OrdinaryObjectCreate(null).
  2. Perform ! CreateDataPropertyOrThrow(unscopableList, "at", true).
  3. Perform ! CreateDataPropertyOrThrow(unscopableList, "copyWithin", true).
  4. Perform ! CreateDataPropertyOrThrow(unscopableList, "entries", true).
  5. Perform ! CreateDataPropertyOrThrow(unscopableList, "fill", true).
  6. Perform ! CreateDataPropertyOrThrow(unscopableList, "find", true).
  7. Perform ! CreateDataPropertyOrThrow(unscopableList, "findIndex", true).
  8. Perform ! CreateDataPropertyOrThrow(unscopableList, "flat", true).
  9. Perform ! CreateDataPropertyOrThrow(unscopableList, "flatMap", true).
  10. Perform ! CreateDataPropertyOrThrow(unscopableList, "includes", true).
  11. Perform ! CreateDataPropertyOrThrow(unscopableList, "keys", true).
  12. Perform ! CreateDataPropertyOrThrow(unscopableList, "values", true).
  13. Return unscopableList.

3 Additions to Properties of the String Prototype Object

3.1 String.prototype.at ( index )

  1. Let O be ? RequireObjectCoercible(this value).
  2. Let S be ? ToString(O).
  3. Let len be the length of S.
  4. Let relativeIndex be ? ToInteger(index).
  5. If relativeIndex ≥ 0, then
    1. Let k be relativeIndex.
  6. Else,
    1. Let k be len + relativeIndex.
  7. If k < 0 or k ≥ len, then return undefined.
  8. Return the String value consisting of only the code unit at position k in S.

4 Additions to Properties of the %TypedArray.prototype% Object

4.1 %TypedArray%.prototype.at ( index )

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. Let relativeIndex be ? ToInteger(index).
  5. If relativeIndex ≥ 0, then
    1. Let k be relativeIndex.
  6. Else,
    1. Let k be len + relativeIndex.
  7. If k < 0 or k ≥ len, then return undefined.
  8. Return ? Get(O, ! ToString(k)).