This page is Ready to Use

Notice: The WebPlatform project, supported by various stewards between 2012 and 2015, has been discontinued. This site is now available on github.

Array

Summary

Provides support for creation of arrays of any data type.

Array is an object used to list values together. When you create an array, you’re setting up a list that you can fill with key:value pairs. You can then refer to a whole list using just that one array name. You can also refer to one item in the list using the key, also called an index when the key is a number.

Syntax

[ element0 [, element1 [, ...[, elementN ]]]]

new Array([ element0 [, element1 [, ...[, elementN ]]]])

new Array([ length ])
element0,…,elementN
Optional. The elements to place in the array. This creates an array with n + 1 elements, and a length of n + 1. Using this syntax, you must supply more than one element.
length
Optional. The length of the array. As arrays are zero-based, created elements will have indexes from zero to size -1.

Return Value

When no arguments are provided, creates and returns a new Array object, with a length property (whose initial value is +0).

When multiple arguments are provided, creates and returns a new Array object with the elements provided, with a length property the number of arguments + 1.

And if only one Number is provided as the argument, with argument len is a Number and ToUint32(len) (an unsigned 32-bit integer), then the length property of the newly constructed object is set to ToUint32(len).

If the only argument is a Number and ToUint32(len) is not equal to len, a RangeError exception is thrown.

If the only argument is not a Number, then the length property of the newly constructed object is set to 1 and the 0 property of the newly constructed object is set to len.

Examples

After an array is created, you can access the individual elements of the array by using [n] notation. Note that unlike other programming languages, arrays keys are only numeric. Keys starts by 0.

// Literal notation
var my_array = [];
for (i = 0; i < 10; i++) {
  my_array[i] = i;
}
x = my_array[4];
document.write(x);
// Output: 4

View live example

You can pass an unsigned 32-bit integer to the Array constructor to specify the size of the array. If the value is negative or not an integer, a run-time error occurs. If you run the following code, you should see this error in the Console.

var arr = new Array(10);
document.write(arr.length);
// Output: 10

// Don't do this
var arr = new Array(-1);
arr = new Array(1.50);

View live example

If a single value is passed to the Array constructor, and it is not a number, the length property is set to 1, and the value of the only element becomes the single, passed-in argument.

var arr = new Array("one");
 document.write(arr.length);
 document.write(arr[0]);

 // Output:
 // 1
 // one

View live example

Adding members, to an array can be done by using the prototypal inheritance chain and call the push() method on it.

var ponies = ['Twilight Sparkle','Pinkie Pie','Rainbow Dash'];

// Adding a new member
ponies.push('Spike');
console.log(ponies[3]);

// Output:
// Spike

View live example

Remarks

JavaScript arrays are referred to as “sparse,” which means that elements in an array can be undefined and deleted. The keys, or index, are not reordered into a denser table, unless you do so, explicitly.

Usage

 Array is a standard, built-in object. Among other things, this means you can create a new array by using the object creation expression new Array(), as in:

var myArray = new Array();

But a more efficient way is to use what’s called the literal notation. An array literal is created without using the new keyword. Instead, you use the square brackets [] and list out what should be in the array:

var myAnimals = ["cat", "dog", "rabbit"];

Using an array literal to declare your array this way avoids some of the quirkiness of the creation expression new Array(). (For more information, see Stoyan Stefanov’s JavaScript Patterns.) Your array can consist of different values and types. Here’s an array that provides describes my dog:

var goodDog = ["Rover", 7, true];

This array combines a string, a number and a Boolean value. An array is often called a zero-indexed, or as having a zero-based index, because the numerical key, or index, starts at zero. (prof.dr. Edsger W. Dijkstra gives a reason why numbering should start at zero.) This means you can refer to the items in your array by referencing the index. So in goodDog, above, you reference the dog’s name with goodDog[0], or his age with goodDog[1], or whether he is, indeed, a good dog with goodDog[2]. Arrays can be dimensional as well. This helps when your setting up something that has row and column patterns, such as seats in a theatre or a checkerboard. So, for example, to describe a college dormitory that has 5 beds per floor and 2 floors, you can set up a two-dimensional array that looks like the following:

var dorm = [[1,1], [1,2], [1,3], [1,4], [1,5],
            [2,1], [2,2], [2,3], [2,4], [2,5]];

Arrays are a useful kind of object for many reasons. For example, because the keys are numerical indexes by default, it’s easy to iterate, or loop, through all of the values. They also have special properties that other objects don’t have. But if your array becomes more complex, you may want to consider using an object instead.

Properties

The following table lists the properties of the Array object.

PropertySummary
constructorReferences the function which created the instance of the Array object.
lengthBasically specifies the number of elements (AKA length) in an Array object. This means the length property represents a number one greater than the largest index defined in an Array object.
prototypeReturns a reference to the prototype for a class of array.

Functions

The following table lists the functions of the Array object.

Methods

The following table lists the methods of the Array object.

MethodSummary
concatCombines two or more arrays.
everyDetermines whether all the members of an array satisfy the specified test.
filterReturns the elements of an array that meet the condition specified in a callback function.
forEachPerforms the specified action for each element in an array.
indexOfReturns the index of the first occurrence of a value in an array.
isArrayDetermines whether an object is an array.
joinAdds all the elements of an array separated by the specified separator string.
lastIndexOfReturns the index of the last occurrence of a specified value in an array.
mapCalls a defined callback function on each element of an array, and returns an array that contains the results.
popRemoves the last element from an array and returns it.
pushAppends new elements to an array, and returns the new length of the array.
reduceCalls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
reduceRightCalls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
reverseReverses the elements in an Array.
shiftRemoves the first element from an array and returns it.
sliceReturns a section of an array.
someDetermines whether the specified callback function returns true for any element of an array.
sortSorts an Array.
spliceRemoves elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.
toStringReturns a string representation of an array.
unshiftInserts new elements at the start of an array.
valueOfReturns the primitive value of the specified object.
hasOwnPropertyDetermines whether an object has a property with the specified name.
isPrototypeOfDetermines whether an object exists in another object’s prototype chain.
propertyIsEnumerableDetermines whether a specified property is enumerable.
toLocaleStringReturns a date converted to a string using the current locale.

See also

External resources

Specification

15.4 Array Objects

ECMAScript® Language Specification Standard ECMA-262 5.1 Edition / June 2011

Attributions

  • Microsoft Developer Network: Article