The JavaScript Array Object

A JavaScript array is an ordered collection of elements selected by one or more indices. As oposed to scalar variables such as numbers and strings, an array is a data structure used to store a variable number of values of different types.

Array values can be other arrays, thus making it possible to create more complex data structures such as multidimensional arrays and trees. An array with a single dimension is often called a vector, whereas a multidimensional array is called a matrix.

Array indices (or keys) may be either integers or strings. However, arrays should not be used as associative arrays. JavaScript arrays are essentially objects, thus setting string keys means setting properties on those objects. Object should be used instead.

Array Syntax

JavaScript arrays are declared using the Array object to construct Array instances or by using the literal array syntax:

var array1 = new Array(arrayLength);

Creates an array with an initial length set to the specified value. The value must be specified as an unsigned integer.

var array2 = new Array(element0, element1, ...);

Creates an array with the specified values as its elements.

Arguments are optional in both cases.

Creating an array using the Array constructor may be a bit confusing and there's a slight chance of undesired results. Therefore it is best to avoid it in favor of the more concise literal form:

var array3 = [element0, element1, ...];

The result is the same. JavaScript takes care of converting between array objects and array primitives. As such, the methods of the Array object are available and can be called on array primitives.

Accessing array elements

Array elements can be referred to by their index using the special square bracket notation. For example:

var fruits = ["apples", "oranges", "grapes"];
fruits[0]; // apples
fruits[2]; // grapes
fruits[1]; // oranges

Note that the first element has the index 0.

Array Properties

constructor
Returns a reference to the function that created the Array object
length
Returns the number of elements in an array
prototype
Allows the addition of properties and methods to all objects

Special Array properties

These properties are not inherited by default and are only available with arrays created by regular expression matches.

index
Returns the index of the match in the string
input
Returns the string against which the regular expression was matched

Array Methods

concat(array1 [, array2 [, ...]])
Creates a new array by joining two or more arrays
every(callback [, object])
Returns true if the callback function returns true for every element in the array
filter(callback [, contextObject])
Filters the elements of an array using a callback function
forEach(callback [, contextObject])
Apply a callback function to every element of the array
join([separator])
Join the elements of the array into a string using a separator
map(callback [, contextObject])
Apply a callback function to every element of the array
pop()
Removes the last element of the array and returns that element
push(element0 [, element1 [, ...]])
Appends one or more elements to the end of the array and returns the new length of the array
reduce(callback [, initialValue])
Reduce the array to a single value using a callback function from left-to-right
reduceRight(callback [, initialValue])
Reduce the array to a single value using a callback function from right-to-left
reverse()
Reverses the order of the elements in the array
shift()
Removes the first element of the array and returns that element
slice(offset [, length])
Extracts a section of the array and returns a new array containing the extracted elements
some(callback [, contextObject])
Returns true if the callback function returns true for at least one element in the array
sort([compare_function])
Sorts the array optionally using a callback function
splice(offset , length [, element1 [, element2 [, ...]]])
Replaces elements from the array with something else
toString()
Returns a string representation of the array
unshift(element0 [, element1 [, ...]])
Prepend one or more elements to the front of the array and returns the new length of the array
valueOf()
Returns the primitive value of the array

See also

If you see a typo, want to make a suggestion or have anything in particular you'd like to know more about, please drop us an e-mail at hello at diveintojavascript dot com.

Copyright © 2010-2013 Dive Into JavaScript