Array

  • Revision slug: JavaScript/Reference/Global_Objects/Array
  • Revision title: Array
  • Revision id: 27748
  • Created:
  • Creator: DataForge
  • Is current revision? No
  • Comment 8 words added, 2 words removed

Revision Content

 Summary

Lets you work with arrays.

Syntax

var arr1 = new Array(arrayLength);
var arr2 = new Array(element0, element1, ..., elementN);

Array literals use the form:

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

Parameters

arrayLength 
The initial length of the array. You can access this value using the length property. If the value specified is not a number, an array of length 1 is created, with the first element having the specified value. The maximum length allowed for an array is 4,294,967,295.
elementN 
A value for the element in that position in the array. When this form is used, the array is initialized with the specified values as its elements, and the array's length property is set to the number of arguments.

Description

An array is an ordered set of values associated with a single variable name. Note that you shouldn't use it as an associative array, use Object instead.

The following example creates an Array object with an array literal; the coffees array contains three elements and has a length of three:

var coffees = ["Kenyan", "Columbian", "Kona"];

You can construct a dense array of two or more elements starting with index 0 if you define initial values for all elements. A dense array is one in which each element has a value. The following code creates a dense array with three elements:

var myArray = new Array("Hello", myVar, 3.14159);

Indexing an array

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

var myArray = new Array("Wind", "Rain", "Fire");

You can then refer to the elements as thus:

  • myArray{{ mediawiki.external("0") }} is the first element
  • myArray{{ mediawiki.external("1") }} is the second element
  • myArray{{ mediawiki.external("2") }} is the third element

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 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 number, an array of length 1 is created, with the first element having the specified value.

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.

{{ JSInherits("Function", "Properties", "caller", "constructor", "length", "name") }}

Methods

 For properties inherited by Array instances, see {{ :en/Core_JavaScript_1.5_Reference/Global_Objects/Array/Prototype() }}

Although the global Array object contains no methods of its own, it does inherit some methods through the prototype chain.

{{ JSInherits("Function", "Methods", "apply", "call", "toSource", "toString", "valueOf") }} {{ JSInherits("Object", "Methods", "__defineGetter__", "__defineSetter__", "hasOwnProperty", "isPrototypeOf", "__lookupGetter__", "__lookupSetter__", "__noSuchMethod__", "propertyIsEnumerable", "unwatch", "watch") }}

Array instances

{{ :en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype() }}

Examples

Example: Creating an Array

The following example creates an array, msgArray, with a length of 0, then assigns values to msgArray{{ mediawiki.external("0") }} and msgArray{{ mediawiki.external("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 1,4 to 3,4. The position 1,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[3][4] = board[1][4];
board[1][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

<h3> Summary</h3>
<p>Lets you work with arrays.</p>
<h3 name="Syntax">Syntax</h3>
<pre class="eval">var arr1 = new Array(<em>arrayLength</em>);
var arr2 = new Array(<em>element0</em>, <em>element1</em>, ..., <em>elementN</em>);
</pre>
<p>Array literals use the form:</p>
<pre class="eval">var lit = [<em>element0</em>, <em>element1</em>, ..., <em>elementN</em>];
</pre>
<h3 name="Parameters">Parameters</h3>
<dl><dt> <code>arrayLength</code> </dt><dd> The initial length of the array. You can access this value using the length property. If the value specified is not a number, an array of length 1 is created, with the first element having the specified value. The maximum length allowed for an array is 4,294,967,295. </dd></dl> <dl><dt> <code>element<em>N</em></code> </dt><dd> A value for the element in that position in the array. When this form is used, the array is initialized with the specified values as its elements, and the array's length property is set to the number of arguments. </dd></dl>
<h3 name="Description">Description</h3>
<p>An array is an ordered set of values associated with a single variable name. 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/Core_JavaScript_1.5_Reference/Global_Objects/Object" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Object">Object</a> instead.</p>
<p>The following example creates an Array object with an array literal; the coffees array contains three elements and has a length of three:</p>
<pre class="eval">var coffees = ["Kenyan", "Columbian", "Kona"];
</pre>
<p>You can construct a dense array of two or more elements starting with index 0 if you define initial values for all elements. A dense array is one in which each element has a value. The following code creates a dense array with three elements:</p>
<pre class="eval">var myArray = new Array("Hello", myVar, 3.14159);
</pre>
<h4 name="Indexing_an_array">Indexing an array</h4>
<p>You index an array by its ordinal number. For example, assume you define the following array:</p>
<pre class="eval">var myArray = new Array("Wind", "Rain", "Fire");
</pre>
<p>You can then refer to the elements as thus:</p>
<ul> <li><code>myArray{{ mediawiki.external("0") }}</code> is the first element</li> <li><code>myArray{{ mediawiki.external("1") }}</code> is the second element</li> <li><code>myArray{{ mediawiki.external("2") }}</code> is the third element</li>
</ul>
<h4 name="Specifying_a_single_parameter">Specifying a single parameter</h4>
<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="eval">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 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 number, an array of length 1 is created, with the first element having the specified value.</li>
</ul>
<p>The following code creates an array of length 25, then assigns values to the first three elements:</p>
<pre class="eval">var musicTypes = new Array(25);
musicTypes[0] = "R&amp;B";
musicTypes[1] = "Blues";
musicTypes[2] = "Jazz";
</pre>
<h4 name="Increasing_the_array_length_indirectly">Increasing the array length indirectly</h4>
<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="eval">var colors = new Array();
colors[99] = "midnightblue";
</pre>
<h4 name="Creating_an_array_using_the_result_of_a_match">Creating an array using the result of a match</h4>
<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="eval">// 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>
<h3 name="Properties">Properties</h3>
<p> {{ Js_see_prototype("Array", "Properties") }}</p>
<dl><dd><dl><dt> <a href="/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype">prototype</a></dt><dd> Allows the addition of properties to all objects. </dd></dl> </dd></dl>
<p>{{ JSInherits("Function", "Properties", "caller", "constructor", "length", "name") }}</p>
<h3 name="Methods">Methods</h3>
<p> <span style="font-size: small; "><em>For properties inherited by Array instances, see {{ :en/Core_JavaScript_1.5_Reference/Global_Objects/Array/Prototype() }}</em></span></p>
<p>Although the global <code>Array</code> object contains no methods of its own, it does inherit some methods through the prototype chain.</p>
<p>{{ JSInherits("Function", "Methods", "apply", "call", "toSource", "toString", "valueOf") }} {{ JSInherits("Object", "Methods", "__defineGetter__", "__defineSetter__", "hasOwnProperty", "isPrototypeOf", "__lookupGetter__", "__lookupSetter__", "__noSuchMethod__", "propertyIsEnumerable", "unwatch", "watch") }}</p><h3 name="Array_instances"><code>Array</code> instances</h3>
<p>{{ :en/Core_JavaScript_1.5_Reference/Global_Objects/Array/prototype() }}</p>
<h3 name="Examples">Examples</h3>
<h4 name="Example:_Creating_an_Array">Example: Creating an Array</h4>
<p>The following example creates an array, <code>msgArray</code>, with a length of 0, then assigns values to <code>msgArray{{ mediawiki.external("0") }}</code> and <code>msgArray{{ mediawiki.external("99") }}</code>, changing the length of the array to 100.</p>
<pre class="eval">var msgArray = new Array();
msgArray[0] = "Hello";
msgArray[99] = "world";

if (msgArray.length == 100)
   print("The length is 100.");
</pre>
<h4 name="Example:_Creating_a_Two-dimensional_Array">Example: Creating a Two-dimensional Array</h4>
<p>The following creates chess board as a two dimensional array of strings. The first move is made by copying the 'P' in 1,4 to 3,4. The position 1,4 is left blank.</p>
<pre class="eval">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[3][4] = board[1][4];
board[1][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/Core_JavaScript_1.5_Guide/Predefined_Core_Objects/Array_Object" title="en/Core_JavaScript_1.5_Guide/Predefined_Core_Objects/Array_Object">Core JavaScript 1.5 Guide:Predefined Core Objects:Array Object</a></li> <li><a href="/en/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/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>
</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