https://tc39.es/proposal-relative-indexing-method/


[                    ]
Pins

Table of Contents

 1. Relative Indexing Method
 2. *1 Additions to Properties of the Array Prototype Object
     1. 1.1 Array.prototype.at ( index )
 3. *2 Modifications to Properties of the Array Prototype Object
     1. 2.1 Array.prototype [ @@unscopables ]
 4. *3 Additions to Properties of the String Prototype Object
     1. 3.1 String.prototype.at ( index )
 5. *4 Additions to Properties of the %TypedArray.prototype% Object
     1. 4.1 %TypedArray%.prototype.at ( index )

Stage 3 Draft / November 20, 2020

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. [INS:Perform ! CreateDataPropertyOrThrow(unscopableList, "at",
    true).:INS]
 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)).