The ECMAScript standard specifies arrays as maps (dictionaries) from indices to values. In other words, arrays may not be contiguous and can have holes in them. For example:

> var arr = [];
> arr[0] = 'a';
'a'
> arr[2] = 'b';
'b'
> arr
[ 'a', , 'b' ]

The preceding array has a hole: there is no element at index 1. Holes in Arrays explains holes in more detail.

Note that most JavaScript engines optimize arrays without holes internally and store them contiguously.

Arrays are still objects and can have object properties. Those are not considered part of the actual array; that is, they are not considered array elements:

> var arr = [ 'a', 'b' ];
> arr.foo = 123;
> arr
[ 'a', 'b' ]
> arr.foo
123

There are two ways to use the constructor Array: you can create an empty array with a given length or an array whose elements are the given values. For this constructor, new is optional: invoking it as a normal function (without new) does the same as invoking it as a constructor.

> var arr = new Array(2);
> arr.length
2
> arr  // two holes plus trailing comma (ignored!)
[ , ,]

// The same as ['a', 'b', 'c']:
var arr1 = new Array('a', 'b', 'c');

> new Array(2)  // alas, not [ 2 ]
[ , ,]

> new Array(5.7)  // alas, not [ 5.7 ]
RangeError: Invalid array length

> new Array('abc')  // ok
[ 'abc' ]

If you need multiple dimensions for elements, you must nest arrays. When you create such nested arrays, the innermost arrays can grow as needed. But if you want direct access to elements, you need to at least create the outer arrays. In the following example, I create a three-by-three matrix for Tic-tac-toe. The matrix is completely filled with data (as opposed to letting rows grow as needed):

// Create the Tic-tac-toe board
var rows = [];
for (var rowCount=0; rowCount < 3; rowCount++) {
    rows[rowCount] = [];
    for (var colCount=0; colCount < 3; colCount++) {
        rows[rowCount][colCount] = '.';
    }
}

// Set an X in the upper right corner
rows[0][2] = 'X';  // [row][column]

// Print the board
rows.forEach(function (row) {
    console.log(row.join(' '));
});

Here is the output:

. . X
. . .
. . .

I wanted the example to demonstrate the general case. Obviously, if a matrix is so small and has fixed dimensions, you can set it up via an array literal:

var rows = [ ['.','.','.'], ['.','.','.'], ['.','.','.'] ];

The in operator detects whether an object has a property with a given key. But it can also be used to determine whether a given element index exists in an array. For example:

> var arr = [ 'a', , 'b' ];
> 0 in arr
true
> 1 in arr
false
> 10 in arr
false

In addition to deleting properties, the delete operator also deletes array elements. Deleting elements creates holes (the length property is not updated):

> var arr = [ 'a', 'b' ];
> arr.length
2
> delete arr[1]  // does not update length
true
> arr
[ 'a',  ]
> arr.length
2

You can also delete trailing array elements by decreasing an array’s length (see length for details). To remove elements without creating holes (i.e., the indices of subsequent elements are decremented), you use Array.prototype.splice() (see Adding and Removing Elements (Destructive)). In this example, we remove two elements at index 1:

> var arr = ['a', 'b', 'c', 'd'];
> arr.splice(1, 2) // returns what has been removed
[ 'b', 'c' ]
> arr
[ 'a', 'd' ]

Array indices are not what they seem. Until now, I have pretended that array indices are numbers. And that is how JavaScript engines implement arrays, internally. However, the ECMAScript specification sees indices differently. Paraphrasing Section 15.4:

In other words, in the world of the spec all values in brackets are converted to strings and interpreted as property keys, even numbers. The following interaction demonstrates this:

> var arr = ['a', 'b'];
> arr['0']
'a'
> arr[0]
'a'

To be an array index, a property key P (a string!) must be equal to the result of the following computation:

That means that an array index must be a stringified integer i in the 32-bit range 0 ≤ i < 2³²−1. The upper limit has been explicitly excluded in the spec (as quoted previously). It is reserved for the maximum length. To see how this definition works, let’s use the function ToUint32() from 32-bit Integers via Bitwise Operators.

First, a string that doesn’t contain a number is always converted to 0, which, after stringification, is not equal to the string:

> ToUint32('xyz')
0
> ToUint32('?@#!')
0

Second, a stringified integer that is out of range is also converted to a completely different integer, which is not equal to the string, after stringification:

> ToUint32('-1')
4294967295
> Math.pow(2, 32)
4294967296
> ToUint32('4294967296')
0

Third, stringified noninteger numbers are converted to integers, which are, again, different:

> ToUint32('1.371')
1

Note that the specification also enforces that array indices don’t have exponents:

> ToUint32('1e3')
1000

And that they don’t have leading zeros:

> var arr = ['a', 'b'];
> arr['0']  // array index
'a'
> arr['00'] // normal property
undefined

Manually increasing the length of an array has remarkably little effect on an array; it only creates holes:

> var arr = [ 'a', 'b' ];
> arr.length = 3;
> arr  // one hole at the end
[ 'a', 'b', ,]

The last result has two commas at the end, because a trailing comma is optional and thus always ignored.

What we just did did not add any elements:

> countElements(arr)
2

However, the length property does act as a pointer indicating where to insert new elements. For example:

> arr.push('c')
4
> arr
[ 'a', 'b', , 'c' ]

Thus, setting the initial length of an array via the Array constructor creates an array that is completely empty:

> var arr = new Array(2);
> arr.length
2
> countElements(arr)
0

If you decrease the length of an array, all elements at the new length and above are deleted:

> var arr = [ 'a', 'b', 'c' ];
> 1 in arr
true
> arr[1]
'b'

> arr.length = 1;
> arr
[ 'a' ]
> 1 in arr
false
> arr[1]
undefined

function clearArray(arr) {
    arr.length = 0;
}

> var arr = [ 'a', 'b', 'c' ];
> clearArray(arr)
> arr
[]

arr = [];

> var a1 = [1, 2, 3];
> var a2 = a1;
> a1.length = 0;

> a1
[]
> a2
[]

> var a1 = [1, 2, 3];
> var a2 = a1;
> a1 = [];

> a1
[]
> a2
[ 1, 2, 3 ]

The maximum array length is 2³²−1:

> var arr1 = new Array(Math.pow(2, 32));  // not ok
RangeError: Invalid array length

> var arr2 = new Array(Math.pow(2, 32)-1);  // ok
> arr2.push('x');
RangeError: Invalid array length

You can create holes by assigning to array indices:

> var arr = [];
> arr[0] = 'a';
> arr[2] = 'c';
> 1 in arr  // hole at index 1
false

You can also create holes by omitting values in array literals:

> var arr = ['a',,'c'];
> 1 in arr  // hole at index 1
false

> [ 'a', ].length
1
> [ 'a', ,].length
2

This section examines the differences between a hole and undefined as an element. Given that reading a hole returns undefined, both are very similar.

An array with holes is called sparse. An array without holes is called dense. Dense arrays are contiguous and have an element at each index—starting at zero, and ending at length − 1. Let’s compare the following two arrays, a sparse array and a dense array. The two are very similar:

var sparse = [ , , 'c' ];
var dense  = [ undefined, undefined, 'c' ];

A hole is almost like having the element undefined at the same index. Both arrays have the same length:

> sparse.length
3
> dense.length
3

But the sparse array does not have an element at index 0:

> 0 in sparse
false
> 0 in dense
true

Iteration via for is the same for both arrays:

> for (var i=0; i<sparse.length; i++) console.log(sparse[i]);
undefined
undefined
c
> for (var i=0; i<dense.length; i++) console.log(dense[i]);
undefined
undefined
c

Iteration via forEach skips the holes, but not the undefined elements:

> sparse.forEach(function (x) { console.log(x) });
c
> dense.forEach(function (x) { console.log(x) });
undefined
undefined
c

Some operations involving arrays ignore holes, while others consider them. This sections explains the details.

> ['a',, 'b'].forEach(function (x,i) { console.log(i+'.'+x) })
0.a
2.b

> ['a',, 'b'].every(function (x) { return typeof x === 'string' })
true

> ['a',, 'b'].map(function (x,i) { return i+'.'+x })
[ '0.a', , '2.b' ]

> ['a',, 'b'].filter(function (x) { return true })
[ 'a', 'b' ]

> ['a',, 'b'].join('-')
'a--b'
> [ 'a', undefined, 'b' ].join('-')
'a--b'

> ['a',, 'b'].sort()  // length of result is 3
[ 'a', 'b', ,  ]

> for (var key in ['a',, 'b']) { console.log(key) }
0
2

> function f() { return [].slice.call(arguments) }
> f.apply(null, [ , , ,])
[ undefined, undefined, undefined ]

> Array.apply(null, Array(3))
[ undefined, undefined, undefined ]

> Array.apply(null, [2])
[ , ,]

As we have seen, filter() removes holes:

> ['a',, 'b'].filter(function (x) { return true })
[ 'a', 'b' ]

Use a custom function to convert holes to undefineds in arbitrary arrays:

function convertHolesToUndefineds(arr) {
    var result = [];
    for (var i=0; i < arr.length; i++) {
        result[i] = arr[i];
    }
    return result;
}

Using the function:

> convertHolesToUndefineds(['a',, 'b'])
[ 'a', undefined, 'b' ]

For numbers, you can simply return a-b, but that can cause numeric overflow. To prevent that from happening, you need more verbose code:

function compareCanonically(a, b) {
    if (a < b) {
        return -1;
    } else if (a > b) {
        return 1;
    } else {
        return 0;
    }
}

I don’t like nested conditional operators. But in this case, the code is so much less verbose that I’m tempted to recommend it:

function compareCanonically(a, b) {
    return a < b ? -1 : (a > b ? 1 : 0);
}

Using the function:

> [-1, -20, 7, 50].sort(compareCanonically)
[ -20, -1, 7, 50 ]

For strings, you can use String.prototype.localeCompare (see Comparing Strings):

> ['c', 'a', 'b'].sort(function (a,b) { return a.localeCompare(b) })
[ 'a', 'b', 'c' ]

The parameter compareFunction is also useful for sorting objects:

var arr = [
    { name: 'Tarzan' },
    { name: 'Cheeta' },
    { name: 'Jane' } ];

function compareNames(a,b) {
    return a.name.localeCompare(b.name);
}

With compareNames as the compare function, arr is sorted by name:

> arr.sort(compareNames)
[ { name: 'Cheeta' },
  { name: 'Jane' },
  { name: 'Tarzan' } ]

Each method described in this section looks like this:

arr.examinationMethod(callback, thisValue?)

Such a method takes the following parameters:

And now for the examination methods whose signatures I have just described:

One potential pitfall of forEach() is that it does not support break or something similar to prematurely abort the loop. If you need to do that, you can use some():

function breakAtEmptyString(strArr) {
    strArr.some(function (elem) {
        if (elem.length === 0) {
            return true; // break
        }
        console.log(elem);
        // implicit: return undefined (interpreted as false)
    });
}

some() returns true if a break happened, and false otherwise. This allows you to react differently depending on whether iterating finished successfully (something that is slightly tricky with for loops).

Transformation methods take an input array and produce an output array, while the callback controls how the output is produced. The callback has the same signature as for examination:

function callback(element, index, array)

There are two transformation methods:

For reducing, the callback has a different signature:

function callback(previousValue, currentElement, currentIndex, array)

The parameter previousValue is the value previously returned by the callback. When the callback is first called, there are two possibilities (the descriptions are for Array.prototype.reduce(); differences with reduceRight() are mentioned in parentheses):

There are two reduction methods:

Another way to look at the reduce method is that it implements an n-ary operator OP:

OP1≤i≤n x_i

via a series of applications of a binary operator op2:

(...(x₁ op2 x₂) op2 ...) op2 x_n

That’s what happened in the previous code example: we implemented an n-ary sum operator for arrays via JavaScript’s binary plus operator.

As an example, let’s examine the two iteration directions via the following function:

function printArgs(prev, cur, i) {
    console.log('prev:'+prev+', cur:'+cur+', i:'+i);
    return prev + cur;
}

As expected, reduce() iterates from left to right:

> ['a', 'b', 'c'].reduce(printArgs)
prev:a, cur:b, i:1
prev:ab, cur:c, i:2
'abc'
> ['a', 'b', 'c'].reduce(printArgs, 'x')
prev:x, cur:a, i:0
prev:xa, cur:b, i:1
prev:xab, cur:c, i:2
'xabc'

And reduceRight() iterates from right to left:

> ['a', 'b', 'c'].reduceRight(printArgs)
prev:c, cur:b, i:1
prev:cb, cur:a, i:0
'cba'
> ['a', 'b', 'c'].reduceRight(printArgs, 'x')
prev:x, cur:c, i:2
prev:xc, cur:b, i:1
prev:xcb, cur:a, i:0
'xcba'