ECMAScript® 2024 Language Specification

Draft ECMA-262 / February 15, 2024

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.

23.1.1.1 Array ( ...values )

This function performs the following steps when called:

  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 len is not a 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 a "length" property whose value is 1𝔽.
  • has the following properties:

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

This method performs the following steps when called:

  1. Let C be the this value.
  2. If mapfn is undefined, then
    1. 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 ? GetIteratorFromMethod(items, 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 ? IteratorStepValue(iteratorRecord).
      4. If next is done, then
        1. Perform ? Set(A, "length", 𝔽(k), true).
        2. Return A.
      5. If mapping is true, then
        1. Let mappedValue be Completion(Call(mapfn, thisArg, « next, 𝔽(k) »)).
        2. IfAbruptCloseIterator(mappedValue, iteratorRecord).
      6. Else,
        1. Let mappedValue be next.
      7. Let defineStatus be Completion(CreateDataPropertyOrThrow(A, Pk, mappedValue)).
      8. IfAbruptCloseIterator(defineStatus, iteratorRecord).
      9. 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,
      1. 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

This method 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 )

This function performs the following steps when called:

  1. Return ? IsArray(arg).

23.1.2.3 Array.of ( ...items )

This method performs the following steps when called:

  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

This method 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 )

This method returns an array containing the array elements of the object followed by the array elements of each argument.

It performs the following steps when called:

  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 len be ? LengthOfArrayLike(E).
      2. If n + len > 253 - 1, throw a TypeError exception.
      3. Let k be 0.
      4. Repeat, while k < len,
        1. Let Pk be ! ToString(𝔽(k)).
        2. Let exists be ? HasProperty(E, Pk).
        3. If exists is true, then
          1. Let subElement be ? Get(E, Pk).
          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 this method is 1𝔽.

Note 1

The explicit setting of the "length" property in step 6 is intended to ensure the length is correct when the final non-empty element of items has trailing holes or when A is not a built-in Array.

 Note 2

This method 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 (an ECMAScript language value) and returns either a normal completion containing a Boolean or a throw completion. It performs the following steps when called:

  1. If O is not an 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.

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let relativeTarget be ? ToIntegerOrInfinity(target).
  4. If relativeTarget = -∞, 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 = -∞, 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 = -∞, 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

This method 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 ( )

This method performs the following steps when called:

  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.

This method performs the following steps when called:

  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

This method 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.

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let relativeStart be ? ToIntegerOrInfinity(start).
  4. If relativeStart = -∞, 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 = -∞, 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

This method 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.

This method performs the following steps when called:

  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

This method 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

This method calls predicate once for each element of the array, in ascending index order, until it finds one where predicate returns a value that coerces to true. If such an element is found, find immediately returns that element value. Otherwise, find returns undefined.

See FindViaPredicate for additional information.

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let findRec be ? FindViaPredicate(O, len, ascending, predicate, thisArg).
  4. Return findRec.[[Value]].
 Note 2

This method 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

This method calls predicate once for each element of the array, in ascending index order, until it finds one where predicate returns a value that coerces to true. If such an element is found, findIndex immediately returns the index of that element value. Otherwise, findIndex returns -1.

See FindViaPredicate for additional information.

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let findRec be ? FindViaPredicate(O, len, ascending, predicate, thisArg).
  4. Return findRec.[[Index]].
 Note 2

This method 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.findLast ( predicate [ , thisArg ] )

Note 1

This method calls predicate once for each element of the array, in descending index order, until it finds one where predicate returns a value that coerces to true. If such an element is found, findLast immediately returns that element value. Otherwise, findLast returns undefined.

See FindViaPredicate for additional information.

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let findRec be ? FindViaPredicate(O, len, descending, predicate, thisArg).
  4. Return findRec.[[Value]].
 Note 2

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

23.1.3.12 Array.prototype.findLastIndex ( predicate [ , thisArg ] )

Note 1

This method calls predicate once for each element of the array, in descending index order, until it finds one where predicate returns a value that coerces to true. If such an element is found, findLastIndex immediately returns the index of that element value. Otherwise, findLastIndex returns -1.

See FindViaPredicate for additional information.

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let findRec be ? FindViaPredicate(O, len, descending, predicate, thisArg).
  4. Return findRec.[[Index]].
 Note 2

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

23.1.3.12.1 FindViaPredicate ( O, len, direction, predicate, thisArg )

The abstract operation FindViaPredicate takes arguments O (an Object), len (a non-negative integer), direction (ascending or descending), predicate (an ECMAScript language value), and thisArg (an ECMAScript language value) and returns either a normal completion containing a Record with fields [[Index]] (an integral Number) and [[Value]] (an ECMAScript language value) or a throw completion.

O should be an array-like object or a TypedArray. This operation calls predicate once for each element of O, in either ascending index order or descending index order (as indicated by direction), until it finds one where predicate returns a value that coerces to true. At that point, this operation returns a Record that gives the index and value of the element found. If no such element is found, this operation returns a Record that specifies -1𝔽 for the index and undefined for the value.

predicate should be a function. When called for an element of the array, it is passed three arguments: the value of the element, the index of the element, and the object being traversed. Its return value will be coerced to a Boolean value.

thisArg will be used as the this value for each invocation of predicate.

This operation 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 is set before the first call to predicate, just before the traversal begins. Elements that are appended to the array after this 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 this operation visits them. Elements that are deleted after traversal begins and before being visited are still visited and are either looked up from the prototype or are undefined.

It performs the following steps when called:

  1. If IsCallable(predicate) is false, throw a TypeError exception.
  2. If direction is ascending, then
    1. Let indices be a List of the integers in the interval from 0 (inclusive) to len (exclusive), in ascending order.
  3. Else,
    1. Let indices be a List of the integers in the interval from 0 (inclusive) to len (exclusive), in descending order.
  4. For each integer k of indices, do
    1. Let Pk be ! ToString(𝔽(k)).
    2. NOTE: If O is a TypedArray, the following invocation of Get will return a normal completion.
    3. Let kValue be ? Get(O, Pk).
    4. Let testResult be ? Call(predicate, thisArg, « kValue, 𝔽(k), O »).
    5. If ToBoolean(testResult) is true, return the Record { [[Index]]: 𝔽(k), [[Value]]: kValue }.
  5. Return the Record { [[Index]]: -1𝔽, [[Value]]: undefined }.

23.1.3.13 Array.prototype.flat ( [ depth ] )

This method performs the following steps when called:

  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.13.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 (a function object) and thisArg (an ECMAScript language value) and returns either a normal completion containing a non-negative integer or a throw 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 = +∞, 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.14 Array.prototype.flatMap ( mapperFunction [ , thisArg ] )

This method performs the following steps when called:

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

This method performs the following steps when called:

  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

This method 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.includes ( searchElement [ , fromIndex ] )

Note 1

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

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 or equal to +0𝔽, the whole array will be searched.

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If len = 0, return false.
  4. Let n be ? ToIntegerOrInfinity(fromIndex).
  5. Assert: If fromIndex is undefined, then n is 0.
  6. If n = +∞, return false.
  7. Else if n = -∞, 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

This method 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

This 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.17 Array.prototype.indexOf ( searchElement [ , fromIndex ] )

This method 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, it returns -1𝔽.

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 or equal to +0𝔽, the whole array will be searched.

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If len = 0, return -1𝔽.
  4. Let n be ? ToIntegerOrInfinity(fromIndex).
  5. Assert: If fromIndex is undefined, then n is 0.
  6. If n = +∞, return -1𝔽.
  7. Else if n = -∞, 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. If IsStrictlyEqual(searchElement, elementK) is true, return 𝔽(k).
    3. Set k to k + 1.
  11. Return -1𝔽.
 Note 2

This method 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.18 Array.prototype.join ( separator )

This method converts the elements of the array to Strings, and then concatenates these Strings, separated by occurrences of the separator. If no separator is provided, a single comma is used as the separator.

It performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If separator is undefined, let sep be ",".
  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 either 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

This method 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.keys ( )

This method performs the following steps when called:

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

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

Note 1

This method 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, it returns -1𝔽.

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 or equal to +0𝔽, -1𝔽 is returned.

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If len = 0, return -1𝔽.
  4. If fromIndex is present, let n be ? ToIntegerOrInfinity(fromIndex); else let n be len - 1.
  5. If n = -∞, 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. If IsStrictlyEqual(searchElement, elementK) is true, return 𝔽(k).
    3. Set k to k - 1.
  9. Return -1𝔽.
 Note 2

This method 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.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.

This method performs the following steps when called:

  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

This method 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.pop ( )

Note 1

This method removes the last element of the array and returns it.

This method performs the following steps when called:

  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

This method 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.push ( ...items )

Note 1

This method appends the arguments to the end of the array, in the order in which they appear. It returns the new length of the array.

This method performs the following steps when called:

  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 this method is 1𝔽.

Note 2

This method 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.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 initialValue and currentValue will be the first value in the array. If no initialValue was supplied, then previousValue will be the first value in the array and currentValue will be 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.

This method performs the following steps when called:

  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

This method 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.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 initialValue and currentValue will be the last value in the array. If no initialValue was supplied, then previousValue will be the last value in the array and currentValue will be 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.

This method performs the following steps when called:

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

This method 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.reverse ( )

Note 1

This method rearranges the elements of the array so as to reverse their order. It returns the object as the result of the call.

This method performs the following steps when called:

  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. NOTE: No action is required.
    12. Set lower to lower + 1.
  6. Return O.
 Note 2

This method 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.shift ( )

This method removes the first element of the array and returns it.

It performs the following steps when called:

  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

This method 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.slice ( start, end )

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

It performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let relativeStart be ? ToIntegerOrInfinity(start).
  4. If relativeStart = -∞, 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 = -∞, 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 in step 15 is intended to ensure the length is correct even when A is not a built-in Array.

 Note 2

This method 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.29 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.

This method performs the following steps when called:

  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

This method 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.sort ( comparefn )

This method sorts the elements of this array. 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.

It performs the following steps when called:

  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. Return ? CompareArrayElements(x, y, comparefn).
  5. Let sortedList be ? SortIndexedProperties(obj, len, SortCompare, skip-holes).
  6. Let itemCount be the number of elements in sortedList.
  7. Let j be 0.
  8. Repeat, while j < itemCount,
    1. Perform ? Set(obj, ! ToString(𝔽(j)), sortedList[j], true).
    2. Set j to j + 1.
  9. NOTE: The call to SortIndexedProperties in step 5 uses skip-holes. The remaining indices are deleted to preserve the number of holes that were detected and excluded from the sort.
  10. Repeat, while j < len,
    1. Perform ? DeletePropertyOrThrow(obj, ! ToString(𝔽(j))).
    2. Set j to j + 1.
  11. Return obj.
 Note 1

Because non-existent property values always compare greater than undefined property values, and undefined always compares greater than any other value (see CompareArrayElements), 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 5 and 6 have the potential to cause SortCompare to not behave as a consistent comparator.

 Note 3

This method 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.1 SortIndexedProperties ( obj, len, SortCompare, holes )

The abstract operation SortIndexedProperties takes arguments obj (an Object), len (a non-negative integer), SortCompare (an Abstract Closure with two parameters), and holes (skip-holes or read-through-holes) and returns either a normal completion containing a List of ECMAScript language values or a throw 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. If holes is skip-holes, then
      1. Let kRead be ? HasProperty(obj, Pk).
    3. Else,
      1. Assert: holes is read-through-holes.
      2. Let kRead be true.
    4. If kRead is true, then
      1. Let kValue be ? Get(obj, Pk).
      2. Append kValue to items.
    5. Set k to k + 1.
  4. 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.
  5. Return items.

The sort order is the ordering of items after completion of step 4 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 4 is executed, and the notation new[j] to refer to items[j] after step 4 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; 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, v is a 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.30.2 CompareArrayElements ( x, y, comparefn )

The abstract operation CompareArrayElements takes arguments x (an ECMAScript language value), y (an ECMAScript language value), and comparefn (a function object or undefined) and returns either a normal completion containing a Number or an abrupt completion. It 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𝔽.

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

Note 1

This method deletes the deleteCount elements of the array starting at integer index start and replaces them with the elements of items. It returns an Array containing the deleted elements (if any).

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let relativeStart be ? ToIntegerOrInfinity(start).
  4. If relativeStart = -∞, 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 itemCount 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 + itemCount - 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. 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.
  17. 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.
  18. Set k to actualStart.
  19. For each element E of items, do
    1. Perform ? Set(O, ! ToString(𝔽(k)), E, true).
    2. Set k to k + 1.
  20. Perform ? Set(O, "length", 𝔽(len - actualDeleteCount + itemCount), true).
  21. Return A.
 Note 2

The explicit setting of the "length" property in steps 15 and 20 is intended to ensure the lengths are correct even when the objects are not built-in Arrays.

 Note 3

This method 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.toLocaleString ( [ reserved1 [ , reserved2 ] ] )

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

Note 1

The first edition of ECMA-402 did not include a replacement specification for this 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.

This method performs the following steps when called:

  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 neither undefined nor 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

This method converts the elements of the array to Strings using their toLocaleString methods, and then concatenates these Strings, separated by occurrences of an implementation-defined locale-sensitive separator String. This method 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

This method 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.toReversed ( )

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let A be ? ArrayCreate(len).
  4. Let k be 0.
  5. Repeat, while k < len,
    1. Let from be ! ToString(𝔽(len - k - 1)).
    2. Let Pk be ! ToString(𝔽(k)).
    3. Let fromValue be ? Get(O, from).
    4. Perform ! CreateDataPropertyOrThrow(A, Pk, fromValue).
    5. Set k to k + 1.
  6. Return A.

23.1.3.34 Array.prototype.toSorted ( comparefn )

This method performs the following steps when called:

  1. If comparefn is not undefined and IsCallable(comparefn) is false, throw a TypeError exception.
  2. Let O be ? ToObject(this value).
  3. Let len be ? LengthOfArrayLike(O).
  4. Let A be ? ArrayCreate(len).
  5. Let SortCompare be a new Abstract Closure with parameters (x, y) that captures comparefn and performs the following steps when called:
    1. Return ? CompareArrayElements(x, y, comparefn).
  6. Let sortedList be ? SortIndexedProperties(O, len, SortCompare, read-through-holes).
  7. Let j be 0.
  8. Repeat, while j < len,
    1. Perform ! CreateDataPropertyOrThrow(A, ! ToString(𝔽(j)), sortedList[j]).
    2. Set j to j + 1.
  9. Return A.

23.1.3.35 Array.prototype.toSpliced ( start, skipCount, ...items )

This method performs the following steps when called:

  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 actualSkipCount be 0.
  9. Else if skipCount is not present, then
    1. Let actualSkipCount be len - actualStart.
  10. Else,
    1. Let sc be ? ToIntegerOrInfinity(skipCount).
    2. Let actualSkipCount be the result of clamping sc between 0 and len - actualStart.
  11. Let newLen be len + insertCount - actualSkipCount.
  12. If newLen > 253 - 1, throw a TypeError exception.
  13. Let A be ? ArrayCreate(newLen).
  14. Let i be 0.
  15. Let r be actualStart + actualSkipCount.
  16. Repeat, while i < actualStart,
    1. Let Pi be ! ToString(𝔽(i)).
    2. Let iValue be ? Get(O, Pi).
    3. Perform ! CreateDataPropertyOrThrow(A, Pi, iValue).
    4. Set i to i + 1.
  17. For each element E of items, do
    1. Let Pi be ! ToString(𝔽(i)).
    2. Perform ! CreateDataPropertyOrThrow(A, Pi, E).
    3. Set i to i + 1.
  18. Repeat, while i < newLen,
    1. Let Pi be ! ToString(𝔽(i)).
    2. Let from be ! ToString(𝔽(r)).
    3. Let fromValue be ? Get(O, from).
    4. Perform ! CreateDataPropertyOrThrow(A, Pi, fromValue).
    5. Set i to i + 1.
    6. Set r to r + 1.
  19. Return A.

23.1.3.36 Array.prototype.toString ( )

This method performs the following steps when called:

  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

This method 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.37 Array.prototype.unshift ( ...items )

This method prepends the arguments 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.

It performs the following steps when called:

  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 this method is 1𝔽.

Note

This method 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.38 Array.prototype.values ( )

This method performs the following steps when called:

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

23.1.3.39 Array.prototype.with ( index, value )

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. Let relativeIndex be ? ToIntegerOrInfinity(index).
  4. If relativeIndex ≥ 0, let actualIndex be relativeIndex.
  5. Else, let actualIndex be len + relativeIndex.
  6. If actualIndex ≥ len or actualIndex < 0, throw a RangeError exception.
  7. Let A be ? ArrayCreate(len).
  8. Let k be 0.
  9. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. If k is actualIndex, let fromValue be value.
    3. Else, let fromValue be ? Get(O, Pk).
    4. Perform ! CreateDataPropertyOrThrow(A, Pk, fromValue).
    5. Set k to k + 1.
  10. Return A.

23.1.3.40 Array.prototype [ @@iterator ] ( )

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

23.1.3.41 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, "findLast", true).
  9. Perform ! CreateDataPropertyOrThrow(unscopableList, "findLastIndex", true).
  10. Perform ! CreateDataPropertyOrThrow(unscopableList, "flat", true).
  11. Perform ! CreateDataPropertyOrThrow(unscopableList, "flatMap", true).
  12. Perform ! CreateDataPropertyOrThrow(unscopableList, "includes", true).
  13. Perform ! CreateDataPropertyOrThrow(unscopableList, "keys", true).
  14. Perform ! CreateDataPropertyOrThrow(unscopableList, "toReversed", true).
  15. Perform ! CreateDataPropertyOrThrow(unscopableList, "toSorted", true).
  16. Perform ! CreateDataPropertyOrThrow(unscopableList, "toSpliced", true).
  17. Perform ! CreateDataPropertyOrThrow(unscopableList, "values", true).
  18. 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.

The reason that "with" is not included in the unscopableList is because it is already a reserved word.

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. Let taRecord be MakeTypedArrayWithBufferWitnessRecord(array, seq-cst).
        2. If IsTypedArrayOutOfBounds(taRecord) is true, throw a TypeError exception.
        3. Let len be TypedArrayLength(taRecord).
      2. Else,
        1. Let len be ? LengthOfArrayLike(array).
      3. If index ≥ len, return NormalCompletion(undefined).
      4. Let indexNumber be 𝔽(index).
      5. If kind is key, then
        1. Let result be indexNumber.
      6. Else,
        1. Let elementKey be ! ToString(indexNumber).
        2. Let elementValue be ? Get(array, elementKey).
        3. If kind is value, then
          1. Let result be elementValue.
        4. Else,
          1. Assert: kind is key+value.
          2. Let result be CreateArrayFromList(« indexNumber, elementValue »).
      7. Perform ? GeneratorYield(CreateIterResultObject(result, false)).
      8. 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 }.