Array

Summary

The JavaScript Array global object is a constructor for arrays, which are high-level, list-like objects.

Syntax

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

element0, element1, ..., elementN

A JavaScript array is initialized with the given elements, except in the case where a single argument is passed to the Array constructor and that argument is a number. (See below.) Note that this special case only applies to JavaScript arrays created with the Array constructor, not with array literals created with the bracket syntax.

arrayLength

If the only argument passed to the Array constructor is an integer between 0 and 2³²-1 (inclusive), this returns a new JavaScript array with length set to that number and  containing that many items, each item being undefined. If the argument is any other number, a RangeError exception is thrown.

Description

Arrays are list-like objects that come with a several built-in methods to perform traversal and mutation operations. Neither the size of a JavaScript array nor the types of its elements are fixed. Since an array's size can grow or shrink at any time, JavaScript arrays are not guaranteed to be dense. In general, these are convenient characteristics; but if these features are not desirable for your particular use case, you might consider using WebGL typed arrays.

Note that you shouldn't use an array as an associative array. You can use plain objects instead, although doing so comes with its own caveats. See the post Lightweight JavaScript dictionaries with arbitrary keys as an example.

Accessing array elements

JavaScript arrays are zero-indexed; the first element of an array is actually at index 0, and the last element is at the index equal to the value of the array's length property minus 1.

var arr = ["this is the first element", "this is the second element"];
console.log(arr[0]);              // prints "this is the first element"
console.log(arr[1]);              // prints "this is the second element"
console.log(arr[arr.length - 1]); // prints "this is the second element"

Array elements are just object properties, in the way that toString is a property. However, note that trying to access the first element of an array as follows will throw a syntax error:

console.log(arr.0);

Note that there is nothing unique about JavaScript arrays and their properties that causes this. JavaScript properties that begin with a digit cannot be referenced with dot notation. They must be accessed using bracket notation. For example, if you had an object with a property "3d", it too would have to be referenced using bracket notation, not dot notation. This similarity is exhibited in the following two code samples:

var years = [1950, 1960, 1970, 1980, 1990, 2000, 2010];
try {
  console.log(years.0);
} catch (ex) {
  console.log("Using bracket notation");
  console.log(years[0]);
}

try {
  renderer.3d.setTexture(model, "character.png");
} catch (ex) {
  console.log("Using bracket notation");
  renderer["3d"].setTexture(model, "character.png");
}

Note that in the 3d example, "3d" had to be quoted. It's possible to quote the JavaScript array indexes as well (e.g., years["2"] instead of years[2]), although it's not necessary. The 2 in years[2] eventually gets coerced into a string by the JavaScript engine, anyway, through an implicit toString conversion. It is for this reason that "2" and "02" would refer to two different slots on the years object and the following example logs true:

console.log(years["2"] != years["02"]);

Relationship between length and numerical properties

A JavaScript array's length property and numerical properties are connected. Several of the built-in array methods (e.g., join, slice, indexOf, etc.) take into account the value of an array's length property when they're called. Other methods (e.g., push, splice, etc.) also result in updates to an array's length property.

var fruits = [];
fruits.push("banana", "apple", "peach");

console.log(fruits.length); // 3

When setting a property on a JavaScript array when the property is a valid array index and that index is outside the current bounds of the array, the engine will update the array's length property accordingly:

fruits[5] = "mango";
console.log(fruits[5]); // "mango"
console.log(Object.keys(fruits));  // ["0", "1", "2", "5"]
console.log(fruits.length); // 6

Increasing the length property does not create additional elements.

fruits.length = 10;
console.log(Object.keys(fruits)); // ["0", "1", "2", "5"]
console.log(fruits.length); // 10

fruits.length = 2;
console.log(Object.keys(fruits)); // ["0", "1"]
console.log(fruits.length); // 2

Creating an array using the result of a match

The result of a match between a regular expression and a string can create a JavaScript array. This array has properties and elements that provide information about the match. An array is the return value of RegExp.exec, String.match, and String.replace. To help explain these properties and elements, look at the following example and then refer to the table below:

// Match one d followed by one or more b's followed by one d
// Remember matched b's and the following d
// Ignore case

var myRe = /d(b+)(d)/i;
var myArray = myRe.exec("cdbBdbsbz");

The properties and elements returned from this match are as follows:

Properties

For properties available on Array instances, see Properties of Array instances.

prototype

Allows the addition of properties to all objects.

Methods

isArray Requires JavaScript 1.8.5

Return true if a variable is an array, if not false.

Array generic methods

Sometimes you would like to apply array methods to strings or other array-like objects (such as function arguments). By doing this, you treat a string as an array of characters (or otherwise treat a non-array as an array). For example, in order to check that every character in the variable str is a letter, you would write:

function isLetter(character) {
  return character >= "a" && character <= "z";
}

if (Array.prototype.every.call(str, isLetter)) {
    console.log("The string '" + str + "' contains only letters!");
}

This notation is rather wasteful and JavaScript 1.6 introduced a generic shorthand:

if (Array.every(isLetter, str)) {
    console.log("The string '" + str + "' contains only letters!");
}

Generics are also available on String.

These are currently not part of ECMAScript standards (though the ES6 Array.from() can be used to achieve this). The following is a shim to allow its use in all browsers:

// Assumes Array extras already present (one may use polyfills for these as well)
(function () {
    'use strict';

    var i,
        // We could also build the array of methods with the following, but the
        //   getOwnPropertyNames() method is non-shimable:
        // Object.getOwnPropertyNames(Array).filter(function (methodName) {return typeof Array[methodName] === 'function'});
        methods = [
            'join', 'reverse', 'sort', 'push', 'pop', 'shift', 'unshift',
            'splice', 'concat', 'slice', 'indexOf', 'lastIndexOf',
            'forEach', 'map', 'reduce', 'reduceRight', 'filter',
            'some', 'every'
        ],
        methodCount = methods.length,
        assignArrayGeneric = function (methodName) {
            if (!Array[methodName]) {
                var method = Array.prototype[methodName];
                if (typeof method === 'function') {
                    Array[methodName] = function () {
                        return method.call.apply(method, arguments);
                    };
                }
            }
        };

    for (i = 0; i < methodCount; i++) {
        assignArrayGeneric(methods[i]);
    }
}());

Examples

Example: Creating an array

The following example creates an array, msgArray, with a length of 0, then assigns values to msgArray[0] and msgArray[99], changing the length of the array to 100.

var msgArray = [];
msgArray[0] = "Hello";
msgArray[99] = "world";

if (msgArray.length === 100) {
    console.log("The length is 100.");
}

Example: Creating a two-dimensional array

The following creates a chess board as a two dimensional array of strings. The first move is made by copying the 'p' in (6,4) to (4,4). The old position 6,4 is made blank.

var board = [ 
    ['R','N','B','Q','K','B','N','R'],
    ['P','P','P','P','P','P','P','P'],
    [' ',' ',' ',' ',' ',' ',' ',' '],
    [' ',' ',' ',' ',' ',' ',' ',' '],
    [' ',' ',' ',' ',' ',' ',' ',' '],
    [' ',' ',' ',' ',' ',' ',' ',' '],
    ['p','p','p','p','p','p','p','p'],
    ['r','n','b','q','k','b','n','r'] ];

console.log(board.join('\n') + '\n\n');

// Move King's Pawn forward 2
board[4][4] = board[6][4];
board[6][4] = ' ';
console.log(board.join('\n'));

Here is the output:

R,N,B,Q,K,B,N,R
P,P,P,P,P,P,P,P
 , , , , , , , 
 , , , , , , , 
 , , , , , , , 
 , , , , , , , 
p,p,p,p,p,p,p,p
r,n,b,q,k,b,n,r

R,N,B,Q,K,B,N,R
P,P,P,P,P,P,P,P
 , , , , , , , 
 , , , , , , , 
 , , , ,p, , , 
 , , , , , , , 
p,p,p,p, ,p,p,p
r,n,b,q,k,b,n,r

Browser compatibility

See also

• Polyfill for JavaScript 1.8.5 Array Generics and ECMAScript 5 Array Extras
• "Indexing object properties" in JavaScript Guide: "Working with objects"
• New in JavaScript 1.7: Array comprehensions
• New in JavaScript 1.6: Array extras
• Draft: Typed Arrays
• Predefined Core Objects#Array Object in the JavaScript Guide