Array

  • Revision slug: JavaScript/Reference/Global_Objects/Array
  • Revision title: Array
  • Revision id: 27777
  • Created:
  • Creator: dbruant
  • Is current revision? No
  • Comment 97 words added, 252 words removed

Revision Content

Summary

In JavaScript, the Array property of the global object is a constructor for array instances.

Syntax

var arr1 = new Array(arrayLength);
var arr2 = new Array(element0, element1, ..., elementN);
arrayLength
If one argument is provided, it is interpreted as the initial length of the array. You can access this value using the length property. If the specified value coerced as a number or not an integer between 0 and 232-1 (inclusive), a RangeError is thrown.
element0, element1, ..., elementN
If several arguments are passed, an array is created with the arguments as first elements.

A more convenient way of initializing an array is to use the array literal syntax.

var lit = [element0, element1, ..., elementN];

Description

An array is a JavaScript object. Note that you shouldn't use it as an associative array, use Object instead.

Accessing array elements

You index an array by its ordinal number. For example, assume you define the following array:

var myArray = new Array("Wind", "Rain", "Fire");
myArray[0]; // "Wind"
myArray[1]; // "Rain"
// ...

Specifying a single parameter

When you specify a single numeric parameter with the Array constructor, you specify the initial length of the array. The following code creates an array of five elements:

var billingMethod = new Array(5);

The behavior of the Array constructor depends on whether the single parameter is a number.

  • If the value specified is a literal number, the constructor converts the number to an unsigned, 32-bit integer and generates an array with the length property (size of the array) set to the integer. The array initially contains no elements, even though it might have a non-zero length.
  • If the value specified is not a literal number, an array of length 1 is created, with the first element having the specified value.
  • If the value specified is a number object (e.g., created with "new Number(123)"), then it will, unlike literal numbers, be treated as an array of length 1 with the first element being the number object.

The following code creates an array of length 25, then assigns values to the first three elements:

var musicTypes = new Array(25);
musicTypes[0] = "R&B";
musicTypes[1] = "Blues";
musicTypes[2] = "Jazz";

Increasing the array length indirectly

An array's length increases if you assign a value to an element higher than the current length of the array. The following code creates an array of length 0, then assigns a value to element 99. This changes the length of the array to 100.

var colors = new Array();
colors[99] = "midnightblue";

Creating an array using the result of a match

The result of a match between a regular expression and a string can create an 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:

Property/Element Description Example
input A read-only property that reflects the original string against which the regular expression was matched. cdbBdbsbz
index A read-only property that is the zero-based index of the match in the string. 1
{{ mediawiki.external("0") }} A read-only element that specifies the last matched characters. dbBd
{{ mediawiki.external("1") }}, ...{{ mediawiki.external('n') }} Read-only elements that specify the parenthesized substring matches, if included in the regular expression. The number of possible parenthesized substrings is unlimited. {{ mediawiki.external("1") }}: bB
{{ mediawiki.external("2") }}: d

Properties

{{ Js_see_prototype("Array", "Properties") }}

prototype
Allows the addition of properties to all objects.
{{ jsOverrides("Function", "Properties", ["prototype"]) }}

Methods

{{ Js_see_prototype("Array", "Methods") }}

isArray

{{ js_minversion_inline("1.8.5") }}
Return true if a variable is an array, if not false.

Array instances

Array instances inherit from Array.prototype. As with all constructors, you can change the constructor's prototype object to make changes to all Array instances.

Properties

{{ page('en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype', 'Properties') }}

Methods

Mutator methods

{{ page('en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype', 'Mutator methods') }}

Accessor methods

{{ page('en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype', 'Accessor methods') }}

Iteration methods

{{ page('en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype', 'Iteration methods') }}

Generic methods

{{ page('en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype', 'Generic methods') }}

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 = new Array();
msgArray[0] = "Hello";
msgArray[99] = "world";

if (msgArray.length == 100)
   print("The length is 100.");

Example: Creating a Two-dimensional Array

The following creates 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 position 4,4 is left 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']];
print(board.join('\n') + '\n\n');

// Move King's Pawn forward 2
board[4][4] = board[6][4];
board[6][4] = ' ';
print(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

See Also

{{ languages( { "es": "es/Referencia_de_JavaScript_1.5/Objetos_globales/Array", "fr": "fr/R\u00e9f\u00e9rence_de_JavaScript_1.5_Core/Objets_globaux/Array", "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/Array", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/Array" } ) }}

Revision Source

<h2>Summary</h2>
<p>In JavaScript, the <code>Array</code> property of the global object is a constructor for array instances.</p> <h2>Syntax</h2>
<pre class="brush: js">var arr1 = new Array(<em>arrayLength</em>);
var arr2 = new Array(<em>element0</em>, <em>element1</em>, ..., <em>elementN</em>);
</pre>
<dl> <dt><code>arrayLength</code></dt> <dd>If one argument is provided, it is interpreted as the initial length of the array. You can access this value using the <code>length</code> property. If the specified value coerced as a number or not an integer between 0 and 2<sup>32</sup>-1 (inclusive), a <code>RangeError</code> is thrown.</dd>
</dl>
<dl> <dt><code><em>element0</em>, <em>element1</em>, ..., <em>elementN</em></code></dt> <dd>If several arguments are passed, an array is created with the arguments as first elements.</dd>
</dl>
<p>A more convenient way of initializing an array is to use the array literal syntax.</p>
<pre class="brush: js">var lit = [<em>element0</em>, <em>element1</em>, ..., <em>elementN</em>];
</pre> <h2>Description</h2>
<p>An array is a JavaScript object. Note that you <a class="external" href="http://www.andrewdupont.net/2006/05/18/javascript-associative-arrays-considered-harmful/">shouldn't use it as an associative array</a>, use <a href="/en/JavaScript/Reference/Global_Objects/Object" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Object">Object</a> instead.</p> <h3>Accessing array elements</h3>
<p>You index an array by its ordinal number. For example, assume you define the following array:</p>
<pre class="brush: js">var myArray = new Array("Wind", "Rain", "Fire");
myArray[0]; // "Wind"
myArray[1]; // "Rain"
// ...
</pre>
<h3>Specifying a single parameter</h3>
<p>When you specify a single numeric parameter with the <code>Array</code> constructor, you specify the initial length of the array. The following code creates an array of five elements:</p>
<pre class="brush: js">var billingMethod = new Array(5);
</pre>
<p>The behavior of the <code>Array</code> constructor depends on whether the single parameter is a number.</p>
<ul> <li>If the value specified is a literal number, the constructor converts the number to an unsigned, 32-bit integer and generates an array with the length property (size of the array) set to the integer. The array initially contains no elements, even though it might have a non-zero length.</li>
</ul>
<ul> <li>If the value specified is not a literal number, an array of length 1 is created, with the first element having the specified value.</li> <li>If the value specified is a <a href="/En/Core_JavaScript_1.5_Reference/Global_Objects/Number" title="En/Core_JavaScript_1.5_Reference/Global_Objects/Number">number object</a> (e.g., created with "new Number(123)"), then it will, unlike literal numbers, be treated as an array of length 1 with the first element being the number object.</li>
</ul>
<p>The following code creates an array of length 25, then assigns values to the first three elements:</p>
<pre class="brush: js">var musicTypes = new Array(25);
musicTypes[0] = "R&amp;B";
musicTypes[1] = "Blues";
musicTypes[2] = "Jazz";
</pre>
<h3>Increasing the array length indirectly</h3>
<p>An array's length increases if you assign a value to an element higher than the current length of the array. The following code creates an array of length 0, then assigns a value to element 99. This changes the length of the array to 100.</p>
<pre class="brush: js">var colors = new Array();
colors[99] = "midnightblue";
</pre>
<h3>Creating an array using the result of a match</h3>
<p>The result of a match between a regular expression and a string can create an 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:</p>
<pre class="brush: js">// 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");
</pre>
<p>The properties and elements returned from this match are as follows:</p>
<table class="fullwidth-table"> <tbody> <tr> <td class="header">Property/Element</td> <td class="header">Description</td> <td class="header">Example</td> </tr> <tr> <td><code>input</code></td> <td>A read-only property that reflects the original string against which the regular expression was matched.</td> <td>cdbBdbsbz</td> </tr> <tr> <td><code>index</code></td> <td>A read-only property that is the zero-based index of the match in the string.</td> <td>1</td> </tr> <tr> <td><code>{{ mediawiki.external("0") }}</code></td> <td>A read-only element that specifies the last matched characters.</td> <td>dbBd</td> </tr> <tr> <td><code>{{ mediawiki.external("1") }}, ...{{ mediawiki.external('n') }}</code></td> <td>Read-only elements that specify the parenthesized substring matches, if included in the regular expression. The number of possible parenthesized substrings is unlimited.</td> <td>{{ mediawiki.external("1") }}: bB<br> {{ mediawiki.external("2") }}: d</td> </tr> </tbody>
</table>
<h2>Properties</h2>
<p>{{ Js_see_prototype("Array", "Properties") }}</p>
<dl> <dd> <dl> <dt><a href="/en/JavaScript/Reference/Global_Objects/Array/prototype" title="en/JavaScript/Reference/Global_Objects/Array/prototype">prototype</a></dt> <dd>Allows the addition of properties to all objects.</dd> </dl> </dd>
</dl>
<div>{{ jsOverrides("Function", "Properties", ["prototype"]) }}</div>
<h2>Methods</h2>
<p>{{ Js_see_prototype("Array", "Methods") }}</p>
<dl> <dt><a href="/en/JavaScript/Reference/Global_Objects/Array/isArray" title="en/JavaScript/Reference/Global Objects/Array/isArray">isArray</a></dt> <dd> <p>{{ js_minversion_inline("1.8.5") }}<br> Return true if a variable is an array, if not false.</p> </dd>
</dl>
<h2><code>Array</code> instances</h2>
<p><code>Array</code> instances inherit from<span style="font-family: monospace;"> <a href="/en/JavaScript/Reference/Global_Objects/Array/prototype" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype">Array.prototype</a></span>. As with all constructors, you can change the constructor's prototype object to make changes to all <code>Array</code> instances.</p>
<h4 class="editable"><span>Properties</span></h4>
<p>{{ page('en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype', 'Properties') }}</p>
<h4 class="editable"><span>Methods</span></h4>
<h5 class="editable"><span>Mutator methods</span></h5>
<p>{{ page('en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype', 'Mutator methods') }}</p>
<h5 class="editable"><span>Accessor methods</span></h5>
<p>{{ page('en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype', 'Accessor methods') }}</p>
<h5 class="editable"><span>Iteration methods</span></h5>
<p>{{ page('en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype', 'Iteration methods') }}</p>
<h5>Generic methods</h5>
<p>{{ page('en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype', 'Generic methods') }}</p>
<h2>Examples</h2>
<h3>Example: Creating an Array</h3>
<p>The following example creates an array, <code>msgArray</code>, with a length of 0, then assigns values to <code>msgArray[0]</code> and <code>msgArray[99]</code>, changing the length of the array to 100.</p>
<pre class="brush: js">var msgArray = new Array();
msgArray[0] = "Hello";
msgArray[99] = "world";

if (msgArray.length == 100)
   print("The length is 100.");
</pre>
<h3>Example: Creating a Two-dimensional Array</h3>
<p>The following creates 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 position 4,4 is left blank.</p>
<pre class="brush: js">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']];
print(board.join('\n') + '\n\n');

// Move King's Pawn forward 2
board[4][4] = board[6][4];
board[6][4] = ' ';
print(board.join('\n'));
</pre>
<p>Here is the output:</p>
<pre class="eval">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
</pre>
<h3 name="See_Also">See Also</h3>
<ul> <li><a href="/en/JavaScript/Guide/Working_with_Objects#Indexing_Object_Properties" title="en/Core_JavaScript_1.5_Guide/Working_with_Objects#Indexing_Object_Properties">Indexing Object Properties in Core JavaScript 1.5 Guide:Working with Object</a></li> <li><a href="/en/JavaScript/New_in_JavaScript/1.7#Array_comprehensions" title="en/New_in_JavaScript_1.7#Array_comprehensions">New in JavaScript 1.7: Array comprehensions</a></li> <li><a href="/en/JavaScript/New_in_JavaScript/1.6#Array_extras" title="en/New_in_JavaScript_1.6#Array_extras">New in JavaScript 1.6: Array extras</a></li> <li><a href="/en/JavaScript_typed_arrays" title="en/JavaScript_typed_arrays">Draft: Typed Arrays</a></li>
</ul>
<p>{{ languages( { "es": "es/Referencia_de_JavaScript_1.5/Objetos_globales/Array", "fr": "fr/R\u00e9f\u00e9rence_de_JavaScript_1.5_Core/Objets_globaux/Array", "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/Array", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/Array" } ) }}</p>
Revert to this revision