JavaScript Array : Object

constructor iterable

Arrays are containers that allow access to its items through numerical indices.

Spec

Array() : Array

Same as new Array().

Spec

Array(length : Number) : Array

Same as new Array(length).

Spec

Array(item0 : Object, [item1 : Object, [...]]) : Array

Same as new Array(item0, item1, ...).

Spec

Constructors

new Array() : Array

Creates an empty Array (length = 0). Can also be constructed as [].

Example:

// The following are equivalent
var x = [];
var y = Array();
var z = new Array();

Run

Results:

Spec

new Array(length : Number) : Array

Creates an Array of the specified length where each item starts as undefined.

Example:

var squares = Array(5);
for (var i = 0; i < squares.length; i++) {
  squares[i] = i * i;
}
console.log('squares = ' + squares);

Run

Results:

Spec

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 Array.of().

Example:

// The following are equivalent
var x = ['a', 'b', 'c'];
var y = Array('a', 'b', 'c');
var z = new Array('a', 'b', 'c');

Run

Results:

Spec

Instance Indexers

this[index : Number] : Object

Gets and sets the item in this at index. index should be between 0 and this.length - 1. If setting to an index greater than length - 1, length will be increased to index + 1.

Example:

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

Run

Results:

Instance Properties

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.

Example:

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;

Run

Results:

Spec

Instance Methods

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.

Example:

var x = [1, 2, 3];
var concatenated = x.concat(4, 5, [6, 7]);

console.log(concatenated);
console.log(concatenated.length);
console.log(x); // x is unchanged

Run

Results:

Spec

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.

Example:

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

Run

Results:

ECMAScript 2015 Spec

entries() : Iterator<Array>

Returns an iterator of the index and items in this where the values of the iterator are of the form [index : Number, item : Object]. See also values() and keys().

Example:

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());

Run

Results:

ECMAScript 2015 Spec

every(callback : Function, [thisArg : Object]) : Boolean

callback(item : Object, index : Number, array : Array) : 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.

Example:

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

Run

Results:

Spec

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.

Example:

var x = Array(5);

console.log(x.fill('a'));
console.log(x.fill('b', 3));
console.log(x.fill('c', 0, 2));

Run

Results:

ECMAScript 2015 Spec

filter(callback : Function, [thisArg : Object]) : Array

callback(item : Object, index : Number, array : Array) : Boolean

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.

Example:

var isEven = function(x) { return (x % 2) === 0; }
var numbers = [1, 2, 4, 5, 7, 9, 12];
console.log(numbers.filter(isEven));

Run

Results:

Spec

find(callback : Function, [thisArg : Object]) : Object

callback(item : Object, index : Number, array : Array) : Boolean

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

Example:

var x = ['a', 'b', 'foo', 'd', 'e'];

console.log(x.find(function(item) {
  return item.length > 1;
}));

Run

Results:

ECMAScript 2015 Spec

findIndex(callback : Function, [thisArg : Object]) : Number

callback(item : Object, index : Number, array : Array) : Boolean

Returns the index of the first item in this where callback returns true for that item. See also find() and indexOf().

Example:

var x = ['a', 'b', 'foo', 'd', 'e'];

console.log(x.findIndex(function(item) {
  return item.length > 1;
}));

Run

Results:

ECMAScript 2015 Spec

flat([depth = 1 : Number]) : Array

Returns a new Array by flattening sub arrays into the array up to the specified depth.

Example:

var x = [1, [2, 3], 4, [5, 6, [7, 8], 9]];
console.dir(x);
console.dir(x.flat());
console.dir(x.flat(2));

Run

Results:

ECMAScript 2019 Spec

flatMap(callback : Function, [thisArg : Object]) : Array

callback(item : Object, index : Number, array : Array) : Object

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

Example:

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

Run

Results:

ECMAScript 2019 Spec

forEach(callback : Function, [thisArg : Object]) : undefined

callback(item : Object, index : Number, array : Array) : undefined

Calls callback for each item in this. The Array passed to callback is the this of the call to forEach.

Example:

var x = ['a', 'b', 'c'];
x.forEach(function(item, index) {
  console.log('item at ' + index + ' = ' + item);
});

Run

Results:

Spec

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.

Example:

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'));

Run

Results:

ECMAScript 2016 Spec

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() and lastIndexOf().

Example:

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

Run

Results:

Spec

join([separator = ',' : String]) : String

Returns a String created by joining the toString() of each item of this separated by separator.

Example:

var x = ['a', 'b', 'c'];
console.log(x.join());
console.log(x.join(' -- '));

Run

Results:

Spec

keys() : Iterator<Number>

Returns an iterator of the indicies in this. See also entries() and values().

Example:

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());

Run

Results:

ECMAScript 2015 Spec

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

Example:

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

Run

Results:

Spec

map(callback : Function, [thisArg : Object]) : Array

callback(item : Object, index : Number, array : Array) : Object

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

Example:

var numbers = [1, 2, 3, 4];
var squares = numbers.map(function(x) { return x * x; });
console.log(squares);

Run

Results:

Spec

pop() : Object

Removes the last item from this and returns the removed item. Returns undefined if this is empty. Use with push to treat an Array as a stack.

Example:

var x = ['a', 'b', 'c']; 
console.log(x.pop());
console.log(x);

Run

Results:

Spec

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 to treat an Array as a stack.

Example:

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

Run

Results:

Spec

reduce(callback : Function, [initialValue : Object]) : Object

callback(previous : Object, current : Object, index : Number, array : Array) : 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-1th item as the previous parameter for the ith 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.

Example:

var join = function(prev, cur) { return prev + cur; } 
console.log(['b', 'c'].reduce(join, 'a'));

Run

Results:

Spec

reduceRight(callback : Function, [initialValue : Object]) : Object

callback(previous : Object, current : Object, index : Number, array : Array) : 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+1th item as the previous parameter for the ith 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.

Example:

var join = function(prev, cur) { return prev + cur; } 
console.log(['b', 'c'].reduceRight(join, 'a'));

Run

Results:

Spec

reverse() : Array

Reverses the order of the items in this and returns this.

Example:

var x = ['a', 'b', 'c']; 
console.log(x.reverse());
console.log(x);

Run

Results:

Spec

shift() : Object

Removes the first item of this and shifts the remaining items down by 1. Returns the removed item.

Example:

var x = ['a', 'b', 'c']; 
console.log(x.shift());
console.log(x);

Run

Results:

Spec

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.

Example:

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

Run

Results:

Spec

some(callback : Function, [thisArg : Object]) : Boolean

callback(item : Object, index : Number, array : Array) : 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.

Example:

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

Run

Results:

Spec

sort([comparisonFunction : Function]) : Array

comparisonFunction(x : Object, y : Object) : Number

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.

Example:

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

Run

Results:

Spec

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.

Example:

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

Run

Results:

Spec

unshift(item0 : Object, [item1 : Object, [...]]) : Number

Inserts the specified items at the start of this. Returns the new value of this.length.

Example:

var x = ['c', 'd', 'e'];
console.log(x.unshift('a', 'b'));
console.log(x);

Run

Results:

Spec

values() : Iterator

Returns an iterator of the items in this. The values function is also returned for this[Symbol.iterator] so you can iterate over this directly to get the values. See also entries() and keys().

Example:

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());

Run

Results:

ECMAScript 2015 Spec

Array Methods

from 2 variants

from(arrayLike : Object, [mapFunction : Function, [thisArg : Object]]) : Array

mapFunction(item : Object, index : Number) : Object

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

Example:

// 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));

Run

Results:

ECMAScript 2015 Spec

from(iterator : Iterator, [mapFunction : Function, [thisArg : Object]]) : Array

mapFunction(item : Object, index : Number) : Object

Returns a new Array containing the items returned by iterator.

Example:

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

Run

Results:

ECMAScript 2015 Spec

isArray(value : Object) : Boolean

Returns true if value is an Array.

Example:

console.log(Array.isArray([]));
console.log(Array.isArray({}));
console.log(Array.isArray(53));

Run

Results:

Spec

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(x) will create an array of length x if x is an integer (and throw an exception if x is a non-integer Number).

Example:

// 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');

Run

Results:

ECMAScript 2015 Spec

home license contribute feedback