Array : Object
Arrays are containers that allow access to its items
through numerical indices.
Iterable:
true
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4
----
Array() : Array
Same as %%#new_Array|**new Array()**%%.
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.1
----
Array(length:Number) : Array
Same as %%#new_Array_Number|**new Array(length)**%%.
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.1.1
----
Array(item0:Object, [item1:Object, [...]]) : Array
Same as %%#new_Array_Object_Object_dotdotdot|**new Array(item0, item1, ...)**%%.
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.1.1
----
new Array() : Array
Creates an empty **Array** (**length** = 0).
Can also be constructed as **[]**.
// The following are equivalent
var x = [];
var y = Array();
var z = new Array();
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.2
----
new Array(length:Number) : Array
Creates an **Array** of the specified length where each item starts as **undefined**.
var squares = Array(5);
for (var i = 0; i < squares.length; i++) {
squares[i] = i * i;
}
console.log('squares = ' + squares);
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.2.1
----
new Array(item0:Object, [item1:Object, [...]]) : Array
Creates an **Array** with the specified parameters as the 0th, 1st, ... items
of the **Array**.
Can also be constructed as **[item0, item1, ...]**.
See also %%#of|**Array.of()**%%.
// The following are equivalent
var x = ['a', 'b', 'c'];
var y = Array('a', 'b', 'c');
var z = new Array('a', 'b', 'c');
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.2.1
----
instance[index : Number] : Object
Gets and sets the item in **this** at **index**. **index** should be between **0** and
**%%#length|this.length%% - 1**. If setting to an index greater than
**length - 1**, **length** will be increased to **index + 1**.
var x = ['a', 'b', 'c'];
for (var i = 0; i < x.length; i++) {
console.log(x[i]);
}
console.log(x.length);
x[7] = 'h';
console.log(x[7]);
console.log(x.length);
----
instance.length : Number
The number of items in **this**. It is 1 greater than the index of the last item.
Setting **length** to a smaller number than the current **length** will remove
elements from the end of the list.
console.log([].length);
console.log(['a', 'b', 'c'].length);
console.log(Array(100).length);
var x = [];
// Assigning to an index automatically adjusts length
x[50] = 'foo';
console.log(x.length);
// Set length to 0 to clear the list.
x.length = 0;
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.5.2
----
prototype.concat(item0:Object, [item1:Object, [...]]) : Array
Returns a new Array composed of the items of **this** followed by
**item0, item1, ...**.
If any of the parameters are Arrays themselves, the values of that Array
will be concatenated into the new Array.
See also %%#push|push%%.
var x = [1, 2, 3];
var concatenated = x.concat(4, 5, [6, 7]);
console.dir(concatenated);
console.log(concatenated.length);
console.dir(x); // x is unchanged
// The spread operator (...) also allows concatenating.
var spread = [...x, 4, 5, ...[6, 7]];
console.dir(spread);
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.4
----
prototype.copyWithin(target : Number, start : Number, [end : Number]) : Array
Copies **this[start], this[start + 1], ... this[end - 1]** to
**this[target], this[target + 1], ... this[target + start - end - 1]**.
If **end** is not specified, **this.length** will be used.
If **end** is greater than **this.length**, it is clamped to
**this.length**.
Note, no elements are copied past **this.length - 1** (ie, **copyWithin()**
will not increase the length of **this**).
Returns **this**.
var x = ['a', 'b', 'c', 'd', 'e', 'f'];
// Copy elements at end to the beginning
console.log(x.copyWithin(0, 3));
x = ['a', 'b', 'c', 'd', 'e', 'f'];
// Copy elements at the beginning to the end
console.log(x.copyWithin(3, 0));
x = ['a', 'b', 'c', 'd', 'e', 'f'];
// Copy first 3 elements to middle
console.log(x.copyWithin(2, 0, 3));
Version:
ECMAScript 2015
Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.copywithin
----
prototype.entries() : Iterator
Returns an iterator of the index and items in **this** where the
%%Iterator#next|**value**s%% of the iterator are of the form
**[index : %%/Number|Number%%, item : %%/Object|Object%%]**.
See also %%#values|**values()**%% and %%#keys|**keys()**%%.
var x = ['a', 'b'];
// Use for (... of ...) to loop over the iterator
for (var entry of x.entries()) {
console.dir(entry);
}
// Or access the iterator manually
var entries = x.entries();
console.dir(entries.next());
console.dir(entries.next());
console.dir(entries.next());
Version:
ECMAScript 2015
Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.entries
----
prototype.every(callback(item:Object, index:Number, array:Array):Boolean, [thisArg : Object]) : Boolean
Returns **true** if **callback** returns **true** for every item in **this**.
Otherwise returns **false**.
The **Array** passed to **callback** is the **this** of the call to **every**.
var isEven = function(x) { return (x % 2) === 0; }
console.log([2, 22, 36].every(isEven));
console.log([6, 19, 18].every(isEven));
console.log([5, 19, 17].every(isEven));
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.16
----
prototype.filter(callback(item:Object, index:Number, array:Array):Boolean, [thisArg:Object]):Array
Returns a new **Array** containing only the items in **this** that **callback** returned
**true** for.
The **Array** passed to **callback** is the **this** of the call to **filter**.
var isEven = function(x) { return (x % 2) === 0; }
var numbers = [1, 2, 4, 5, 7, 9, 12];
console.log(numbers.filter(isEven));
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.20
----
prototype.fill(value : Object, [start = 0 : Number, [end : Number]]) : Array
Fills **this[start]**, **this[start + 1]**, ... **this[end - 1]** with
**value**.
If **end** is not specified, **this.length** is used.
Returns **this**.
var x = Array(5);
console.log(x.fill('a'));
console.log(x.fill('b', 3));
console.log(x.fill('c', 0, 2));
Version:
ECMAScript 2015
Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.fill
----
prototype.find(callback(item:Object, index:Number, array:Array):Boolean, [thisArg : Object]) : Object
Returns the first item in **this** where **callback** returns
**true** for that item.
The **Array** passed to **callback** is the **this** of the call to **find**.
See also %%#findIndex|**findIndex()**%%.
var x = ['a', 'b', 'foo', 'd', 'e'];
console.log(x.find(function(item) {
return item.length > 1;
}));
Version:
ECMAScript 2015
Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.find
----
prototype.findIndex(callback(item:Object, index:Number, array:Array):Boolean, [thisArg : Object]) : Number
Returns the index of the first item in **this** where **callback** returns
**true** for that item.
See also %%#find|**find()**%% and %%#indexOf|**indexOf()**%%.
var x = ['a', 'b', 'foo', 'd', 'e'];
console.log(x.findIndex(function(item) {
return item.length > 1;
}));
Version:
ECMAScript 2015
Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.findIndex
----
prototype.flat([depth = 1 : Number]):Array
Returns a new Array by flattening sub arrays into the array up to the specified
**depth**.
var x = [1, [2, 3], 4, [5, 6, [7, 8], 9]];
console.dir(x);
console.dir(x.flat());
console.dir(x.flat(2));
Version:
ECMAScript 2019
Spec:
https://tc39.es/ecma262/#sec-array.prototype.flat
----
prototype.flatMap(callback(item:Object, index:Number, array:Array):Object, [thisArg:Object]):Array
Returns a new **Array** with where each item is the result of calling
**callback** on each item in **this**. If the return of **callback** is an Array,
that Array will be flattened into the Array returned by **flatMap**.
See also %%#map|**map()**%%.
var x = [1, 2, 3];
var callback = (i, index) => [i, i * index];
var y = x.flatMap(callback);
console.dir(y);
// flatMap is essentially equivalent to:
var z = x.map(callback).flat();
console.dir(z);
Version:
ECMAScript 2019
Spec:
https://tc39.es/ecma262/#sec-array.prototype.flatmap
----
prototype.forEach(callback(item:Object, index:Number, array:Array):undefined, [thisArg:Object]):undefined
Calls **callback** for each item in **this**.
The **Array** passed to **callback** is the **this** of the call to **forEach**.
var x = ['a', 'b', 'c'];
x.forEach(function(item, index) {
console.log('item at ' + index + ' = ' + item);
});
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.18
----
prototype.indexOf(item:Object, [startingIndex = 0 : Number]):Number
Returns the first location of **item** in **this** starting the search from
**start**.
If **startingIndex**
is negative, **this.length** is added to it before starting the search.
Returns **-1** if **item** is not found.
See also %%#findIndex|**findIndex()**%% and %%#lastIndexOf|**lastIndexOf()**%%.
var x = ['a', 'b', 'c', 'd', 'b', 'c', 'a'];
console.log(x.indexOf('b'));
console.log(x.indexOf('b', 2));
console.log(x.indexOf('b', -4));
console.log(x.indexOf('e', 2));
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.14
----
prototype.join([separator=',':String]):String
Returns a String created by joining the **toString()** of each item of
**this** separated by **separator**.
var x = ['a', 'b', 'c'];
console.log(x.join());
console.log(x.join(' -- '));
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.5
----
prototype.keys() : Iterator
Returns an iterator of the indicies in **this**.
See also %%#entries|**entries()**%% and %%#values|**values()**%%.
var x = ['a', 'b'];
// Use for (... of ...) to loop over the iterator
for (var key of x.keys()) {
console.dir(key);
}
// Or access the iterator manually
var keys = x.keys();
console.dir(keys.next());
console.dir(keys.next());
console.dir(keys.next());
Version:
ECMAScript 2015
Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.keys
----
prototype.lastIndexOf(item:Object, [startingIndex:Number]):Number
Returns the location of **item** by searchig backwards through
**this**, starting the search from **startingIndex**.
If **startingIndex** is not specified, the search starts from the
end of the array.
If **startingIndex** is negative, **this.length** is added to it
before starting the search.
Returns **-1** if **item** is not found.
See also %%#indexOf|**indexOf()**%%.
var x = ['a', 'b', 'c', 'd', 'b', 'c', 'a'];
console.log(x.lastIndexOf('b'));
console.log(x.lastIndexOf('b', 3));
console.log(x.lastIndexOf('b', -4));
console.log(x.lastIndexOf('e', 2));
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.15
----
prototype.map(callback(item:Object, index:Number, array:Array):Object, [thisArg:Object]):Array
Returns a new **Array** with where each item is the result of calling
**callback** on each item in **this**.
The **Array** passed to **callback** is the **this** of the call to **map**.
See also %%#flatMap|**flatMap()**%%.
var numbers = [1, 2, 3, 4];
var squares = numbers.map(function(x) { return x * x; });
console.log(squares);
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.19
----
prototype.pop():Object
Removes the last item from **this** and returns the removed item.
Returns **undefined** if **this** is empty.
Use with %%#push|**push**%% to treat an **Array** as a stack.
var x = ['a', 'b', 'c'];
console.log(x.pop());
console.log(x);
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.6
----
prototype.push(item0:Object, [item1:Object, [...]]):Number
Appends the specified items to the end of **this** and returns the new
value of **this.length**. Use with %%#pop|**pop**%% to treat an **Array** as a
stack.
var x = ['a', 'b', 'c'];
console.log(x.push('d', 'e'));
console.log(x);
// Use with the spread operator (...) to push all elements of an array
var y = ['x', 'y', 'z'];
x.push(...y);
console.log(x);
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.7
----
prototype.reduce(callback(previous:Object, current:Object,index:Number,array:Array):Object, [initialValue:Object]):Object
Calls **callback** for each item in **this** in ascending order (**0** to **length-1**).
It passes the return value of **callback** for the **i-1**th item as the
**previous** parameter for the **i**th item.
Returns the result from the last call to **callback**.
If **initialValue** is not specified, **callback** will first
be called on **this[1]** with **previous** set to **this[0]**.
The **Array** passed to **callback** is the **this** of the call to **reduce**.
var join = function(prev, cur) { return prev + cur; }
console.log(['b', 'c'].reduce(join, 'a'));
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.21
----
prototype.reduceRight(callback(previous:Object, current:Object,index:Number,array:Array):Object, [initialValue:Object]):Object
Calls **callback** for each item in **this** in descending order (**length-1** to **0**).
It passes the return value of **callback** for the **i+1**th item as the
**previous** parameter for the **i**th item.
Returns the result from the last call to **callback**.
If **initialValue** is not specified, **callback** will first
be called on **this[this.length - 2]** with **previous** set to **this[this.length - 1]**.
The **Array** passed to **callback** is the **this** of the call to **reduceRight**.
var join = function(prev, cur) { return prev + cur; }
console.log(['b', 'c'].reduceRight(join, 'a'));
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.22
----
prototype.reverse() : Array
Reverses the order of the items in **this** and returns **this**.
var x = ['a', 'b', 'c'];
console.log(x.reverse());
console.log(x);
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.8
----
prototype.shift():Object
Removes the first item of **this** and shifts the
remaining items down by **1**. Returns the removed item.
var x = ['a', 'b', 'c'];
console.log(x.shift());
console.log(x);
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.9
----
prototype.slice(start:Number, [end:Number]):Array
Returns a new **Array** which is composed of the items **this[start],
this[start + 1], ..., this[end - 1]**. Note that
**item[end]** is not included. If **start** or **end**
is negative, the value is added to **this.length** before performing
the slice. If **end** is not specified, **this.length** is used.
var x = ['a', 'b', 'c', 'd', 'e'];
console.log(x.slice(2));
console.log(x.slice(2, 3));
console.log(x.slice(1, -2));
console.log(x.slice(-4, -1));
console.log(x);
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.10
----
prototype.some(callback(item : Object, index : Number, array:Array):Boolean, [thisArg:Object]) : Boolean
Returns **true** if **callback** returns **true** for at least one item in
**this**. Otherwise returns **false**.
The **Array** passed to **callback** is the **this** of the call to **some**.
var isEven = function(x) { return (x % 2) === 0; }
console.log([2, 22, 36].some(isEven));
console.log([6, 19, 18].some(isEven));
console.log([5, 19, 17].some(isEven));
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.17
----
prototype.sort([comparisonFunction(x:Object, y:Object):Number]):Array
Sort the items of **this** using **comparisonFunction** to determine
the sort order and returns **this**.
The Number returned by **comparisonFunction** should be **0** if **x** and
**y** are equal, negative if **x** is less than **y**, or positive if **x**
is greater than **y**. If **comparisonFunction** is not specified, the **toString()**
of the items will be sorted in alphanumeric order.
Returns **this**.
var x = [52, 7, 14, 22, 9];
// Sort alphanumerically
console.log(x.sort());
console.log(x);
// Sort numerically
var numericComparison = function(x, y) {
return x - y;
};
console.log(x.sort(numericComparison));
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.11
----
prototype.splice(start:Number, count:Number, [item0:Object, [item1:Object, [...]]]):Array
Removes **count** items from **this** starting at index
**start**. If the optional **items** are specified, they are
inserted into **this** at **start**. Returns a new **Array** containing
the removed items.
var x = ['a', 'b', 'c', 'd', 'e'];
console.log(x.splice(2, 1));
console.log(x);
console.log(x.splice(1, 2, 'X', 'Y', 'Z'));
console.log(x);
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.12
----
prototype.unshift(item0:Object, [item1:Object, [...]]):Number
Inserts the specified items at the start of **this**.
Returns the new value of **this.length**.
var x = ['c', 'd', 'e'];
console.log(x.unshift('a', 'b'));
console.log(x);
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.4.13
----
prototype.values() : Iterator
Returns an iterator of the items in **this**.
The **values** function is also returned for
**this[%%/Symbol#iterator|Symbol.iterator%%]** so you can
iterate over **this** directly to get the values.
See also %%#entries|**entries()**%% and %%#keys|**keys()**%%.
var x = ['a', 'b'];
// values is returned by x[Symbol.iterator] so you can just
// use x directly in the for (... of ...) loop
for (var value of x) {
console.dir(value);
}
// You can iterate over values explicitly
for (var value of x.values()) {
console.dir(value);
}
// Or access the iterator manually
var values = x.values();
console.dir(values.next());
console.dir(values.next());
console.dir(values.next());
Version:
ECMAScript 2015
Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-array.prototype.values
----
prototype.includes(item : Object, [startingIndex = 0 : Number]) : Boolean
Returns **true** if **item** is an element of **this** starting the search from
**startingIndex**. If **startingIndex** is negative, **this.length** is added to it before
starting the search.
var x = ['a', 'b', 'c', 'd'];
console.log(x.includes('b'));
console.log(x.includes('b', 2));
console.log(x.includes('a', -2));
console.log(x.includes('e'));
Version:
ECMAScript 2016
Spec:
http://www.ecma-international.org/ecma-262/7.0/#sec-array.prototype.includes
----
from(arrayLike : Object, [mapFunction(item : Object, index : Number) : Object, [thisArg : Object]]) : Array
Returns a new **Array** with the elements of **arrayLike**.
**from()** will return
a new **Array** of length **arrayLike.length** where the elements are
**arrayLike[0]**, **arrayLike[1]**, ..., **arrayLike[arrayLike.length - 1]**.
// From a string
console.log(Array.from('foo'));
// With a map function
var mapFunction = function(value) {
return value.toUpperCase();
};
console.log(Array.from('foo', mapFunction));
Version:
ECMAScript 2015
Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-array.from
----
from(iterator : Iterator, [mapFunction(item : Object, index : Number) : Object, [thisArg : Object]]) : Array
Returns a new **Array** containing the items returned by **iterator**.
var generator = function*() {
yield "foo";
yield* ["bar", "baz"];
};
console.log(Array.from(generator()));
// With a map function
var mapFunction = function(value) {
return value.toUpperCase();
};
console.log(Array.from(generator(), mapFunction));
Version:
ECMAScript 2015
Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-array.from
----
isArray(value : Object) : Boolean
Returns **true** if **value** is an **Array**.
console.log(Array.isArray([]));
console.log(Array.isArray({}));
console.log(Array.isArray(53));
Spec:
http://www.ecma-international.org/ecma-262/5.1/#sec-15.4.3.2
----
of(item0 : Object, [item1 : Object, [...]]) : Array
Creates an **Array** with the specified parameters as the
0th, 1st, ... items of the **Array**.
Can also be constructed as **[item0, item1, ...]**.
Note that **Array.of(x)** will always create an array of length **1**
containing **x**,
while %%#new_Array_Number|**new Array(x)**%% will create
an array of length **x** if **x** is an integer (and throw an exception
if **x** is a non-integer %%/Number|Number%%).
// The following are equivalent
var w = ['a', 'b', 'c'];
var x = Array('a', 'b', 'c');
var y = new Array('a', 'b', 'c');
var z = Array.of('a', 'b', 'c');
Version:
ECMAScript 2015
Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-array.of