23.1 Array Objects

Array objects 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 exotic object when called as a constructor.
  • also creates and initializes a new Array object 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.
  • is designed to be subclassable. It 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 intLen is not the same value as len, 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 with argument items and optional arguments mapfn and thisArg, 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 Call(mapfn, thisArg, « nextValue, 𝔽(k) »).
        2. If mappedValue is an abrupt completion, return ? IteratorClose(iteratorRecord, mappedValue).
        3. Set mappedValue to mappedValue.[[Value]].
      7. Else, let mappedValue be nextValue.
      8. Let defineStatus be CreateDataPropertyOrThrow(A, Pk, mappedValue).
      9. If defineStatus is an abrupt completion, return ? IteratorClose(iteratorRecord, defineStatus).
      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 )

The isArray function takes one argument arg, and performs the following steps:

  1. Return ? IsArray(arg).

23.1.2.3 Array.of ( ...items )

When the of method is called with any number of arguments, 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:

  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.concat ( ...items )

When the concat method is called with zero or more arguments, it returns an array containing the array elements of the object followed by the array elements of each argument.

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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.1.1 IsConcatSpreadable ( O )

The abstract operation IsConcatSpreadable takes argument O. 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.2 Array.prototype.constructor

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

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

The copyWithin method takes up to three arguments target, start and end.

Note 1

The end argument is optional with the length of the this value as its default value. 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.

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 2

The copyWithin function 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.4 Array.prototype.entries ( )

The following steps are taken:

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

23.1.3.5 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 with one or two arguments, 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

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

The fill method takes up to three arguments value, start and end.

Note 1

The start and end arguments are optional with default values of 0 and the length of the this value. 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.

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 2

The fill function 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.7 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 with one or two arguments, 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

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

The find method is called with one or two arguments, predicate and 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 not visited.

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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.9 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 not visited.

When the findIndex method is called with one or two arguments, 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.10 Array.prototype.flat ( [ depth ] )

When the flat method is called with zero or one arguments, 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.10.1 FlattenIntoArray ( target, source, sourceLen, start, depth [ , mapperFunction, thisArg ] )

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

  1. Assert: Type(target) is Object.
  2. Assert: Type(source) is Object.
  3. Assert: If mapperFunction is present, then ! IsCallable(mapperFunction) is true, thisArg is present, and depth is 1.
  4. Let targetIndex be start.
  5. Let sourceIndex be +0𝔽.
  6. 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𝔽.
  7. Return targetIndex.

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

When the flatMap method is called with one or two arguments, 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.12 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 with one or two arguments, 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.13 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 object. 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 Strict Equality Comparison, allowing it to detect NaN array elements. Second, it does not skip missing array elements, instead treating them as undefined.

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

Note 1

indexOf compares searchElement to the elements of the array, in ascending order, using the Strict Equality Comparison algorithm, and if found at one or more indices, returns the smallest such index; otherwise, -1𝔽 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, -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 with one or two arguments, 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 the result of performing Strict Equality Comparison 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.15 Array.prototype.join ( separator )

Note 1

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.

The join method takes one argument, separator, and performs the following steps:

  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 2

The join function 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.16 Array.prototype.keys ( )

The following steps are taken:

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

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

Note 1

lastIndexOf compares searchElement to the elements of the array in descending order using the Strict Equality Comparison 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 with one or two arguments, 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 the result of performing Strict Equality Comparison 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.18 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 with one or two arguments, 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.19 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.20 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 with zero or more arguments, 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.21 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 with one or two arguments, 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.22 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 with one or two arguments, 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.23 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 lowermiddle,
    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 object. Therefore, it can be transferred to other kinds of objects for use as a method.

23.1.3.24 Array.prototype.shift ( )

Note 1

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 2

The shift function 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.25 Array.prototype.slice ( start, end )

Note 1

The slice method takes two arguments, start and end, and 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.

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 2

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 3

The slice function 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.26 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 with one or two arguments, 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.27 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 value if x < y, zero if x = y, or a positive value if x > y.

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 items be a new empty List.
  5. Let k be 0.
  6. 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.
  7. Let itemCount be the number of elements in items.
  8. 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 or steps in this algorithm and return that completion.
  9. Let j be 0.
  10. Repeat, while j < itemCount,
    1. Perform ? Set(obj, ! ToString(𝔽(j)), items[j], true).
    2. Set j to j + 1.
  11. Repeat, while j < len,
    1. Perform ? DeletePropertyOrThrow(obj, ! ToString(𝔽(j))).
    2. Set j to j + 1.
  12. Return obj.

The sort order is the ordering, after completion of this function, of the integer-indexed property values of obj whose integer indexes are less than len. The result of the sort function is then determined as follows:

The sort order is implementation-defined if any of the following conditions is true:

  • If comparefn is not undefined and is not a consistent comparison function for the elements of items (see below).
  • If comparefn is undefined and SortCompare does not act as a consistent comparison function.
  • 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 above to be implementation-defined, items must satisfy all of the following conditions after executing step 8 of the algorithm above:

  • 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 (see SortCompare below), then π(j) < π(k).

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

A function comparefn is a consistent comparison function 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 <CF b means comparefn(a, b) < 0; a =CF b means comparefn(a, b) = 0 (of either sign); and a >CF b means comparefn(a, b) > 0.

  • Calling comparefn(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 <CF b, a =CF b, and a >CF b will be true for a given pair of a and b.
  • Calling comparefn(a, b) does not modify obj or any object on obj's prototype chain.
  • a =CF a (reflexivity)
  • If a =CF b, then b =CF a (symmetry)
  • If a =CF b and b =CF c, then a =CF c (transitivity of =CF)
  • If a <CF b and b <CF c, then a <CF c (transitivity of <CF)
  • If a >CF b and b >CF c, then a >CF c (transitivity of >CF)
Note 1

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

Note 2

The sort function 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.27.1 SortCompare ( x, y )

The abstract operation SortCompare takes arguments x and y. It also has access to the comparefn argument passed to the current invocation of the sort method. 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 the result of performing Abstract Relational Comparison xString < yString.
  8. If xSmaller is true, return -1𝔽.
  9. Let ySmaller be the result of performing Abstract Relational Comparison yString < xString.
  10. If ySmaller is true, return 1𝔽.
  11. Return +0𝔽.
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 5 and 6 have the potential to cause SortCompare to not behave as a consistent comparison function.

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

Note 1

When the splice method is called with two or more arguments start, deleteCount and zero or more items, the deleteCount elements of the array starting at integer index start are replaced by the elements of items. An Array object containing the deleted elements (if any) is returned.

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. If start is not present, then
    1. Let insertCount be 0.
    2. Let actualDeleteCount be 0.
  8. Else if deleteCount is not present, then
    1. Let insertCount be 0.
    2. Let actualDeleteCount be len - actualStart.
  9. Else,
    1. Let insertCount be the number of elements in items.
    2. Let dc be ? ToIntegerOrInfinity(deleteCount).
    3. Let actualDeleteCount be the result of clamping dc between 0 and len - actualStart.
  10. If len + insertCount - actualDeleteCount > 253 - 1, throw a TypeError exception.
  11. Let A be ? ArraySpeciesCreate(O, actualDeleteCount).
  12. Let k be 0.
  13. Repeat, while k < actualDeleteCount,
    1. Let from be ! ToString(𝔽(actualStart + k)).
    2. Let fromPresent be ? HasProperty(O, from).
    3. If fromPresent is true, then
      1. Let fromValue be ? Get(O, from).
      2. Perform ? CreateDataPropertyOrThrow(A, ! ToString(𝔽(k)), fromValue).
    4. Set k to k + 1.
  14. Perform ? Set(A, "length", 𝔽(actualDeleteCount), true).
  15. Let itemCount be the number of elements in items.
  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. 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.
    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. 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.
  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 of the result Array in step 20 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

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

The following steps are taken:

  1. Let array be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(array).
  3. Let separator be the String value for the list-separator String appropriate for the host environment's current locale (this is derived in an implementation-defined way).
  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 a separator String that has been derived in an implementation-defined locale-specific way. The result of calling this function is intended to be analogous to the result of toString, except that the result of this function is intended to be locale-specific.

Note 3

The toLocaleString function 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.30 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 object. Therefore it can be transferred to other kinds of objects for use as a method.

23.1.3.31 Array.prototype.unshift ( ...items )

Note 1

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 with zero or more arguments item1, item2, etc., 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 2

The unshift function 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.32 Array.prototype.values ( )

The following steps are taken:

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

23.1.3.33 Array.prototype [ @@iterator ] ( )

The initial value of the @@iterator property is the same function object as the initial value of the Array.prototype.values property.

23.1.3.34 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, "copyWithin", true).
  3. Perform ! CreateDataPropertyOrThrow(unscopableList, "entries", true).
  4. Perform ! CreateDataPropertyOrThrow(unscopableList, "fill", true).
  5. Perform ! CreateDataPropertyOrThrow(unscopableList, "find", true).
  6. Perform ! CreateDataPropertyOrThrow(unscopableList, "findIndex", true).
  7. Perform ! CreateDataPropertyOrThrow(unscopableList, "flat", true).
  8. Perform ! CreateDataPropertyOrThrow(unscopableList, "flatMap", true).
  9. Perform ! CreateDataPropertyOrThrow(unscopableList, "includes", true).
  10. Perform ! CreateDataPropertyOrThrow(unscopableList, "keys", true).
  11. Perform ! CreateDataPropertyOrThrow(unscopableList, "values", true).
  12. 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 object.

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 object 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 and kind. This operation is used to create iterator objects for Array methods that return such iterators. It performs the following steps when called:

  1. Assert: Type(array) is Object.
  2. Assert: kind is key+value, key, or value.
  3. 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 indexlen, return undefined.
      4. If kind is key, perform ? Yield(𝔽(index)).
      5. Else,
        1. Let elementKey be ! ToString(𝔽(index)).
        2. Let elementValue be ? Get(array, elementKey).
        3. If kind is value, perform ? Yield(elementValue).
        4. Else,
          1. Assert: kind is key+value.
          2. Perform ? Yield(! CreateArrayFromList𝔽(index), elementValue »)).
      6. Set index to index + 1.
  4. 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 }.