Skip to content

23 Indexed Collections

23.1 Array Objects

Arrays are exotic objects that give special treatment to a certain class of property names. See 10.4.2 for a definition of this special treatment.

23.1.1 The Array Constructor

The Array constructor:

  • is %Array%.
  • is the initial value of the "Array" property of the global object.
  • creates and initializes a new Array when called as a constructor.
  • also creates and initializes a new Array when called as a function rather than as a constructor. Thus the function call Array(…) is equivalent to the object creation expression new Array(…) with the same arguments.
  • is a function whose behaviour differs based upon the number and types of its arguments.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the exotic Array behaviour must include a super call to the Array constructor to initialize subclass instances that are Array exotic objects. However, most of the Array.prototype methods are generic methods that are not dependent upon their this value being an Array exotic object.
  • has a "length" property whose value is 1𝔽.

23.1.1.1 Array ( ...values )

When the Array function is called, the following steps are taken:

  1. If NewTarget is undefined, let newTarget be the active function object; else let newTarget be NewTarget.
  2. Let proto be ? GetPrototypeFromConstructor(newTarget, "%Array.prototype%").
  3. Let numberOfArgs be the number of elements in values.
  4. If numberOfArgs = 0, then
    1. Return ! ArrayCreate(0, proto).
  5. Else if numberOfArgs = 1, then
    1. Let len be values[0].
    2. Let array be ! ArrayCreate(0, proto).
    3. If Type(len) is not Number, then
      1. Perform ! CreateDataPropertyOrThrow(array, "0", len).
      2. Let intLen be 1𝔽.
    4. Else,
      1. Let intLen be ! ToUint32(len).
      2. If SameValueZero(intLen, len) is false, throw a RangeError exception.
    5. Perform ! Set(array, "length", intLen, true).
    6. Return array.
  6. Else,
    1. Assert: numberOfArgs ≥ 2.
    2. Let array be ? ArrayCreate(numberOfArgs, proto).
    3. Let k be 0.
    4. Repeat, while k < numberOfArgs,
      1. Let Pk be ! ToString(𝔽(k)).
      2. Let itemK be values[k].
      3. Perform ! CreateDataPropertyOrThrow(array, Pk, itemK).
      4. Set k to k + 1.
    5. Assert: The mathematical value of array's "length" property is numberOfArgs.
    6. Return array.

23.1.2 Properties of the Array Constructor

The Array constructor:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has the following properties:

23.1.2.1 Array.from ( items [ , mapfn [ , thisArg ] ] )

When the from method is called, the following steps are taken:

  1. Let C be the this value.
  2. If mapfn is undefined, let mapping be false.
  3. Else,
    1. If IsCallable(mapfn) is false, throw a TypeError exception.
    2. Let mapping be true.
  4. Let usingIterator be ? GetMethod(items, @@iterator).
  5. If usingIterator is not undefined, then
    1. If IsConstructor(C) is true, then
      1. Let A be ? Construct(C).
    2. Else,
      1. Let A be ! ArrayCreate(0).
    3. Let iteratorRecord be ? GetIterator(items, sync, usingIterator).
    4. Let k be 0.
    5. Repeat,
      1. If k ≥ 253 - 1, then
        1. Let error be ThrowCompletion(a newly created TypeError object).
        2. Return ? IteratorClose(iteratorRecord, error).
      2. Let Pk be ! ToString(𝔽(k)).
      3. Let next be ? IteratorStep(iteratorRecord).
      4. If next is false, then
        1. Perform ? Set(A, "length", 𝔽(k), true).
        2. Return A.
      5. Let nextValue be ? IteratorValue(next).
      6. If mapping is true, then
        1. Let mappedValue be Completion(Call(mapfn, thisArg, « nextValue, 𝔽(k) »)).
        2. IfAbruptCloseIterator(mappedValue, iteratorRecord).
      7. Else, let mappedValue be nextValue.
      8. Let defineStatus be Completion(CreateDataPropertyOrThrow(A, Pk, mappedValue)).
      9. IfAbruptCloseIterator(defineStatus, iteratorRecord).
      10. Set k to k + 1.
  6. NOTE: items is not an Iterable so assume it is an array-like object.
  7. Let arrayLike be ! ToObject(items).
  8. Let len be ? LengthOfArrayLike(arrayLike).
  9. If IsConstructor(C) is true, then
    1. Let A be ? Construct(C, « 𝔽(len) »).
  10. Else,
    1. Let A be ? ArrayCreate(len).
  11. Let k be 0.
  12. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ? Get(arrayLike, Pk).
    3. If mapping is true, then
      1. Let mappedValue be ? Call(mapfn, thisArg, « kValue, 𝔽(k) »).
    4. Else, let mappedValue be kValue.
    5. Perform ? CreateDataPropertyOrThrow(A, Pk, mappedValue).
    6. Set k to k + 1.
  13. Perform ? Set(A, "length", 𝔽(len), true).
  14. Return A.
 Note

The from function is an intentionally generic factory method; it does not require that its this value be the Array constructor. Therefore it can be transferred to or inherited by any other constructors that may be called with a single numeric argument.

23.1.2.2 Array.isArray ( arg )

When the isArray method is called, the following steps are taken:

  1. Return ? IsArray(arg).

23.1.2.3 Array.of ( ...items )

When the of method is called, the following steps are taken:

  1. Let len be the number of elements in items.
  2. Let lenNumber be 𝔽(len).
  3. Let C be the this value.
  4. If IsConstructor(C) is true, then
    1. Let A be ? Construct(C, « lenNumber »).
  5. Else,
    1. Let A be ? ArrayCreate(len).
  6. Let k be 0.
  7. Repeat, while k < len,
    1. Let kValue be items[k].
    2. Let Pk be ! ToString(𝔽(k)).
    3. Perform ? CreateDataPropertyOrThrow(A, Pk, kValue).
    4. Set k to k + 1.
  8. Perform ? Set(A, "length", lenNumber, true).
  9. Return A.
 Note

The of function is an intentionally generic factory method; it does not require that its this value be the Array constructor. Therefore it can be transferred to or inherited by other constructors that may be called with a single numeric argument.

23.1.2.4 Array.prototype

The value of Array.prototype is the Array prototype object.

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

23.1.2.5 get Array [ @@species ]

Array[@@species] is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Return the this value.

The value of the "name" property of this function is "get [Symbol.species]".

Note

Array prototype methods normally use their this value's constructor to create a derived object. However, a subclass constructor may over-ride that default behaviour by redefining its @@species property.

23.1.3 Properties of the Array Prototype Object

The Array prototype object:

  • is %Array.prototype%.
  • is an Array exotic object and has the internal methods specified for such objects.
  • has a "length" property whose initial value is +0𝔽 and whose attributes are { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false }.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
Note

The Array prototype object is specified to be an Array exotic object to ensure compatibility with ECMAScript code that was created prior to the ECMAScript 2015 specification.

23.1.3.1 Array.prototype.at ( index )

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let relativeIndex be ? ToIntegerOrInfinity(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, return undefined.
  7. Return ? Get(O, ! ToString(𝔽(k))).

23.1.3.2 Array.prototype.concat ( ...items )

Returns an array containing the array elements of the object followed by the array elements of each argument.

When the concat method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let A be ? ArraySpeciesCreate(O, 0).
  3. Let n be 0.
  4. Prepend O to items.
  5. For each element E of items, do
    1. Let spreadable be ? IsConcatSpreadable(E).
    2. If spreadable is true, then
      1. Let k be 0.
      2. Let len be ? LengthOfArrayLike(E).
      3. If n + len > 253 - 1, throw a TypeError exception.
      4. Repeat, while k < len,
        1. Let P be ! ToString(𝔽(k)).
        2. Let exists be ? HasProperty(E, P).
        3. If exists is true, then
          1. Let subElement be ? Get(E, P).
          2. Perform ? CreateDataPropertyOrThrow(A, ! ToString(𝔽(n)), subElement).
        4. Set n to n + 1.
        5. Set k to k + 1.
    3. Else,
      1. NOTE: E is added as a single item rather than spread.
      2. If n ≥ 253 - 1, throw a TypeError exception.
      3. Perform ? CreateDataPropertyOrThrow(A, ! ToString(𝔽(n)), E).
      4. Set n to n + 1.
  6. Perform ? Set(A, "length", 𝔽(n), true).
  7. Return A.

The "length" property of the concat method is 1𝔽.

Note 1

The explicit setting of the "length" property in step 6 is necessary to ensure that its value is correct in situations where the trailing elements of the result Array are not present.

 Note 2

The concat function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.2.1 IsConcatSpreadable ( O )

The abstract operation IsConcatSpreadable takes argument O and returns either a normal completion containing a Boolean or an abrupt completion. It performs the following steps when called:

  1. If Type(O) is not Object, return false.
  2. Let spreadable be ? Get(O, @@isConcatSpreadable).
  3. If spreadable is not undefined, return ToBoolean(spreadable).
  4. Return ? IsArray(O).

23.1.3.3 Array.prototype.constructor

The initial value of Array.prototype.constructor is %Array%.

23.1.3.4 Array.prototype.copyWithin ( target, start [ , end ] )

Note 1

The end argument is optional. If it is not provided, the length of the this value is used.

 Note 2

If target is negative, it is treated as length + target where length is the length of the array. If start is negative, it is treated as length + start. If end is negative, it is treated as length + end.

When the copyWithin method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let relativeTarget be ? ToIntegerOrInfinity(target).
  4. If relativeTarget is -∞, let to be 0.
  5. Else if relativeTarget < 0, let to be max(len + relativeTarget, 0).
  6. Else, let to be min(relativeTarget, len).
  7. Let relativeStart be ? ToIntegerOrInfinity(start).
  8. If relativeStart is -∞, let from be 0.
  9. Else if relativeStart < 0, let from be max(len + relativeStart, 0).
  10. Else, let from be min(relativeStart, len).
  11. If end is undefined, let relativeEnd be len; else let relativeEnd be ? ToIntegerOrInfinity(end).
  12. If relativeEnd is -∞, let final be 0.
  13. Else if relativeEnd < 0, let final be max(len + relativeEnd, 0).
  14. Else, let final be min(relativeEnd, len).
  15. Let count be min(final - from, len - to).
  16. If from < to and to < from + count, then
    1. Let direction be -1.
    2. Set from to from + count - 1.
    3. Set to to to + count - 1.
  17. Else,
    1. Let direction be 1.
  18. Repeat, while count > 0,
    1. Let fromKey be ! ToString(𝔽(from)).
    2. Let toKey be ! ToString(𝔽(to)).
    3. Let fromPresent be ? HasProperty(O, fromKey).
    4. If fromPresent is true, then
      1. Let fromVal be ? Get(O, fromKey).
      2. Perform ? Set(O, toKey, fromVal, true).
    5. Else,
      1. Assert: fromPresent is false.
      2. Perform ? DeletePropertyOrThrow(O, toKey).
    6. Set from to from + direction.
    7. Set to to to + direction.
    8. Set count to count - 1.
  19. Return O.
 Note 3

The copyWithin function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.5 Array.prototype.entries ( )

When the entries method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Return CreateArrayIterator(O, key+value).

23.1.3.6 Array.prototype.every ( callbackfn [ , thisArg ] )

Note 1

callbackfn should be a function that accepts three arguments and returns a value that is coercible to a Boolean value. every calls callbackfn once for each element present in the array, in ascending order, until it finds one where callbackfn returns false. If such an element is found, every immediately returns false. Otherwise, if callbackfn returned true for all elements, every will return true. callbackfn is called only for elements of the array which actually exist; it is not called for missing elements of the array.

If a thisArg parameter is provided, it will be used as the this value for each invocation of callbackfn. If it is not provided, undefined is used instead.

callbackfn is called with three arguments: the value of the element, the index of the element, and the object being traversed.

every does not directly mutate the object on which it is called but the object may be mutated by the calls to callbackfn.

The range of elements processed by every is set before the first call to callbackfn. Elements which are appended to the array after the call to every begins will not be visited by callbackfn. If existing elements of the array are changed, their value as passed to callbackfn will be the value at the time every visits them; elements that are deleted after the call to every begins and before being visited are not visited. every acts like the "for all" quantifier in mathematics. In particular, for an empty array, it returns true.

When the every method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If IsCallable(callbackfn) is false, throw a TypeError exception.
  4. Let k be 0.
  5. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kPresent be ? HasProperty(O, Pk).
    3. If kPresent is true, then
      1. Let kValue be ? Get(O, Pk).
      2. Let testResult be ToBoolean(? Call(callbackfn, thisArg, « kValue, 𝔽(k), O »)).
      3. If testResult is false, return false.
    4. Set k to k + 1.
  6. Return true.
 Note 2

The every function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.7 Array.prototype.fill ( value [ , start [ , end ] ] )

Note 1

The start argument is optional. If it is not provided, +0𝔽 is used.

The end argument is optional. If it is not provided, the length of the this value is used.

 Note 2

If start is negative, it is treated as length + start where length is the length of the array. If end is negative, it is treated as length + end.

When the fill method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let relativeStart be ? ToIntegerOrInfinity(start).
  4. If relativeStart is -∞, let k be 0.
  5. Else if relativeStart < 0, let k be max(len + relativeStart, 0).
  6. Else, let k be min(relativeStart, len).
  7. If end is undefined, let relativeEnd be len; else let relativeEnd be ? ToIntegerOrInfinity(end).
  8. If relativeEnd is -∞, let final be 0.
  9. Else if relativeEnd < 0, let final be max(len + relativeEnd, 0).
  10. Else, let final be min(relativeEnd, len).
  11. Repeat, while k < final,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Perform ? Set(O, Pk, value, true).
    3. Set k to k + 1.
  12. Return O.
 Note 3

The fill function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.8 Array.prototype.filter ( callbackfn [ , thisArg ] )

Note 1

callbackfn should be a function that accepts three arguments and returns a value that is coercible to a Boolean value. filter calls callbackfn once for each element in the array, in ascending order, and constructs a new array of all the values for which callbackfn returns true. callbackfn is called only for elements of the array which actually exist; it is not called for missing elements of the array.

If a thisArg parameter is provided, it will be used as the this value for each invocation of callbackfn. If it is not provided, undefined is used instead.

callbackfn is called with three arguments: the value of the element, the index of the element, and the object being traversed.

filter does not directly mutate the object on which it is called but the object may be mutated by the calls to callbackfn.

The range of elements processed by filter is set before the first call to callbackfn. Elements which are appended to the array after the call to filter begins will not be visited by callbackfn. If existing elements of the array are changed their value as passed to callbackfn will be the value at the time filter visits them; elements that are deleted after the call to filter begins and before being visited are not visited.

When the filter method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If IsCallable(callbackfn) is false, throw a TypeError exception.
  4. Let A be ? ArraySpeciesCreate(O, 0).
  5. Let k be 0.
  6. Let to be 0.
  7. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kPresent be ? HasProperty(O, Pk).
    3. If kPresent is true, then
      1. Let kValue be ? Get(O, Pk).
      2. Let selected be ToBoolean(? Call(callbackfn, thisArg, « kValue, 𝔽(k), O »)).
      3. If selected is true, then
        1. Perform ? CreateDataPropertyOrThrow(A, ! ToString(𝔽(to)), kValue).
        2. Set to to to + 1.
    4. Set k to k + 1.
  8. Return A.
 Note 2

The filter function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.9 Array.prototype.find ( predicate [ , thisArg ] )

Note 1

predicate should be a function that accepts three arguments and returns a value that is coercible to a Boolean value. find calls predicate once for each element of the array, in ascending order, until it finds one where predicate returns true. If such an element is found, find immediately returns that element value. Otherwise, find returns undefined.

If a thisArg parameter is provided, it will be used as the this value for each invocation of predicate. If it is not provided, undefined is used instead.

predicate is called with three arguments: the value of the element, the index of the element, and the object being traversed.

find does not directly mutate the object on which it is called but the object may be mutated by the calls to predicate.

The range of elements processed by find is set before the first call to predicate. Elements that are appended to the array after the call to find begins will not be visited by predicate. If existing elements of the array are changed, their value as passed to predicate will be the value at the time that find visits them; elements that are deleted after the call to find begins and before being visited are still visited and are either looked up from the prototype or are undefined.

When the find method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If IsCallable(predicate) is false, throw a TypeError exception.
  4. Let k be 0.
  5. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ? Get(O, Pk).
    3. Let testResult be ToBoolean(? Call(predicate, thisArg, « kValue, 𝔽(k), O »)).
    4. If testResult is true, return kValue.
    5. Set k to k + 1.
  6. Return undefined.
 Note 2

The find function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.10 Array.prototype.findIndex ( predicate [ , thisArg ] )

Note 1

predicate should be a function that accepts three arguments and returns a value that is coercible to a Boolean value. findIndex calls predicate once for each element of the array, in ascending order, until it finds one where predicate returns true. If such an element is found, findIndex immediately returns the index of that element value. Otherwise, findIndex returns -1.

If a thisArg parameter is provided, it will be used as the this value for each invocation of predicate. If it is not provided, undefined is used instead.

predicate is called with three arguments: the value of the element, the index of the element, and the object being traversed.

findIndex does not directly mutate the object on which it is called but the object may be mutated by the calls to predicate.

The range of elements processed by findIndex is set before the first call to predicate. Elements that are appended to the array after the call to findIndex begins will not be visited by predicate. If existing elements of the array are changed, their value as passed to predicate will be the value at the time that findIndex visits them; elements that are deleted after the call to findIndex begins and before being visited are still visited and are either looked up from the prototype or are undefined.

When the findIndex method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If IsCallable(predicate) is false, throw a TypeError exception.
  4. Let k be 0.
  5. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ? Get(O, Pk).
    3. Let testResult be ToBoolean(? Call(predicate, thisArg, « kValue, 𝔽(k), O »)).
    4. If testResult is true, return 𝔽(k).
    5. Set k to k + 1.
  6. Return -1𝔽.
 Note 2

The findIndex function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.11 Array.prototype.flat ( [ depth ] )

When the flat method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let sourceLen be ? LengthOfArrayLike(O).
  3. Let depthNum be 1.
  4. If depth is not undefined, then
    1. Set depthNum to ? ToIntegerOrInfinity(depth).
    2. If depthNum < 0, set depthNum to 0.
  5. Let A be ? ArraySpeciesCreate(O, 0).
  6. Perform ? FlattenIntoArray(A, O, sourceLen, 0, depthNum).
  7. Return A.

23.1.3.11.1 FlattenIntoArray ( target, source, sourceLen, start, depth [ , mapperFunction [ , thisArg ] ] )

The abstract operation FlattenIntoArray takes arguments target (an Object), source (an Object), sourceLen (a non-negative integer), start (a non-negative integer), and depth (a non-negative integer or +∞) and optional arguments mapperFunction and thisArg and returns either a normal completion containing a non-negative integer or an abrupt completion. It performs the following steps when called:

  1. Assert: If mapperFunction is present, then IsCallable(mapperFunction) is true, thisArg is present, and depth is 1.
  2. Let targetIndex be start.
  3. Let sourceIndex be +0𝔽.
  4. Repeat, while ℝ(sourceIndex) < sourceLen,
    1. Let P be ! ToString(sourceIndex).
    2. Let exists be ? HasProperty(source, P).
    3. If exists is true, then
      1. Let element be ? Get(source, P).
      2. If mapperFunction is present, then
        1. Set element to ? Call(mapperFunction, thisArg, « element, sourceIndex, source »).
      3. Let shouldFlatten be false.
      4. If depth > 0, then
        1. Set shouldFlatten to ? IsArray(element).
      5. If shouldFlatten is true, then
        1. If depth is +∞, let newDepth be +∞.
        2. Else, let newDepth be depth - 1.
        3. Let elementLen be ? LengthOfArrayLike(element).
        4. Set targetIndex to ? FlattenIntoArray(target, element, elementLen, targetIndex, newDepth).
      6. Else,
        1. If targetIndex ≥ 253 - 1, throw a TypeError exception.
        2. Perform ? CreateDataPropertyOrThrow(target, ! ToString(𝔽(targetIndex)), element).
        3. Set targetIndex to targetIndex + 1.
    4. Set sourceIndex to sourceIndex + 1𝔽.
  5. Return targetIndex.

23.1.3.12 Array.prototype.flatMap ( mapperFunction [ , thisArg ] )

When the flatMap method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let sourceLen be ? LengthOfArrayLike(O).
  3. If IsCallable(mapperFunction) is false, throw a TypeError exception.
  4. Let A be ? ArraySpeciesCreate(O, 0).
  5. Perform ? FlattenIntoArray(A, O, sourceLen, 0, 1, mapperFunction, thisArg).
  6. Return A.

23.1.3.13 Array.prototype.forEach ( callbackfn [ , thisArg ] )

Note 1

callbackfn should be a function that accepts three arguments. forEach calls callbackfn once for each element present in the array, in ascending order. callbackfn is called only for elements of the array which actually exist; it is not called for missing elements of the array.

If a thisArg parameter is provided, it will be used as the this value for each invocation of callbackfn. If it is not provided, undefined is used instead.

callbackfn is called with three arguments: the value of the element, the index of the element, and the object being traversed.

forEach does not directly mutate the object on which it is called but the object may be mutated by the calls to callbackfn.

The range of elements processed by forEach is set before the first call to callbackfn. Elements which are appended to the array after the call to forEach begins will not be visited by callbackfn. If existing elements of the array are changed, their value as passed to callbackfn will be the value at the time forEach visits them; elements that are deleted after the call to forEach begins and before being visited are not visited.

When the forEach method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If IsCallable(callbackfn) is false, throw a TypeError exception.
  4. Let k be 0.
  5. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kPresent be ? HasProperty(O, Pk).
    3. If kPresent is true, then
      1. Let kValue be ? Get(O, Pk).
      2. Perform ? Call(callbackfn, thisArg, « kValue, 𝔽(k), O »).
    4. Set k to k + 1.
  6. Return undefined.
 Note 2

The forEach function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.14 Array.prototype.includes ( searchElement [ , fromIndex ] )

Note 1

includes compares searchElement to the elements of the array, in ascending order, using the SameValueZero algorithm, and if found at any position, returns true; otherwise, false is returned.

The optional second argument fromIndex defaults to +0𝔽 (i.e. the whole array is searched). If it is greater than or equal to the length of the array, false is returned, i.e. the array will not be searched. If it is less than +0𝔽, it is used as the offset from the end of the array to compute fromIndex. If the computed index is less than +0𝔽, the whole array will be searched.

When the includes method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If len is 0, return false.
  4. Let n be ? ToIntegerOrInfinity(fromIndex).
  5. Assert: If fromIndex is undefined, then n is 0.
  6. If n is +∞, return false.
  7. Else if n is -∞, set n to 0.
  8. If n ≥ 0, then
    1. Let k be n.
  9. Else,
    1. Let k be len + n.
    2. If k < 0, set k to 0.
  10. Repeat, while k < len,
    1. Let elementK be ? Get(O, ! ToString(𝔽(k))).
    2. If SameValueZero(searchElement, elementK) is true, return true.
    3. Set k to k + 1.
  11. Return false.
 Note 2

The includes function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

 Note 3

The includes method intentionally differs from the similar indexOf method in two ways. First, it uses the SameValueZero algorithm, instead of IsStrictlyEqual, allowing it to detect NaN array elements. Second, it does not skip missing array elements, instead treating them as undefined.

23.1.3.15 Array.prototype.indexOf ( searchElement [ , fromIndex ] )

indexOf compares searchElement to the elements of the array, in ascending order, using the IsStrictlyEqual algorithm, and if found at one or more indices, returns the smallest such index; otherwise, -1𝔽 is returned.

Note 1

The optional second argument fromIndex defaults to +0𝔽 (i.e. the whole array is searched). If it is greater than or equal to the length of the array, -1𝔽 is returned, i.e. the array will not be searched. If it is less than +0𝔽, it is used as the offset from the end of the array to compute fromIndex. If the computed index is less than +0𝔽, the whole array will be searched.

When the indexOf method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If len is 0, return -1𝔽.
  4. Let n be ? ToIntegerOrInfinity(fromIndex).
  5. Assert: If fromIndex is undefined, then n is 0.
  6. If n is +∞, return -1𝔽.
  7. Else if n is -∞, set n to 0.
  8. If n ≥ 0, then
    1. Let k be n.
  9. Else,
    1. Let k be len + n.
    2. If k < 0, set k to 0.
  10. Repeat, while k < len,
    1. Let kPresent be ? HasProperty(O, ! ToString(𝔽(k))).
    2. If kPresent is true, then
      1. Let elementK be ? Get(O, ! ToString(𝔽(k))).
      2. Let same be IsStrictlyEqual(searchElement, elementK).
      3. If same is true, return 𝔽(k).
    3. Set k to k + 1.
  11. Return -1𝔽.
 Note 2

The indexOf function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.16 Array.prototype.join ( separator )

The elements of the array are converted to Strings, and these Strings are then concatenated, separated by occurrences of the separator. If no separator is provided, a single comma is used as the separator.

When the join method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If separator is undefined, let sep be the single-element String ",".
  4. Else, let sep be ? ToString(separator).
  5. Let R be the empty String.
  6. Let k be 0.
  7. Repeat, while k < len,
    1. If k > 0, set R to the string-concatenation of R and sep.
    2. Let element be ? Get(O, ! ToString(𝔽(k))).
    3. If element is undefined or null, let next be the empty String; otherwise, let next be ? ToString(element).
    4. Set R to the string-concatenation of R and next.
    5. Set k to k + 1.
  8. Return R.
 Note

The join function is intentionally generic; it does not require that its this value be an Array. Therefore, it can be transferred to other kinds of objects for use as a method.

23.1.3.17 Array.prototype.keys ( )

When the keys method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Return CreateArrayIterator(O, key).

23.1.3.18 Array.prototype.lastIndexOf ( searchElement [ , fromIndex ] )

Note 1

lastIndexOf compares searchElement to the elements of the array in descending order using the IsStrictlyEqual algorithm, and if found at one or more indices, returns the largest such index; otherwise, -1𝔽 is returned.

The optional second argument fromIndex defaults to the array's length minus one (i.e. the whole array is searched). If it is greater than or equal to the length of the array, the whole array will be searched. If it is less than +0𝔽, it is used as the offset from the end of the array to compute fromIndex. If the computed index is less than +0𝔽, -1𝔽 is returned.

When the lastIndexOf method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If len is 0, return -1𝔽.
  4. If fromIndex is present, let n be ? ToIntegerOrInfinity(fromIndex); else let n be len - 1.
  5. If n is -∞, return -1𝔽.
  6. If n ≥ 0, then
    1. Let k be min(n, len - 1).
  7. Else,
    1. Let k be len + n.
  8. Repeat, while k ≥ 0,
    1. Let kPresent be ? HasProperty(O, ! ToString(𝔽(k))).
    2. If kPresent is true, then
      1. Let elementK be ? Get(O, ! ToString(𝔽(k))).
      2. Let same be IsStrictlyEqual(searchElement, elementK).
      3. If same is true, return 𝔽(k).
    3. Set k to k - 1.
  9. Return -1𝔽.
 Note 2

The lastIndexOf function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.19 Array.prototype.map ( callbackfn [ , thisArg ] )

Note 1

callbackfn should be a function that accepts three arguments. map calls callbackfn once for each element in the array, in ascending order, and constructs a new Array from the results. callbackfn is called only for elements of the array which actually exist; it is not called for missing elements of the array.

If a thisArg parameter is provided, it will be used as the this value for each invocation of callbackfn. If it is not provided, undefined is used instead.

callbackfn is called with three arguments: the value of the element, the index of the element, and the object being traversed.

map does not directly mutate the object on which it is called but the object may be mutated by the calls to callbackfn.

The range of elements processed by map is set before the first call to callbackfn. Elements which are appended to the array after the call to map begins will not be visited by callbackfn. If existing elements of the array are changed, their value as passed to callbackfn will be the value at the time map visits them; elements that are deleted after the call to map begins and before being visited are not visited.

When the map method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If IsCallable(callbackfn) is false, throw a TypeError exception.
  4. Let A be ? ArraySpeciesCreate(O, len).
  5. Let k be 0.
  6. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kPresent be ? HasProperty(O, Pk).
    3. If kPresent is true, then
      1. Let kValue be ? Get(O, Pk).
      2. Let mappedValue be ? Call(callbackfn, thisArg, « kValue, 𝔽(k), O »).
      3. Perform ? CreateDataPropertyOrThrow(A, Pk, mappedValue).
    4. Set k to k + 1.
  7. Return A.
 Note 2

The map function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.20 Array.prototype.pop ( )

Note 1

The last element of the array is removed from the array and returned.

When the pop method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If len = 0, then
    1. Perform ? Set(O, "length", +0𝔽, true).
    2. Return undefined.
  4. Else,
    1. Assert: len > 0.
    2. Let newLen be 𝔽(len - 1).
    3. Let index be ! ToString(newLen).
    4. Let element be ? Get(O, index).
    5. Perform ? DeletePropertyOrThrow(O, index).
    6. Perform ? Set(O, "length", newLen, true).
    7. Return element.
 Note 2

The pop function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.21 Array.prototype.push ( ...items )

Note 1

The arguments are appended to the end of the array, in the order in which they appear. The new length of the array is returned as the result of the call.

When the push method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let argCount be the number of elements in items.
  4. If len + argCount > 253 - 1, throw a TypeError exception.
  5. For each element E of items, do
    1. Perform ? Set(O, ! ToString(𝔽(len)), E, true).
    2. Set len to len + 1.
  6. Perform ? Set(O, "length", 𝔽(len), true).
  7. Return 𝔽(len).

The "length" property of the push method is 1𝔽.

Note 2

The push function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.22 Array.prototype.reduce ( callbackfn [ , initialValue ] )

Note 1

callbackfn should be a function that takes four arguments. reduce calls the callback, as a function, once for each element after the first element present in the array, in ascending order.

callbackfn is called with four arguments: the previousValue (value from the previous call to callbackfn), the currentValue (value of the current element), the currentIndex, and the object being traversed. The first time that callback is called, the previousValue and currentValue can be one of two values. If an initialValue was supplied in the call to reduce, then previousValue will be equal to initialValue and currentValue will be equal to the first value in the array. If no initialValue was supplied, then previousValue will be equal to the first value in the array and currentValue will be equal to the second. It is a TypeError if the array contains no elements and initialValue is not provided.

reduce does not directly mutate the object on which it is called but the object may be mutated by the calls to callbackfn.

The range of elements processed by reduce is set before the first call to callbackfn. Elements that are appended to the array after the call to reduce begins will not be visited by callbackfn. If existing elements of the array are changed, their value as passed to callbackfn will be the value at the time reduce visits them; elements that are deleted after the call to reduce begins and before being visited are not visited.

When the reduce method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If IsCallable(callbackfn) is false, throw a TypeError exception.
  4. If len = 0 and initialValue is not present, throw a TypeError exception.
  5. Let k be 0.
  6. Let accumulator be undefined.
  7. If initialValue is present, then
    1. Set accumulator to initialValue.
  8. Else,
    1. Let kPresent be false.
    2. Repeat, while kPresent is false and k < len,
      1. Let Pk be ! ToString(𝔽(k)).
      2. Set kPresent to ? HasProperty(O, Pk).
      3. If kPresent is true, then
        1. Set accumulator to ? Get(O, Pk).
      4. Set k to k + 1.
    3. If kPresent is false, throw a TypeError exception.
  9. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kPresent be ? HasProperty(O, Pk).
    3. If kPresent is true, then
      1. Let kValue be ? Get(O, Pk).
      2. Set accumulator to ? Call(callbackfn, undefined, « accumulator, kValue, 𝔽(k), O »).
    4. Set k to k + 1.
  10. Return accumulator.
 Note 2

The reduce function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.23 Array.prototype.reduceRight ( callbackfn [ , initialValue ] )

Note 1

callbackfn should be a function that takes four arguments. reduceRight calls the callback, as a function, once for each element after the first element present in the array, in descending order.

callbackfn is called with four arguments: the previousValue (value from the previous call to callbackfn), the currentValue (value of the current element), the currentIndex, and the object being traversed. The first time the function is called, the previousValue and currentValue can be one of two values. If an initialValue was supplied in the call to reduceRight, then previousValue will be equal to initialValue and currentValue will be equal to the last value in the array. If no initialValue was supplied, then previousValue will be equal to the last value in the array and currentValue will be equal to the second-to-last value. It is a TypeError if the array contains no elements and initialValue is not provided.

reduceRight does not directly mutate the object on which it is called but the object may be mutated by the calls to callbackfn.

The range of elements processed by reduceRight is set before the first call to callbackfn. Elements that are appended to the array after the call to reduceRight begins will not be visited by callbackfn. If existing elements of the array are changed by callbackfn, their value as passed to callbackfn will be the value at the time reduceRight visits them; elements that are deleted after the call to reduceRight begins and before being visited are not visited.

When the reduceRight method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If IsCallable(callbackfn) is false, throw a TypeError exception.
  4. If len is 0 and initialValue is not present, throw a TypeError exception.
  5. Let k be len - 1.
  6. Let accumulator be undefined.
  7. If initialValue is present, then
    1. Set accumulator to initialValue.
  8. Else,
    1. Let kPresent be false.
    2. Repeat, while kPresent is false and k ≥ 0,
      1. Let Pk be ! ToString(𝔽(k)).
      2. Set kPresent to ? HasProperty(O, Pk).
      3. If kPresent is true, then
        1. Set accumulator to ? Get(O, Pk).
      4. Set k to k - 1.
    3. If kPresent is false, throw a TypeError exception.
  9. Repeat, while k ≥ 0,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kPresent be ? HasProperty(O, Pk).
    3. If kPresent is true, then
      1. Let kValue be ? Get(O, Pk).
      2. Set accumulator to ? Call(callbackfn, undefined, « accumulator, kValue, 𝔽(k), O »).
    4. Set k to k - 1.
  10. Return accumulator.
 Note 2

The reduceRight function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.24 Array.prototype.reverse ( )

Note 1

The elements of the array are rearranged so as to reverse their order. The object is returned as the result of the call.

When the reverse method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let middle be floor(len / 2).
  4. Let lower be 0.
  5. Repeat, while lower ≠ middle,
    1. Let upper be len - lower - 1.
    2. Let upperP be ! ToString(𝔽(upper)).
    3. Let lowerP be ! ToString(𝔽(lower)).
    4. Let lowerExists be ? HasProperty(O, lowerP).
    5. If lowerExists is true, then
      1. Let lowerValue be ? Get(O, lowerP).
    6. Let upperExists be ? HasProperty(O, upperP).
    7. If upperExists is true, then
      1. Let upperValue be ? Get(O, upperP).
    8. If lowerExists is true and upperExists is true, then
      1. Perform ? Set(O, lowerP, upperValue, true).
      2. Perform ? Set(O, upperP, lowerValue, true).
    9. Else if lowerExists is false and upperExists is true, then
      1. Perform ? Set(O, lowerP, upperValue, true).
      2. Perform ? DeletePropertyOrThrow(O, upperP).
    10. Else if lowerExists is true and upperExists is false, then
      1. Perform ? DeletePropertyOrThrow(O, lowerP).
      2. Perform ? Set(O, upperP, lowerValue, true).
    11. Else,
      1. Assert: lowerExists and upperExists are both false.
      2. No action is required.
    12. Set lower to lower + 1.
  6. Return O.
 Note 2

The reverse function is intentionally generic; it does not require that its this value be an Array. Therefore, it can be transferred to other kinds of objects for use as a method.

23.1.3.25 Array.prototype.shift ( )

The first element of the array is removed from the array and returned.

When the shift method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If len = 0, then
    1. Perform ? Set(O, "length", +0𝔽, true).
    2. Return undefined.
  4. Let first be ? Get(O, "0").
  5. Let k be 1.
  6. Repeat, while k < len,
    1. Let from be ! ToString(𝔽(k)).
    2. Let to be ! ToString(𝔽(k - 1)).
    3. Let fromPresent be ? HasProperty(O, from).
    4. If fromPresent is true, then
      1. Let fromVal be ? Get(O, from).
      2. Perform ? Set(O, to, fromVal, true).
    5. Else,
      1. Assert: fromPresent is false.
      2. Perform ? DeletePropertyOrThrow(O, to).
    6. Set k to k + 1.
  7. Perform ? DeletePropertyOrThrow(O, ! ToString(𝔽(len - 1))).
  8. Perform ? Set(O, "length", 𝔽(len - 1), true).
  9. Return first.
 Note

The shift function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.26 Array.prototype.slice ( start, end )

The slice method returns an array containing the elements of the array from element start up to, but not including, element end (or through the end of the array if end is undefined). If start is negative, it is treated as length + start where length is the length of the array. If end is negative, it is treated as length + end where length is the length of the array.

When the slice method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let relativeStart be ? ToIntegerOrInfinity(start).
  4. If relativeStart is -∞, let k be 0.
  5. Else if relativeStart < 0, let k be max(len + relativeStart, 0).
  6. Else, let k be min(relativeStart, len).
  7. If end is undefined, let relativeEnd be len; else let relativeEnd be ? ToIntegerOrInfinity(end).
  8. If relativeEnd is -∞, let final be 0.
  9. Else if relativeEnd < 0, let final be max(len + relativeEnd, 0).
  10. Else, let final be min(relativeEnd, len).
  11. Let count be max(final - k, 0).
  12. Let A be ? ArraySpeciesCreate(O, count).
  13. Let n be 0.
  14. Repeat, while k < final,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kPresent be ? HasProperty(O, Pk).
    3. If kPresent is true, then
      1. Let kValue be ? Get(O, Pk).
      2. Perform ? CreateDataPropertyOrThrow(A, ! ToString(𝔽(n)), kValue).
    4. Set k to k + 1.
    5. Set n to n + 1.
  15. Perform ? Set(A, "length", 𝔽(n), true).
  16. Return A.
 Note 1

The explicit setting of the "length" property of the result Array in step 15 was necessary in previous editions of ECMAScript to ensure that its length was correct in situations where the trailing elements of the result Array were not present. Setting "length" became unnecessary starting in ES2015 when the result Array was initialized to its proper length rather than an empty Array but is carried forward to preserve backward compatibility.

 Note 2

The slice function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.27 Array.prototype.some ( callbackfn [ , thisArg ] )

Note 1

callbackfn should be a function that accepts three arguments and returns a value that is coercible to a Boolean value. some calls callbackfn once for each element present in the array, in ascending order, until it finds one where callbackfn returns true. If such an element is found, some immediately returns true. Otherwise, some returns false. callbackfn is called only for elements of the array which actually exist; it is not called for missing elements of the array.

If a thisArg parameter is provided, it will be used as the this value for each invocation of callbackfn. If it is not provided, undefined is used instead.

callbackfn is called with three arguments: the value of the element, the index of the element, and the object being traversed.

some does not directly mutate the object on which it is called but the object may be mutated by the calls to callbackfn.

The range of elements processed by some is set before the first call to callbackfn. Elements that are appended to the array after the call to some begins will not be visited by callbackfn. If existing elements of the array are changed, their value as passed to callbackfn will be the value at the time that some visits them; elements that are deleted after the call to some begins and before being visited are not visited. some acts like the "exists" quantifier in mathematics. In particular, for an empty array, it returns false.

When the some method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If IsCallable(callbackfn) is false, throw a TypeError exception.
  4. Let k be 0.
  5. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kPresent be ? HasProperty(O, Pk).
    3. If kPresent is true, then
      1. Let kValue be ? Get(O, Pk).
      2. Let testResult be ToBoolean(? Call(callbackfn, thisArg, « kValue, 𝔽(k), O »)).
      3. If testResult is true, return true.
    4. Set k to k + 1.
  6. Return false.
 Note 2

The some function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.28 Array.prototype.sort ( comparefn )

The elements of this array are sorted. The sort must be stable (that is, elements that compare equal must remain in their original order). If comparefn is not undefined, it should be a function that accepts two arguments x and y and returns a negative Number if x < y, a positive Number if x > y, or a zero otherwise.

When the sort method is called, the following steps are taken:

  1. If comparefn is not undefined and IsCallable(comparefn) is false, throw a TypeError exception.
  2. Let obj be ? ToObject(this value).
  3. Let len be ? LengthOfArrayLike(obj).
  4. Let SortCompare be a new Abstract Closure with parameters (x, y) that captures comparefn and performs the following steps when called:
    1. If x and y are both undefined, return +0𝔽.
    2. If x is undefined, return 1𝔽.
    3. If y is undefined, return -1𝔽.
    4. If comparefn is not undefined, then
      1. Let v be ? ToNumber(? Call(comparefn, undefined, « x, y »)).
      2. If v is NaN, return +0𝔽.
      3. Return v.
    5. Let xString be ? ToString(x).
    6. Let yString be ? ToString(y).
    7. Let xSmaller be ! IsLessThan(xString, yString, true).
    8. If xSmaller is true, return -1𝔽.
    9. Let ySmaller be ! IsLessThan(yString, xString, true).
    10. If ySmaller is true, return 1𝔽.
    11. Return +0𝔽.
  5. Return ? SortIndexedProperties(obj, len, SortCompare).
 Note 1

Because non-existent property values always compare greater than undefined property values, and undefined always compares greater than any other value, undefined property values always sort to the end of the result, followed by non-existent property values.

 Note 2

Method calls performed by the ToString abstract operations in steps 4.e and 4.f have the potential to cause SortCompare to not behave as a consistent comparator.

 Note 3

The sort function is intentionally generic; it does not require that its this value be an Array. Therefore, it can be transferred to other kinds of objects for use as a method.

23.1.3.28.1 SortIndexedProperties ( obj, len, SortCompare )

The abstract operation SortIndexedProperties takes arguments obj (an Object), len (a non-negative integer), and SortCompare (an Abstract Closure with two parameters) and returns either a normal completion containing an Object or an abrupt completion. It performs the following steps when called:

  1. Let items be a new empty List.
  2. Let k be 0.
  3. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kPresent be ? HasProperty(obj, Pk).
    3. If kPresent is true, then
      1. Let kValue be ? Get(obj, Pk).
      2. Append kValue to items.
    4. Set k to k + 1.
  4. Let itemCount be the number of elements in items.
  5. Sort items using an implementation-defined sequence of calls to SortCompare. If any such call returns an abrupt completion, stop before performing any further calls to SortCompare and return that Completion Record.
  6. Let j be 0.
  7. Repeat, while j < itemCount,
    1. Perform ? Set(obj, ! ToString(𝔽(j)), items[j], true).
    2. Set j to j + 1.
  8. Repeat, while j < len,
    1. Perform ? DeletePropertyOrThrow(obj, ! ToString(𝔽(j))).
    2. Set j to j + 1.
  9. Return obj.

The sort order is the ordering of items after completion of step 5 of the algorithm above. The sort order is implementation-defined if SortCompare is not a consistent comparator for the elements of items. When SortIndexedProperties is invoked by Array.prototype.sort, the sort order is also implementation-defined if comparefn is undefined, and all applications of ToString, to any specific value passed as an argument to SortCompare, do not produce the same result.

Unless the sort order is specified to be implementation-defined, it must satisfy all of the following conditions:

  • There must be some mathematical permutation π of the non-negative integers less than itemCount, such that for every non-negative integer j less than itemCount, the element old[j] is exactly the same as new[π(j)].
  • Then for all non-negative integers j and k, each less than itemCount, if SortCompare(old[j], old[k]) < 0, then π(j) < π(k).

Here the notation old[j] is used to refer to items[j] before step 5 is executed, and the notation new[j] to refer to items[j] after step 5 has been executed.

An abstract closure or function comparator is a consistent comparator for a set of values S if all of the requirements below are met for all values a, b, and c (possibly the same value) in the set S: The notation a <C b means comparator(a, b) < 0; a =C b means comparator(a, b) = 0 (of either sign); and a >C b means comparator(a, b) > 0.

  • Calling comparator(a, b) always returns the same value v when given a specific pair of values a and b as its two arguments. Furthermore, Type(v) is Number, and v is not NaN. Note that this implies that exactly one of a <C b, a =C b, and a >C b will be true for a given pair of a and b.
  • Calling comparator(a, b) does not modify obj or any object on obj's prototype chain.
  • a =C a (reflexivity)
  • If a =C b, then b =C a (symmetry)
  • If a =C b and b =C c, then a =C c (transitivity of =C)
  • If a <C b and b <C c, then a <C c (transitivity of <C)
  • If a >C b and b >C c, then a >C c (transitivity of >C)
Note

The above conditions are necessary and sufficient to ensure that comparator divides the set S into equivalence classes and that these equivalence classes are totally ordered.

23.1.3.29 Array.prototype.splice ( start, deleteCount, ...items )

Note 1

The deleteCount elements of the array starting at integer index start are replaced by the elements of items. An Array containing the deleted elements (if any) is returned.

When the splice method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let relativeStart be ? ToIntegerOrInfinity(start).
  4. If relativeStart is -∞, let actualStart be 0.
  5. Else if relativeStart < 0, let actualStart be max(len + relativeStart, 0).
  6. Else, let actualStart be min(relativeStart, len).
  7. Let insertCount be the number of elements in items.
  8. If start is not present, then
    1. Let actualDeleteCount be 0.
  9. Else if deleteCount is not present, then
    1. Let actualDeleteCount be len - actualStart.
  10. Else,
    1. Let dc be ? ToIntegerOrInfinity(deleteCount).
    2. Let actualDeleteCount be the result of clamping dc between 0 and len - actualStart.
  11. If len + insertCount - actualDeleteCount > 253 - 1, throw a TypeError exception.
  12. Let A be ? ArraySpeciesCreate(O, actualDeleteCount).
  13. Let k be 0.
  14. Repeat, while k < actualDeleteCount,
    1. Let from be ! ToString(𝔽(actualStart + k)).
    2. If ? HasProperty(O, from) is true, then
      1. Let fromValue be ? Get(O, from).
      2. Perform ? CreateDataPropertyOrThrow(A, ! ToString(𝔽(k)), fromValue).
    3. Set k to k + 1.
  15. Perform ? Set(A, "length", 𝔽(actualDeleteCount), true).
  16. Let itemCount be the number of elements in items.
  17. If itemCount < actualDeleteCount, then
    1. Set k to actualStart.
    2. Repeat, while k < (len - actualDeleteCount),
      1. Let from be ! ToString(𝔽(k + actualDeleteCount)).
      2. Let to be ! ToString(𝔽(k + itemCount)).
      3. If ? HasProperty(O, from) is true, then
        1. Let fromValue be ? Get(O, from).
        2. Perform ? Set(O, to, fromValue, true).
      4. Else,
        1. Perform ? DeletePropertyOrThrow(O, to).
      5. Set k to k + 1.
    3. Set k to len.
    4. Repeat, while k > (len - actualDeleteCount + itemCount),
      1. Perform ? DeletePropertyOrThrow(O, ! ToString(𝔽(k - 1))).
      2. Set k to k - 1.
  18. Else if itemCount > actualDeleteCount, then
    1. Set k to (len - actualDeleteCount).
    2. Repeat, while k > actualStart,
      1. Let from be ! ToString(𝔽(k + actualDeleteCount - 1)).
      2. Let to be ! ToString(𝔽(k + itemCount - 1)).
      3. If ? HasProperty(O, from) is true, then
        1. Let fromValue be ? Get(O, from).
        2. Perform ? Set(O, to, fromValue, true).
      4. Else,
        1. Perform ? DeletePropertyOrThrow(O, to).
      5. Set k to k - 1.
  19. Set k to actualStart.
  20. For each element E of items, do
    1. Perform ? Set(O, ! ToString(𝔽(k)), E, true).
    2. Set k to k + 1.
  21. Perform ? Set(O, "length", 𝔽(len - actualDeleteCount + itemCount), true).
  22. Return A.
 Note 2

The explicit setting of the "length" property of the result Array in step 21 was necessary in previous editions of ECMAScript to ensure that its length was correct in situations where the trailing elements of the result Array were not present. Setting "length" became unnecessary starting in ES2015 when the result Array was initialized to its proper length rather than an empty Array but is carried forward to preserve backward compatibility.

 Note 3

The splice function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.30 Array.prototype.toLocaleString ( [ reserved1 [ , reserved2 ] ] )

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the Array.prototype.toLocaleString method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of the toLocaleString method is used.

Note 1

The first edition of ECMA-402 did not include a replacement specification for the Array.prototype.toLocaleString method.

The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.

When the toLocaleString method is called, the following steps are taken:

  1. Let array be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(array).
  3. Let separator be the implementation-defined list-separator String value appropriate for the host environment's current locale (such as ", ").
  4. Let R be the empty String.
  5. Let k be 0.
  6. Repeat, while k < len,
    1. If k > 0, then
      1. Set R to the string-concatenation of R and separator.
    2. Let nextElement be ? Get(array, ! ToString(𝔽(k))).
    3. If nextElement is not undefined or null, then
      1. Let S be ? ToString(? Invoke(nextElement, "toLocaleString")).
      2. Set R to the string-concatenation of R and S.
    4. Set k to k + 1.
  7. Return R.
 Note 2

The elements of the array are converted to Strings using their toLocaleString methods, and these Strings are then concatenated, separated by occurrences of an implementation-defined locale-sensitive separator String. This function is analogous to toString except that it is intended to yield a locale-sensitive result corresponding with conventions of the host environment's current locale.

 Note 3

The toLocaleString function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.31 Array.prototype.toString ( )

When the toString method is called, the following steps are taken:

  1. Let array be ? ToObject(this value).
  2. Let func be ? Get(array, "join").
  3. If IsCallable(func) is false, set func to the intrinsic function %Object.prototype.toString%.
  4. Return ? Call(func, array).
 Note

The toString function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.32 Array.prototype.unshift ( ...items )

The arguments are prepended to the start of the array, such that their order within the array is the same as the order in which they appear in the argument list.

When the unshift method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let argCount be the number of elements in items.
  4. If argCount > 0, then
    1. If len + argCount > 253 - 1, throw a TypeError exception.
    2. Let k be len.
    3. Repeat, while k > 0,
      1. Let from be ! ToString(𝔽(k - 1)).
      2. Let to be ! ToString(𝔽(k + argCount - 1)).
      3. Let fromPresent be ? HasProperty(O, from).
      4. If fromPresent is true, then
        1. Let fromValue be ? Get(O, from).
        2. Perform ? Set(O, to, fromValue, true).
      5. Else,
        1. Assert: fromPresent is false.
        2. Perform ? DeletePropertyOrThrow(O, to).
      6. Set k to k - 1.
    4. Let j be +0𝔽.
    5. For each element E of items, do
      1. Perform ? Set(O, ! ToString(j), E, true).
      2. Set j to j + 1𝔽.
  5. Perform ? Set(O, "length", 𝔽(len + argCount), true).
  6. Return 𝔽(len + argCount).

The "length" property of the unshift method is 1𝔽.

Note

The unshift function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.33 Array.prototype.values ( )

When the values method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Return CreateArrayIterator(O, value).

23.1.3.34 Array.prototype [ @@iterator ] ( )

The initial value of the @@iterator property is %Array.prototype.values%, defined in 23.1.3.33.

23.1.3.35 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.

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

Note

The own property names of this object are property names that were not included as standard properties of Array.prototype prior to the ECMAScript 2015 specification. These names are ignored for with statement binding purposes in order to preserve the behaviour of existing code that might use one of these names as a binding in an outer scope that is shadowed by a with statement whose binding object is an Array.

23.1.4 Properties of Array Instances

Array instances are Array exotic objects and have the internal methods specified for such objects. Array instances inherit properties from the Array prototype object.

Array instances have a "length" property, and a set of enumerable properties with array index names.

23.1.4.1 length

The "length" property of an Array instance is a data property whose value is always numerically greater than the name of every configurable own property whose name is an array index.

The "length" property initially has the attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false }.

Note

Reducing the value of the "length" property has the side-effect of deleting own array elements whose array index is between the old and new length values. However, non-configurable properties can not be deleted. Attempting to set the "length" property of an Array to a value that is numerically less than or equal to the largest numeric own property name of an existing non-configurable array-indexed property of the array will result in the length being set to a numeric value that is one greater than that non-configurable numeric own property name. See 10.4.2.1.

23.1.5 Array Iterator Objects

An Array Iterator is an object, that represents a specific iteration over some specific Array instance object. There is not a named constructor for Array Iterator objects. Instead, Array iterator objects are created by calling certain methods of Array instance objects.

23.1.5.1 CreateArrayIterator ( array, kind )

The abstract operation CreateArrayIterator takes arguments array (an Object) and kind (key+value, key, or value) and returns a Generator. It is used to create iterator objects for Array methods that return such iterators. It performs the following steps when called:

  1. Let closure be a new Abstract Closure with no parameters that captures kind and array and performs the following steps when called:
    1. Let index be 0.
    2. Repeat,
      1. If array has a [[TypedArrayName]] internal slot, then
        1. If IsDetachedBuffer(array.[[ViewedArrayBuffer]]) is true, throw a TypeError exception.
        2. Let len be array.[[ArrayLength]].
      2. Else,
        1. Let len be ? LengthOfArrayLike(array).
      3. If index ≥ len, return undefined.
      4. If kind is key, perform ? GeneratorYield(CreateIterResultObject(𝔽(index), false)).
      5. Else,
        1. Let elementKey be ! ToString(𝔽(index)).
        2. Let elementValue be ? Get(array, elementKey).
        3. If kind is value, perform ? GeneratorYield(CreateIterResultObject(elementValue, false)).
        4. Else,
          1. Assert: kind is key+value.
          2. Let result be CreateArrayFromList(« 𝔽(index), elementValue »).
          3. Perform ? GeneratorYield(CreateIterResultObject(result, false)).
      6. Set index to index + 1.
  2. Return CreateIteratorFromClosure(closure, "%ArrayIteratorPrototype%", %ArrayIteratorPrototype%).

23.1.5.2 The %ArrayIteratorPrototype% Object

The %ArrayIteratorPrototype% object:

  • has properties that are inherited by all Array Iterator Objects.
  • is an ordinary object.
  • has a [[Prototype]] internal slot whose value is %IteratorPrototype%.
  • has the following properties:

23.1.5.2.1 %ArrayIteratorPrototype%.next ( )

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

23.1.5.2.2 %ArrayIteratorPrototype% [ @@toStringTag ]

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

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

23.2 TypedArray Objects

A TypedArray presents an array-like view of an underlying binary data buffer (25.1). A TypedArray element type is the underlying binary scalar data type that all elements of a TypedArray instance have. There is a distinct TypedArray constructor, listed in Table 71, for each of the supported element types. Each constructor in Table 71 has a corresponding distinct prototype object.

Constructor Name and Intrinsic Element Type Element Size Conversion Operation Description
Int8Array
%Int8Array% 		Int8 1 ToInt8 8-bit two's complement signed integer
Uint8Array
%Uint8Array% 		Uint8 1 ToUint8 8-bit unsigned integer
Uint8ClampedArray
%Uint8ClampedArray% 		Uint8C 1 ToUint8Clamp 8-bit unsigned integer (clamped conversion)
Int16Array
%Int16Array% 		Int16 2 ToInt16 16-bit two's complement signed integer
Uint16Array
%Uint16Array% 		Uint16 2 ToUint16 16-bit unsigned integer
Int32Array
%Int32Array% 		Int32 4 ToInt32 32-bit two's complement signed integer
Uint32Array
%Uint32Array% 		Uint32 4 ToUint32 32-bit unsigned integer
BigInt64Array
%BigInt64Array% 		BigInt64 8 ToBigInt64 64-bit two's complement signed integer
BigUint64Array
%BigUint64Array% 		BigUint64 8 ToBigUint64 64-bit unsigned integer
Float32Array
%Float32Array% 		Float32 4 32-bit IEEE floating point
Float64Array
%Float64Array% 		Float64 8 64-bit IEEE floating point

In the definitions below, references to TypedArray should be replaced with the appropriate constructor name from the above table.

23.2.1 The %TypedArray% Intrinsic Object

The %TypedArray% intrinsic object:

  • is a constructor function object that all of the TypedArray constructor objects inherit from.
  • along with its corresponding prototype object, provides common properties that are inherited by all TypedArray constructors and their instances.
  • does not have a global name or appear as a property of the global object.
  • acts as the abstract superclass of the various TypedArray constructors.
  • will throw an error when invoked, because it is an abstract class constructor. The TypedArray constructors do not perform a super call to it.

23.2.1.1 %TypedArray% ( )

The %TypedArray% constructor performs the following steps when called:

  1. Throw a TypeError exception.

The "length" property of the %TypedArray% constructor function is +0𝔽.

23.2.2 Properties of the %TypedArray% Intrinsic Object

The %TypedArray% intrinsic object:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has a "name" property whose value is "TypedArray".
  • has the following properties:

23.2.2.1 %TypedArray%.from ( source [ , mapfn [ , thisArg ] ] )

When the from method is called, the following steps are taken:

  1. Let C be the this value.
  2. If IsConstructor(C) is false, throw a TypeError exception.
  3. If mapfn is undefined, let mapping be false.
  4. Else,
    1. If IsCallable(mapfn) is false, throw a TypeError exception.
    2. Let mapping be true.
  5. Let usingIterator be ? GetMethod(source, @@iterator).
  6. If usingIterator is not undefined, then
    1. Let values be ? IterableToList(source, usingIterator).
    2. Let len be the number of elements in values.
    3. Let targetObj be ? TypedArrayCreate(C, « 𝔽(len) »).
    4. Let k be 0.
    5. Repeat, while k < len,
      1. Let Pk be ! ToString(𝔽(k)).
      2. Let kValue be the first element of values and remove that element from values.
      3. If mapping is true, then
        1. Let mappedValue be ? Call(mapfn, thisArg, « kValue, 𝔽(k) »).
      4. Else, let mappedValue be kValue.
      5. Perform ? Set(targetObj, Pk, mappedValue, true).
      6. Set k to k + 1.
    6. Assert: values is now an empty List.
    7. Return targetObj.
  7. NOTE: source is not an Iterable so assume it is already an array-like object.
  8. Let arrayLike be ! ToObject(source).
  9. Let len be ? LengthOfArrayLike(arrayLike).
  10. Let targetObj be ? TypedArrayCreate(C, « 𝔽(len) »).
  11. Let k be 0.
  12. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ? Get(arrayLike, Pk).
    3. If mapping is true, then
      1. Let mappedValue be ? Call(mapfn, thisArg, « kValue, 𝔽(k) »).
    4. Else, let mappedValue be kValue.
    5. Perform ? Set(targetObj, Pk, mappedValue, true).
    6. Set k to k + 1.
  13. Return targetObj.

23.2.2.2 %TypedArray%.of ( ...items )

When the of method is called, the following steps are taken:

  1. Let len be the number of elements in items.
  2. Let C be the this value.
  3. If IsConstructor(C) is false, throw a TypeError exception.
  4. Let newObj be ? TypedArrayCreate(C, « 𝔽(len) »).
  5. Let k be 0.
  6. Repeat, while k < len,
    1. Let kValue be items[k].
    2. Let Pk be ! ToString(𝔽(k)).
    3. Perform ? Set(newObj, Pk, kValue, true).
    4. Set k to k + 1.
  7. Return newObj.

23.2.2.3 %TypedArray%.prototype

The initial value of %TypedArray%.prototype is the %TypedArray% prototype object.

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

23.2.2.4 get %TypedArray% [ @@species ]

%TypedArray%[@@species] is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Return the this value.

The value of the "name" property of this function is "get [Symbol.species]".

Note

%TypedArray.prototype% methods normally use their this value's constructor to create a derived object. However, a subclass constructor may over-ride that default behaviour by redefining its @@species property.

23.2.3 Properties of the %TypedArray% Prototype Object

The %TypedArray% prototype object:

  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is %TypedArray.prototype%.
  • is an ordinary object.
  • does not have a [[ViewedArrayBuffer]] or any other of the internal slots that are specific to TypedArray instance objects.

23.2.3.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 ? ToIntegerOrInfinity(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, return undefined.
  8. Return ! Get(O, ! ToString(𝔽(k))).

23.2.3.2 get %TypedArray%.prototype.buffer

%TypedArray%.prototype.buffer is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[TypedArrayName]]).
  3. Assert: O has a [[ViewedArrayBuffer]] internal slot.
  4. Let buffer be O.[[ViewedArrayBuffer]].
  5. Return buffer.

23.2.3.3 get %TypedArray%.prototype.byteLength

%TypedArray%.prototype.byteLength is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[TypedArrayName]]).
  3. Assert: O has a [[ViewedArrayBuffer]] internal slot.
  4. Let buffer be O.[[ViewedArrayBuffer]].
  5. If IsDetachedBuffer(buffer) is true, return +0𝔽.
  6. Let size be O.[[ByteLength]].
  7. Return 𝔽(size).

23.2.3.4 get %TypedArray%.prototype.byteOffset

%TypedArray%.prototype.byteOffset is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[TypedArrayName]]).
  3. Assert: O has a [[ViewedArrayBuffer]] internal slot.
  4. Let buffer be O.[[ViewedArrayBuffer]].
  5. If IsDetachedBuffer(buffer) is true, return +0𝔽.
  6. Let offset be O.[[ByteOffset]].
  7. Return 𝔽(offset).

23.2.3.5 %TypedArray%.prototype.constructor

The initial value of %TypedArray%.prototype.constructor is %TypedArray%.

23.2.3.6 %TypedArray%.prototype.copyWithin ( target, start [ , end ] )

The interpretation and use of the arguments of %TypedArray%.prototype.copyWithin are the same as for Array.prototype.copyWithin as defined in 23.1.3.4.

When the copyWithin method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. Let relativeTarget be ? ToIntegerOrInfinity(target).
  5. If relativeTarget is -∞, let to be 0.
  6. Else if relativeTarget < 0, let to be max(len + relativeTarget, 0).
  7. Else, let to be min(relativeTarget, len).
  8. Let relativeStart be ? ToIntegerOrInfinity(start).
  9. If relativeStart is -∞, let from be 0.
  10. Else if relativeStart < 0, let from be max(len + relativeStart, 0).
  11. Else, let from be min(relativeStart, len).
  12. If end is undefined, let relativeEnd be len; else let relativeEnd be ? ToIntegerOrInfinity(end).
  13. If relativeEnd is -∞, let final be 0.
  14. Else if relativeEnd < 0, let final be max(len + relativeEnd, 0).
  15. Else, let final be min(relativeEnd, len).
  16. Let count be min(final - from, len - to).
  17. If count > 0, then
    1. NOTE: The copying must be performed in a manner that preserves the bit-level encoding of the source data.
    2. Let buffer be O.[[ViewedArrayBuffer]].
    3. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
    4. Let elementSize be TypedArrayElementSize(O).
    5. Let byteOffset be O.[[ByteOffset]].
    6. Let toByteIndex be to × elementSize + byteOffset.
    7. Let fromByteIndex be from × elementSize + byteOffset.
    8. Let countBytes be count × elementSize.
    9. If fromByteIndex < toByteIndex and toByteIndex < fromByteIndex + countBytes, then
      1. Let direction be -1.
      2. Set fromByteIndex to fromByteIndex + countBytes - 1.
      3. Set toByteIndex to toByteIndex + countBytes - 1.
    10. Else,
      1. Let direction be 1.
    11. Repeat, while countBytes > 0,
      1. Let value be GetValueFromBuffer(buffer, fromByteIndex, Uint8, true, Unordered).
      2. Perform SetValueInBuffer(buffer, toByteIndex, Uint8, value, true, Unordered).
      3. Set fromByteIndex to fromByteIndex + direction.
      4. Set toByteIndex to toByteIndex + direction.
      5. Set countBytes to countBytes - 1.
  18. Return O.

23.2.3.7 %TypedArray%.prototype.entries ( )

When the entries method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Return CreateArrayIterator(O, key+value).

23.2.3.8 %TypedArray%.prototype.every ( callbackfn [ , thisArg ] )

The interpretation and use of the arguments of %TypedArray%.prototype.every are the same as for Array.prototype.every as defined in 23.1.3.6.

When the every method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If IsCallable(callbackfn) is false, throw a TypeError exception.
  5. Let k be 0.
  6. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ! Get(O, Pk).
    3. Let testResult be ToBoolean(? Call(callbackfn, thisArg, « kValue, 𝔽(k), O »)).
    4. If testResult is false, return false.
    5. Set k to k + 1.
  7. Return true.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.9 %TypedArray%.prototype.fill ( value [ , start [ , end ] ] )

The interpretation and use of the arguments of %TypedArray%.prototype.fill are the same as for Array.prototype.fill as defined in 23.1.3.7.

When the fill method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If O.[[ContentType]] is BigInt, set value to ? ToBigInt(value).
  5. Otherwise, set value to ? ToNumber(value).
  6. Let relativeStart be ? ToIntegerOrInfinity(start).
  7. If relativeStart is -∞, let k be 0.
  8. Else if relativeStart < 0, let k be max(len + relativeStart, 0).
  9. Else, let k be min(relativeStart, len).
  10. If end is undefined, let relativeEnd be len; else let relativeEnd be ? ToIntegerOrInfinity(end).
  11. If relativeEnd is -∞, let final be 0.
  12. Else if relativeEnd < 0, let final be max(len + relativeEnd, 0).
  13. Else, let final be min(relativeEnd, len).
  14. If IsDetachedBuffer(O.[[ViewedArrayBuffer]]) is true, throw a TypeError exception.
  15. Repeat, while k < final,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Perform ! Set(O, Pk, value, true).
    3. Set k to k + 1.
  16. Return O.

23.2.3.10 %TypedArray%.prototype.filter ( callbackfn [ , thisArg ] )

The interpretation and use of the arguments of %TypedArray%.prototype.filter are the same as for Array.prototype.filter as defined in 23.1.3.8.

When the filter method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If IsCallable(callbackfn) is false, throw a TypeError exception.
  5. Let kept be a new empty List.
  6. Let k be 0.
  7. Let captured be 0.
  8. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ! Get(O, Pk).
    3. Let selected be ToBoolean(? Call(callbackfn, thisArg, « kValue, 𝔽(k), O »)).
    4. If selected is true, then
      1. Append kValue to the end of kept.
      2. Set captured to captured + 1.
    5. Set k to k + 1.
  9. Let A be ? TypedArraySpeciesCreate(O, « 𝔽(captured) »).
  10. Let n be 0.
  11. For each element e of kept, do
    1. Perform ! Set(A, ! ToString(𝔽(n)), e, true).
    2. Set n to n + 1.
  12. Return A.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.11 %TypedArray%.prototype.find ( predicate [ , thisArg ] )

The interpretation and use of the arguments of %TypedArray%.prototype.find are the same as for Array.prototype.find as defined in 23.1.3.9.

When the find method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If IsCallable(predicate) is false, throw a TypeError exception.
  5. Let k be 0.
  6. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ! Get(O, Pk).
    3. Let testResult be ToBoolean(? Call(predicate, thisArg, « kValue, 𝔽(k), O »)).
    4. If testResult is true, return kValue.
    5. Set k to k + 1.
  7. Return undefined.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.12 %TypedArray%.prototype.findIndex ( predicate [ , thisArg ] )

The interpretation and use of the arguments of %TypedArray%.prototype.findIndex are the same as for Array.prototype.findIndex as defined in 23.1.3.10.

When the findIndex method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If IsCallable(predicate) is false, throw a TypeError exception.
  5. Let k be 0.
  6. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ! Get(O, Pk).
    3. Let testResult be ToBoolean(? Call(predicate, thisArg, « kValue, 𝔽(k), O »)).
    4. If testResult is true, return 𝔽(k).
    5. Set k to k + 1.
  7. Return -1𝔽.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.13 %TypedArray%.prototype.forEach ( callbackfn [ , thisArg ] )

The interpretation and use of the arguments of %TypedArray%.prototype.forEach are the same as for Array.prototype.forEach as defined in 23.1.3.13.

When the forEach method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If IsCallable(callbackfn) is false, throw a TypeError exception.
  5. Let k be 0.
  6. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ! Get(O, Pk).
    3. Perform ? Call(callbackfn, thisArg, « kValue, 𝔽(k), O »).
    4. Set k to k + 1.
  7. Return undefined.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.14 %TypedArray%.prototype.includes ( searchElement [ , fromIndex ] )

The interpretation and use of the arguments of %TypedArray%.prototype.includes are the same as for Array.prototype.includes as defined in 23.1.3.14.

When the includes method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If len is 0, return false.
  5. Let n be ? ToIntegerOrInfinity(fromIndex).
  6. Assert: If fromIndex is undefined, then n is 0.
  7. If n is +∞, return false.
  8. Else if n is -∞, set n to 0.
  9. If n ≥ 0, then
    1. Let k be n.
  10. Else,
    1. Let k be len + n.
    2. If k < 0, set k to 0.
  11. Repeat, while k < len,
    1. Let elementK be ! Get(O, ! ToString(𝔽(k))).
    2. If SameValueZero(searchElement, elementK) is true, return true.
    3. Set k to k + 1.
  12. Return false.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.15 %TypedArray%.prototype.indexOf ( searchElement [ , fromIndex ] )

The interpretation and use of the arguments of %TypedArray%.prototype.indexOf are the same as for Array.prototype.indexOf as defined in 23.1.3.15.

When the indexOf method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If len is 0, return -1𝔽.
  5. Let n be ? ToIntegerOrInfinity(fromIndex).
  6. Assert: If fromIndex is undefined, then n is 0.
  7. If n is +∞, return -1𝔽.
  8. Else if n is -∞, set n to 0.
  9. If n ≥ 0, then
    1. Let k be n.
  10. Else,
    1. Let k be len + n.
    2. If k < 0, set k to 0.
  11. Repeat, while k < len,
    1. Let kPresent be ! HasProperty(O, ! ToString(𝔽(k))).
    2. If kPresent is true, then
      1. Let elementK be ! Get(O, ! ToString(𝔽(k))).
      2. Let same be IsStrictlyEqual(searchElement, elementK).
      3. If same is true, return 𝔽(k).
    3. Set k to k + 1.
  12. Return -1𝔽.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.16 %TypedArray%.prototype.join ( separator )

The interpretation and use of the arguments of %TypedArray%.prototype.join are the same as for Array.prototype.join as defined in 23.1.3.16.

When the join method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If separator is undefined, let sep be the single-element String ",".
  5. Else, let sep be ? ToString(separator).
  6. Let R be the empty String.
  7. Let k be 0.
  8. Repeat, while k < len,
    1. If k > 0, set R to the string-concatenation of R and sep.
    2. Let element be ! Get(O, ! ToString(𝔽(k))).
    3. If element is undefined, let next be the empty String; otherwise, let next be ! ToString(element).
    4. Set R to the string-concatenation of R and next.
    5. Set k to k + 1.
  9. Return R.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.17 %TypedArray%.prototype.keys ( )

When the keys method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Return CreateArrayIterator(O, key).

23.2.3.18 %TypedArray%.prototype.lastIndexOf ( searchElement [ , fromIndex ] )

The interpretation and use of the arguments of %TypedArray%.prototype.lastIndexOf are the same as for Array.prototype.lastIndexOf as defined in 23.1.3.18.

When the lastIndexOf method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If len is 0, return -1𝔽.
  5. If fromIndex is present, let n be ? ToIntegerOrInfinity(fromIndex); else let n be len - 1.
  6. If n is -∞, return -1𝔽.
  7. If n ≥ 0, then
    1. Let k be min(n, len - 1).
  8. Else,
    1. Let k be len + n.
  9. Repeat, while k ≥ 0,
    1. Let kPresent be ! HasProperty(O, ! ToString(𝔽(k))).
    2. If kPresent is true, then
      1. Let elementK be ! Get(O, ! ToString(𝔽(k))).
      2. Let same be IsStrictlyEqual(searchElement, elementK).
      3. If same is true, return 𝔽(k).
    3. Set k to k - 1.
  10. Return -1𝔽.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.19 get %TypedArray%.prototype.length

%TypedArray%.prototype.length is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[TypedArrayName]]).
  3. Assert: O has [[ViewedArrayBuffer]] and [[ArrayLength]] internal slots.
  4. Let buffer be O.[[ViewedArrayBuffer]].
  5. If IsDetachedBuffer(buffer) is true, return +0𝔽.
  6. Let length be O.[[ArrayLength]].
  7. Return 𝔽(length).

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.20 %TypedArray%.prototype.map ( callbackfn [ , thisArg ] )

The interpretation and use of the arguments of %TypedArray%.prototype.map are the same as for Array.prototype.map as defined in 23.1.3.19.

When the map method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If IsCallable(callbackfn) is false, throw a TypeError exception.
  5. Let A be ? TypedArraySpeciesCreate(O, « 𝔽(len) »).
  6. Let k be 0.
  7. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ! Get(O, Pk).
    3. Let mappedValue be ? Call(callbackfn, thisArg, « kValue, 𝔽(k), O »).
    4. Perform ? Set(A, Pk, mappedValue, true).
    5. Set k to k + 1.
  8. Return A.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.21 %TypedArray%.prototype.reduce ( callbackfn [ , initialValue ] )

The interpretation and use of the arguments of %TypedArray%.prototype.reduce are the same as for Array.prototype.reduce as defined in 23.1.3.22.

When the reduce method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If IsCallable(callbackfn) is false, throw a TypeError exception.
  5. If len = 0 and initialValue is not present, throw a TypeError exception.
  6. Let k be 0.
  7. Let accumulator be undefined.
  8. If initialValue is present, then
    1. Set accumulator to initialValue.
  9. Else,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Set accumulator to ! Get(O, Pk).
    3. Set k to k + 1.
  10. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ! Get(O, Pk).
    3. Set accumulator to ? Call(callbackfn, undefined, « accumulator, kValue, 𝔽(k), O »).
    4. Set k to k + 1.
  11. Return accumulator.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.22 %TypedArray%.prototype.reduceRight ( callbackfn [ , initialValue ] )

The interpretation and use of the arguments of %TypedArray%.prototype.reduceRight are the same as for Array.prototype.reduceRight as defined in 23.1.3.23.

When the reduceRight method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If IsCallable(callbackfn) is false, throw a TypeError exception.
  5. If len is 0 and initialValue is not present, throw a TypeError exception.
  6. Let k be len - 1.
  7. Let accumulator be undefined.
  8. If initialValue is present, then
    1. Set accumulator to initialValue.
  9. Else,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Set accumulator to ! Get(O, Pk).
    3. Set k to k - 1.
  10. Repeat, while k ≥ 0,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ! Get(O, Pk).
    3. Set accumulator to ? Call(callbackfn, undefined, « accumulator, kValue, 𝔽(k), O »).
    4. Set k to k - 1.
  11. Return accumulator.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.23 %TypedArray%.prototype.reverse ( )

The interpretation and use of the arguments of %TypedArray%.prototype.reverse are the same as for Array.prototype.reverse as defined in 23.1.3.24.

When the reverse method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. Let middle be floor(len / 2).
  5. Let lower be 0.
  6. Repeat, while lower ≠ middle,
    1. Let upper be len - lower - 1.
    2. Let upperP be ! ToString(𝔽(upper)).
    3. Let lowerP be ! ToString(𝔽(lower)).
    4. Let lowerValue be ! Get(O, lowerP).
    5. Let upperValue be ! Get(O, upperP).
    6. Perform ! Set(O, lowerP, upperValue, true).
    7. Perform ! Set(O, upperP, lowerValue, true).
    8. Set lower to lower + 1.
  7. Return O.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.24 %TypedArray%.prototype.set ( source [ , offset ] )

%TypedArray%.prototype.set is a function whose behaviour differs based upon the type of its first argument.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

Sets multiple values in this TypedArray, reading the values from source. The optional offset value indicates the first element index in this TypedArray where values are written. If omitted, it is assumed to be 0.

When the set method is called, the following steps are taken:

  1. Let target be the this value.
  2. Perform ? RequireInternalSlot(target, [[TypedArrayName]]).
  3. Assert: target has a [[ViewedArrayBuffer]] internal slot.
  4. Let targetOffset be ? ToIntegerOrInfinity(offset).
  5. If targetOffset < 0, throw a RangeError exception.
  6. If source is an Object that has a [[TypedArrayName]] internal slot, then
    1. Perform ? SetTypedArrayFromTypedArray(target, targetOffset, source).
  7. Else,
    1. Perform ? SetTypedArrayFromArrayLike(target, targetOffset, source).
  8. Return undefined.

23.2.3.24.1 SetTypedArrayFromTypedArray ( target, targetOffset, source )

The abstract operation SetTypedArrayFromTypedArray takes arguments target (a TypedArray), targetOffset (a non-negative integer or +∞), and source (a TypedArray) and returns either a normal completion containing unused or an abrupt completion. It sets multiple values in target, starting at index targetOffset, reading the values from source. It performs the following steps when called:

  1. Let targetBuffer be target.[[ViewedArrayBuffer]].
  2. If IsDetachedBuffer(targetBuffer) is true, throw a TypeError exception.
  3. Let targetLength be target.[[ArrayLength]].
  4. Let srcBuffer be source.[[ViewedArrayBuffer]].
  5. If IsDetachedBuffer(srcBuffer) is true, throw a TypeError exception.
  6. Let targetType be TypedArrayElementType(target).
  7. Let targetElementSize be TypedArrayElementSize(target).
  8. Let targetByteOffset be target.[[ByteOffset]].
  9. Let srcType be TypedArrayElementType(source).
  10. Let srcElementSize be TypedArrayElementSize(source).
  11. Let srcLength be source.[[ArrayLength]].
  12. Let srcByteOffset be source.[[ByteOffset]].
  13. If targetOffset is +∞, throw a RangeError exception.
  14. If srcLength + targetOffset > targetLength, throw a RangeError exception.
  15. If target.[[ContentType]] ≠ source.[[ContentType]], throw a TypeError exception.
  16. If both IsSharedArrayBuffer(srcBuffer) and IsSharedArrayBuffer(targetBuffer) are true, then
    1. If srcBuffer.[[ArrayBufferData]] and targetBuffer.[[ArrayBufferData]] are the same Shared Data Block values, let same be true; else let same be false.
  17. Else, let same be SameValue(srcBuffer, targetBuffer).
  18. If same is true, then
    1. Let srcByteLength be source.[[ByteLength]].
    2. Set srcBuffer to ? CloneArrayBuffer(srcBuffer, srcByteOffset, srcByteLength, %ArrayBuffer%).
    3. NOTE: %ArrayBuffer% is used to clone srcBuffer because is it known to not have any observable side-effects.
    4. Let srcByteIndex be 0.
  19. Else, let srcByteIndex be srcByteOffset.
  20. Let targetByteIndex be targetOffset × targetElementSize + targetByteOffset.
  21. Let limit be targetByteIndex + targetElementSize × srcLength.
  22. If srcType is the same as targetType, then
    1. NOTE: If srcType and targetType are the same, the transfer must be performed in a manner that preserves the bit-level encoding of the source data.
    2. Repeat, while targetByteIndex < limit,
      1. Let value be GetValueFromBuffer(srcBuffer, srcByteIndex, Uint8, true, Unordered).
      2. Perform SetValueInBuffer(targetBuffer, targetByteIndex, Uint8, value, true, Unordered).
      3. Set srcByteIndex to srcByteIndex + 1.
      4. Set targetByteIndex to targetByteIndex + 1.
  23. Else,
    1. Repeat, while targetByteIndex < limit,
      1. Let value be GetValueFromBuffer(srcBuffer, srcByteIndex, srcType, true, Unordered).
      2. Perform SetValueInBuffer(targetBuffer, targetByteIndex, targetType, value, true, Unordered).
      3. Set srcByteIndex to srcByteIndex + srcElementSize.
      4. Set targetByteIndex to targetByteIndex + targetElementSize.
  24. Return unused.

23.2.3.24.2 SetTypedArrayFromArrayLike ( target, targetOffset, source )

The abstract operation SetTypedArrayFromArrayLike takes arguments target (a TypedArray), targetOffset (a non-negative integer or +∞), and source (an ECMAScript language value, but not a TypedArray) and returns either a normal completion containing unused or an abrupt completion. It sets multiple values in target, starting at index targetOffset, reading the values from source. It performs the following steps when called:

  1. Let targetBuffer be target.[[ViewedArrayBuffer]].
  2. If IsDetachedBuffer(targetBuffer) is true, throw a TypeError exception.
  3. Let targetLength be target.[[ArrayLength]].
  4. Let targetElementSize be TypedArrayElementSize(target).
  5. Let targetType be TypedArrayElementType(target).
  6. Let targetByteOffset be target.[[ByteOffset]].
  7. Let src be ? ToObject(source).
  8. Let srcLength be ? LengthOfArrayLike(src).
  9. If targetOffset is +∞, throw a RangeError exception.
  10. If srcLength + targetOffset > targetLength, throw a RangeError exception.
  11. Let targetByteIndex be targetOffset × targetElementSize + targetByteOffset.
  12. Let k be 0.
  13. Let limit be targetByteIndex + targetElementSize × srcLength.
  14. Repeat, while targetByteIndex < limit,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let value be ? Get(src, Pk).
    3. If target.[[ContentType]] is BigInt, set value to ? ToBigInt(value).
    4. Otherwise, set value to ? ToNumber(value).
    5. If IsDetachedBuffer(targetBuffer) is true, throw a TypeError exception.
    6. Perform SetValueInBuffer(targetBuffer, targetByteIndex, targetType, value, true, Unordered).
    7. Set k to k + 1.
    8. Set targetByteIndex to targetByteIndex + targetElementSize.
  15. Return unused.

23.2.3.25 %TypedArray%.prototype.slice ( start, end )

The interpretation and use of the arguments of %TypedArray%.prototype.slice are the same as for Array.prototype.slice as defined in 23.1.3.26. The following steps are taken:

When the slice method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. Let relativeStart be ? ToIntegerOrInfinity(start).
  5. If relativeStart is -∞, let k be 0.
  6. Else if relativeStart < 0, let k be max(len + relativeStart, 0).
  7. Else, let k be min(relativeStart, len).
  8. If end is undefined, let relativeEnd be len; else let relativeEnd be ? ToIntegerOrInfinity(end).
  9. If relativeEnd is -∞, let final be 0.
  10. Else if relativeEnd < 0, let final be max(len + relativeEnd, 0).
  11. Else, let final be min(relativeEnd, len).
  12. Let count be max(final - k, 0).
  13. Let A be ? TypedArraySpeciesCreate(O, « 𝔽(count) »).
  14. If count > 0, then
    1. If IsDetachedBuffer(O.[[ViewedArrayBuffer]]) is true, throw a TypeError exception.
    2. Let srcType be TypedArrayElementType(O).
    3. Let targetType be TypedArrayElementType(A).
    4. If srcType is different from targetType, then
      1. Let n be 0.
      2. Repeat, while k < final,
        1. Let Pk be ! ToString(𝔽(k)).
        2. Let kValue be ! Get(O, Pk).
        3. Perform ! Set(A, ! ToString(𝔽(n)), kValue, true).
        4. Set k to k + 1.
        5. Set n to n + 1.
    5. Else,
      1. Let srcBuffer be O.[[ViewedArrayBuffer]].
      2. Let targetBuffer be A.[[ViewedArrayBuffer]].
      3. Let elementSize be TypedArrayElementSize(O).
      4. NOTE: If srcType and targetType are the same, the transfer must be performed in a manner that preserves the bit-level encoding of the source data.
      5. Let srcByteOffset be O.[[ByteOffset]].
      6. Let targetByteIndex be A.[[ByteOffset]].
      7. Let srcByteIndex be (k × elementSize) + srcByteOffset.
      8. Let limit be targetByteIndex + count × elementSize.
      9. Repeat, while targetByteIndex < limit,
        1. Let value be GetValueFromBuffer(srcBuffer, srcByteIndex, Uint8, true, Unordered).
        2. Perform SetValueInBuffer(targetBuffer, targetByteIndex, Uint8, value, true, Unordered).
        3. Set srcByteIndex to srcByteIndex + 1.
        4. Set targetByteIndex to targetByteIndex + 1.
  15. Return A.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.26 %TypedArray%.prototype.some ( callbackfn [ , thisArg ] )

The interpretation and use of the arguments of %TypedArray%.prototype.some are the same as for Array.prototype.some as defined in 23.1.3.27.

When the some method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Let len be O.[[ArrayLength]].
  4. If IsCallable(callbackfn) is false, throw a TypeError exception.
  5. Let k be 0.
  6. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ! Get(O, Pk).
    3. Let testResult be ToBoolean(? Call(callbackfn, thisArg, « kValue, 𝔽(k), O »)).
    4. If testResult is true, return true.
    5. Set k to k + 1.
  7. Return false.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.27 %TypedArray%.prototype.sort ( comparefn )

%TypedArray%.prototype.sort is a distinct function that, except as described below, implements the same requirements as those of Array.prototype.sort as defined in 23.1.3.28. The implementation of the %TypedArray%.prototype.sort specification may be optimized with the knowledge that the this value is an object that has a fixed length and whose integer-indexed properties are not sparse.

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

The following steps are performed:

  1. If comparefn is not undefined and IsCallable(comparefn) is false, throw a TypeError exception.
  2. Let obj be the this value.
  3. Perform ? ValidateTypedArray(obj).
  4. Let buffer be obj.[[ViewedArrayBuffer]].
  5. Let len be obj.[[ArrayLength]].
  6. NOTE: The following closure performs a numeric comparison rather than the string comparison used in 23.1.3.28.
  7. Let SortCompare be a new Abstract Closure with parameters (x, y) that captures comparefn and buffer and performs the following steps when called:
    1. Assert: Both Type(x) and Type(y) are Number or both are BigInt.
    2. If comparefn is not undefined, then
      1. Let v be ? ToNumber(? Call(comparefn, undefined, « x, y »)).
      2. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
      3. If v is NaN, return +0𝔽.
      4. Return v.
    3. If x and y are both NaN, return +0𝔽.
    4. If x is NaN, return 1𝔽.
    5. If y is NaN, return -1𝔽.
    6. If x < y, return -1𝔽.
    7. If x > y, return 1𝔽.
    8. If x is -0𝔽 and y is +0𝔽, return -1𝔽.
    9. If x is +0𝔽 and y is -0𝔽, return 1𝔽.
    10. Return +0𝔽.
  8. Return ? SortIndexedProperties(obj, len, SortCompare).
 Note

Because NaN always compares greater than any other value, NaN property values always sort to the end of the result when comparefn is not provided.

23.2.3.28 %TypedArray%.prototype.subarray ( begin, end )

Returns a new TypedArray whose element type is the same as this TypedArray and whose ArrayBuffer is the same as the ArrayBuffer of this TypedArray, referencing the elements at begin, inclusive, up to end, exclusive. If either begin or end is negative, it refers to an index from the end of the array, as opposed to from the beginning.

When the subarray method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[TypedArrayName]]).
  3. Assert: O has a [[ViewedArrayBuffer]] internal slot.
  4. Let buffer be O.[[ViewedArrayBuffer]].
  5. Let srcLength be O.[[ArrayLength]].
  6. Let relativeBegin be ? ToIntegerOrInfinity(begin).
  7. If relativeBegin is -∞, let beginIndex be 0.
  8. Else if relativeBegin < 0, let beginIndex be max(srcLength + relativeBegin, 0).
  9. Else, let beginIndex be min(relativeBegin, srcLength).
  10. If end is undefined, let relativeEnd be srcLength; else let relativeEnd be ? ToIntegerOrInfinity(end).
  11. If relativeEnd is -∞, let endIndex be 0.
  12. Else if relativeEnd < 0, let endIndex be max(srcLength + relativeEnd, 0).
  13. Else, let endIndex be min(relativeEnd, srcLength).
  14. Let newLength be max(endIndex - beginIndex, 0).
  15. Let elementSize be TypedArrayElementSize(O).
  16. Let srcByteOffset be O.[[ByteOffset]].
  17. Let beginByteOffset be srcByteOffset + beginIndex × elementSize.
  18. Let argumentsList be « buffer, 𝔽(beginByteOffset), 𝔽(newLength) ».
  19. Return ? TypedArraySpeciesCreate(O, argumentsList).

This function is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

23.2.3.29 %TypedArray%.prototype.toLocaleString ( [ reserved1 [ , reserved2 ] ] )

%TypedArray%.prototype.toLocaleString is a distinct function that implements the same algorithm as Array.prototype.toLocaleString as defined in 23.1.3.30 except that the this value's [[ArrayLength]] internal slot is accessed in place of performing a [[Get]] of "length". The implementation of the algorithm may be optimized with the knowledge that the this value is an object that has a fixed length and whose integer-indexed properties are not sparse. However, such optimization must not introduce any observable changes in the specified behaviour of the algorithm.

This function is not generic. ValidateTypedArray is applied to the this value prior to evaluating the algorithm. If its result is an abrupt completion that exception is thrown instead of evaluating the algorithm.

Note

If the ECMAScript implementation includes the ECMA-402 Internationalization API this function is based upon the algorithm for Array.prototype.toLocaleString that is in the ECMA-402 specification.

23.2.3.30 %TypedArray%.prototype.toString ( )

The initial value of the "toString" property is %Array.prototype.toString%, defined in 23.1.3.31.

23.2.3.31 %TypedArray%.prototype.values ( )

When the values method is called, the following steps are taken:

  1. Let O be the this value.
  2. Perform ? ValidateTypedArray(O).
  3. Return CreateArrayIterator(O, value).

23.2.3.32 %TypedArray%.prototype [ @@iterator ] ( )

The initial value of the @@iterator property is %TypedArray.prototype.values%, defined in 23.2.3.31.

23.2.3.33 get %TypedArray%.prototype [ @@toStringTag ]

%TypedArray%.prototype[@@toStringTag] is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let O be the this value.
  2. If Type(O) is not Object, return undefined.
  3. If O does not have a [[TypedArrayName]] internal slot, return undefined.
  4. Let name be O.[[TypedArrayName]].
  5. Assert: Type(name) is String.
  6. Return name.

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

The initial value of the "name" property of this function is "get [Symbol.toStringTag]".

23.2.4 Abstract Operations for TypedArray Objects

23.2.4.1 TypedArraySpeciesCreate ( exemplar, argumentList )

The abstract operation TypedArraySpeciesCreate takes arguments exemplar (a TypedArray) and argumentList and returns either a normal completion containing a TypedArray or an abrupt completion. It is used to specify the creation of a new TypedArray using a constructor function that is derived from exemplar. Unlike ArraySpeciesCreate, which can create non-Array objects through the use of @@species, this operation enforces that the constructor function creates an actual TypedArray. It performs the following steps when called:

  1. Let defaultConstructor be the intrinsic object listed in column one of Table 71 for exemplar.[[TypedArrayName]].
  2. Let constructor be ? SpeciesConstructor(exemplar, defaultConstructor).
  3. Let result be ? TypedArrayCreate(constructor, argumentList).
  4. Assert: result has [[TypedArrayName]] and [[ContentType]] internal slots.
  5. If result.[[ContentType]] ≠ exemplar.[[ContentType]], throw a TypeError exception.
  6. Return result.

23.2.4.2 TypedArrayCreate ( constructor, argumentList )

The abstract operation TypedArrayCreate takes arguments constructor and argumentList and returns either a normal completion containing a TypedArray or an abrupt completion. It is used to specify the creation of a new TypedArray using a constructor function. It performs the following steps when called:

  1. Let newTypedArray be ? Construct(constructor, argumentList).
  2. Perform ? ValidateTypedArray(newTypedArray).
  3. If argumentList is a List of a single Number, then
    1. If newTypedArray.[[ArrayLength]] < ℝ(argumentList[0]), throw a TypeError exception.
  4. Return newTypedArray.

23.2.4.3 ValidateTypedArray ( O )

The abstract operation ValidateTypedArray takes argument O and returns either a normal completion containing unused or an abrupt completion. It performs the following steps when called:

  1. Perform ? RequireInternalSlot(O, [[TypedArrayName]]).
  2. Assert: O has a [[ViewedArrayBuffer]] internal slot.
  3. Let buffer be O.[[ViewedArrayBuffer]].
  4. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  5. Return unused.

23.2.4.4 TypedArrayElementSize ( O )

The abstract operation TypedArrayElementSize takes argument O (a TypedArray) and returns a non-negative integer. It performs the following steps when called:

  1. Return the Element Size value specified in Table 71 for O.[[TypedArrayName]].

23.2.4.5 TypedArrayElementType ( O )

The abstract operation TypedArrayElementType takes argument O (a TypedArray) and returns a TypedArray element type. It performs the following steps when called:

  1. Return the Element Type value specified in Table 71 for O.[[TypedArrayName]].

23.2.5 The TypedArray Constructors

Each TypedArray constructor:

  • is an intrinsic object that has the structure described below, differing only in the name used as the constructor name instead of TypedArray, in Table 71.
  • is a function whose behaviour differs based upon the number and types of its arguments. The actual behaviour of a call of TypedArray depends upon the number and kind of arguments that are passed to it.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified TypedArray behaviour must include a super call to the TypedArray constructor to create and initialize the subclass instance with the internal state necessary to support the %TypedArray%.prototype built-in methods.
  • has a "length" property whose value is 3𝔽.

23.2.5.1 TypedArray ( ...args )

Each TypedArray constructor performs the following steps when called:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let constructorName be the String value of the Constructor Name value specified in Table 71 for this TypedArray constructor.
  3. Let proto be "%TypedArray.prototype%".
  4. Let numberOfArgs be the number of elements in args.
  5. If numberOfArgs = 0, then
    1. Return ? AllocateTypedArray(constructorName, NewTarget, proto, 0).
  6. Else,
    1. Let firstArgument be args[0].
    2. If Type(firstArgument) is Object, then
      1. Let O be ? AllocateTypedArray(constructorName, NewTarget, proto).
      2. If firstArgument has a [[TypedArrayName]] internal slot, then
        1. Perform ? InitializeTypedArrayFromTypedArray(O, firstArgument).
      3. Else if firstArgument has an [[ArrayBufferData]] internal slot, then
        1. If numberOfArgs > 1, let byteOffset be args[1]; else let byteOffset be undefined.
        2. If numberOfArgs > 2, let length be args[2]; else let length be undefined.
        3. Perform ? InitializeTypedArrayFromArrayBuffer(O, firstArgument, byteOffset, length).
      4. Else,
        1. Assert: Type(firstArgument) is Object and firstArgument does not have either a [[TypedArrayName]] or an [[ArrayBufferData]] internal slot.
        2. Let usingIterator be ? GetMethod(firstArgument, @@iterator).
        3. If usingIterator is not undefined, then
          1. Let values be ? IterableToList(firstArgument, usingIterator).
          2. Perform ? InitializeTypedArrayFromList(O, values).
        4. Else,
          1. NOTE: firstArgument is not an Iterable so assume it is already an array-like object.
          2. Perform ? InitializeTypedArrayFromArrayLike(O, firstArgument).
      5. Return O.
    3. Else,
      1. Assert: firstArgument is not an Object.
      2. Let elementLength be ? ToIndex(firstArgument).
      3. Return ? AllocateTypedArray(constructorName, NewTarget, proto, elementLength).

23.2.5.1.1 AllocateTypedArray ( constructorName, newTarget, defaultProto [ , length ] )

The abstract operation AllocateTypedArray takes arguments constructorName (a String which is the name of a TypedArray constructor in Table 71), newTarget, and defaultProto and optional argument length (a non-negative integer) and returns either a normal completion containing a TypedArray or an abrupt completion. It is used to validate and create an instance of a TypedArray constructor. If the length argument is passed, an ArrayBuffer of that length is also allocated and associated with the new TypedArray instance. AllocateTypedArray provides common semantics that is used by TypedArray. It performs the following steps when called:

  1. Let proto be ? GetPrototypeFromConstructor(newTarget, defaultProto).
  2. Let obj be IntegerIndexedObjectCreate(proto).
  3. Assert: obj.[[ViewedArrayBuffer]] is undefined.
  4. Set obj.[[TypedArrayName]] to constructorName.
  5. If constructorName is "BigInt64Array" or "BigUint64Array", set obj.[[ContentType]] to BigInt.
  6. Otherwise, set obj.[[ContentType]] to Number.
  7. If length is not present, then
    1. Set obj.[[ByteLength]] to 0.
    2. Set obj.[[ByteOffset]] to 0.
    3. Set obj.[[ArrayLength]] to 0.
  8. Else,
    1. Perform ? AllocateTypedArrayBuffer(obj, length).
  9. Return obj.

23.2.5.1.2 InitializeTypedArrayFromTypedArray ( O, srcArray )

The abstract operation InitializeTypedArrayFromTypedArray takes arguments O (a TypedArray) and srcArray (a TypedArray) and returns either a normal completion containing unused or an abrupt completion. It performs the following steps when called:

  1. Let srcData be srcArray.[[ViewedArrayBuffer]].
  2. If IsDetachedBuffer(srcData) is true, throw a TypeError exception.
  3. Let elementType be TypedArrayElementType(O).
  4. Let elementSize be TypedArrayElementSize(O).
  5. Let srcType be TypedArrayElementType(srcArray).
  6. Let srcElementSize be TypedArrayElementSize(srcArray).
  7. Let srcByteOffset be srcArray.[[ByteOffset]].
  8. Let elementLength be srcArray.[[ArrayLength]].
  9. Let byteLength be elementSize × elementLength.
  10. If IsSharedArrayBuffer(srcData) is false, then
    1. Let bufferConstructor be ? SpeciesConstructor(srcData, %ArrayBuffer%).
  11. Else,
    1. Let bufferConstructor be %ArrayBuffer%.
  12. If elementType is the same as srcType, then
    1. Let data be ? CloneArrayBuffer(srcData, srcByteOffset, byteLength, bufferConstructor).
  13. Else,
    1. Let data be ? AllocateArrayBuffer(bufferConstructor, byteLength).
    2. If IsDetachedBuffer(srcData) is true, throw a TypeError exception.
    3. If srcArray.[[ContentType]] ≠ O.[[ContentType]], throw a TypeError exception.
    4. Let srcByteIndex be srcByteOffset.
    5. Let targetByteIndex be 0.
    6. Let count be elementLength.
    7. Repeat, while count > 0,
      1. Let value be GetValueFromBuffer(srcData, srcByteIndex, srcType, true, Unordered).
      2. Perform SetValueInBuffer(data, targetByteIndex, elementType, value, true, Unordered).
      3. Set srcByteIndex to srcByteIndex + srcElementSize.
      4. Set targetByteIndex to targetByteIndex + elementSize.
      5. Set count to count - 1.
  14. Set O.[[ViewedArrayBuffer]] to data.
  15. Set O.[[ByteLength]] to byteLength.
  16. Set O.[[ByteOffset]] to 0.
  17. Set O.[[ArrayLength]] to elementLength.
  18. Return unused.

23.2.5.1.3 InitializeTypedArrayFromArrayBuffer ( O, buffer, byteOffset, length )

The abstract operation InitializeTypedArrayFromArrayBuffer takes arguments O (a TypedArray), buffer (an ArrayBuffer or a SharedArrayBuffer), byteOffset (an ECMAScript language value), and length (an ECMAScript language value) and returns either a normal completion containing unused or an abrupt completion. It performs the following steps when called:

  1. Let elementSize be TypedArrayElementSize(O).
  2. Let offset be ? ToIndex(byteOffset).
  3. If offset modulo elementSize ≠ 0, throw a RangeError exception.
  4. If length is not undefined, then
    1. Let newLength be ? ToIndex(length).
  5. If IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  6. Let bufferByteLength be buffer.[[ArrayBufferByteLength]].
  7. If length is undefined, then
    1. If bufferByteLength modulo elementSize ≠ 0, throw a RangeError exception.
    2. Let newByteLength be bufferByteLength - offset.
    3. If newByteLength < 0, throw a RangeError exception.
  8. Else,
    1. Let newByteLength be newLength × elementSize.
    2. If offset + newByteLength > bufferByteLength, throw a RangeError exception.
  9. Set O.[[ViewedArrayBuffer]] to buffer.
  10. Set O.[[ByteLength]] to newByteLength.
  11. Set O.[[ByteOffset]] to offset.
  12. Set O.[[ArrayLength]] to newByteLength / elementSize.
  13. Return unused.

23.2.5.1.4 InitializeTypedArrayFromList ( O, values )

The abstract operation InitializeTypedArrayFromList takes arguments O (a TypedArray) and values (a List of ECMAScript language values) and returns either a normal completion containing unused or an abrupt completion. It performs the following steps when called:

  1. Let len be the number of elements in values.
  2. Perform ? AllocateTypedArrayBuffer(O, len).
  3. Let k be 0.
  4. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be the first element of values and remove that element from values.
    3. Perform ? Set(O, Pk, kValue, true).
    4. Set k to k + 1.
  5. Assert: values is now an empty List.
  6. Return unused.

23.2.5.1.5 InitializeTypedArrayFromArrayLike ( O, arrayLike )

The abstract operation InitializeTypedArrayFromArrayLike takes arguments O (a TypedArray) and arrayLike (an Object, but not a TypedArray or an ArrayBuffer) and returns either a normal completion containing unused or an abrupt completion. It performs the following steps when called:

  1. Let len be ? LengthOfArrayLike(arrayLike).
  2. Perform ? AllocateTypedArrayBuffer(O, len).
  3. Let k be 0.
  4. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kValue be ? Get(arrayLike, Pk).
    3. Perform ? Set(O, Pk, kValue, true).
    4. Set k to k + 1.
  5. Return unused.

23.2.5.1.6 AllocateTypedArrayBuffer ( O, length )

The abstract operation AllocateTypedArrayBuffer takes arguments O (a TypedArray) and length (a non-negative integer) and returns either a normal completion containing unused or an abrupt completion. It allocates and associates an ArrayBuffer with O. It performs the following steps when called:

  1. Assert: O.[[ViewedArrayBuffer]] is undefined.
  2. Let elementSize be TypedArrayElementSize(O).
  3. Let byteLength be elementSize × length.
  4. Let data be ? AllocateArrayBuffer(%ArrayBuffer%, byteLength).
  5. Set O.[[ViewedArrayBuffer]] to data.
  6. Set O.[[ByteLength]] to byteLength.
  7. Set O.[[ByteOffset]] to 0.
  8. Set O.[[ArrayLength]] to length.
  9. Return unused.

23.2.6 Properties of the TypedArray Constructors

Each TypedArray constructor:

  • has a [[Prototype]] internal slot whose value is %TypedArray%.
  • has a "name" property whose value is the String value of the constructor name specified for it in Table 71.
  • has the following properties:

23.2.6.1 TypedArray.BYTES_PER_ELEMENT

The value of TypedArray.BYTES_PER_ELEMENT is the Element Size value specified in Table 71 for TypedArray.

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

23.2.6.2 TypedArray.prototype

The initial value of TypedArray.prototype is the corresponding TypedArray prototype intrinsic object (23.2.7).

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

23.2.7 Properties of the TypedArray Prototype Objects

Each TypedArray prototype object:

  • has a [[Prototype]] internal slot whose value is %TypedArray.prototype%.
  • is an ordinary object.
  • does not have a [[ViewedArrayBuffer]] or any other of the internal slots that are specific to TypedArray instance objects.

23.2.7.1 TypedArray.prototype.BYTES_PER_ELEMENT

The value of TypedArray.prototype.BYTES_PER_ELEMENT is the Element Size value specified in Table 71 for TypedArray.

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

23.2.7.2 TypedArray.prototype.constructor

The initial value of a TypedArray.prototype.constructor is the corresponding %TypedArray% intrinsic object.

23.2.8 Properties of TypedArray Instances

TypedArray instances are Integer-Indexed exotic objects. Each TypedArray instance inherits properties from the corresponding TypedArray prototype object. Each TypedArray instance has the following internal slots: [[TypedArrayName]], [[ViewedArrayBuffer]], [[ByteLength]], [[ByteOffset]], and [[ArrayLength]].