An array is an ordered list of elements.
Returns a new array comprised of this array joined
with other array(s) and/or value(s).
|
Show Details |
4.0+ |
1.0+ |
4.0+ |
7.0+ |
1.0+ |
Parameters
Number |
valueN |
(one-or-more)Arrays and/or values to concatenate to this array.
|
Returns
-
Concatenating two arraysThe following code concatenates two arrays:
alpha = new Array("a", "b", "c");
numeric = new Array(1, 2, 3);
alphaNumeric = alpha.concat(numeric); // creates array ["a", "b", "c", 1, 2, 3] Concatenating three arraysThe
following code concatenates three arrays: num1 = [1, 2, 3];
num2 = [4, 5, 6];
num3 = [7, 8, 9];
nums = num1.concat(num2,num3) // creates array [1, 2, 3, 4, 5, 6, 7, 8, 9] Concatenating values to an arrayThe
following code concatenates three values to an
array: alpha = ['a', 'b', 'c'];
alphaNumeric = alpha.concat(1, 2, 3); // creates array ["a", "b", "c", 1, 2, 3]
- Remarks
-
concat does not alter the original
arrays, but returns a "one level deep" copy that contains
copies of the same elements combined from the original
arrays. Elements of the original arrays are copied into
the new array as follows:
- Object references (and not the actual object):
concat copies object references into the
new array. Both the original and new array refer to the
same object. That is, if a referenced object is
modified, the changes are visible to both the new and
original arrays.
- Strings and numbers (not String
and Number
objects):
concat copies the values of
strings and numbers into the new array.
Any operation on the new array will have no effect on
the original arrays, and vice versa.
- See Also
-
Array.join|Array.push|Array.splice
- Availability
-
JavaScript 1.2|JScript 3.0|ECMAScript v3
|
every( Function callback, Function thisObject) : Boolean
Returns true if every element in an array meets the specified criteria.
|
Show Details |
no |
1.0+ |
3.0+ |
no |
no |
Parameters
Function |
callback |
Function that tests each element of an array. |
Function |
thisObject |
(zero-or-more)Object to use as this when executing callback.
|
Returns
Example: Testing size of all array elements
The following example tests whether all elements in the array are bigger than 10.
function isBigEnough(element, index, array) {
return (element >= 10);
}
passed = [12, 5, 8, 130, 44].every(isBigEnough);
// passed is false
passed = [12, 54, 18, 130, 44].every(isBigEnough);
// passed is true
- Remarks
every executes the provided function (callback ) once for each element present in the array until
it finds one where callback returns a false value. If such an element is found, the test aborts and false
is returned, otherwise (callback returned a true value for each of the elements) every will return
true . Arrays are treated as "dense", meaning that callback will be invoked for each index less
than the array's length , even if a given index has never been explicitly assigned.
callback is invoked with three arguments: the value of the element, the index of the element, and the Array
object being traversed.
If a thisObject parameter is provided to every , it will be used as the this
for each invocation of the callback . If it is not provided, or is null , the global object associated
with callback is used instead.
every does not mutate the array on which it is called.
The range of elements processed by every is set before the first invocation of callback .
Elements which are appended to the array after the call to every begins will not be visited by callback .
If existing elements of the array are changed, or deleted, their value as passed to callback will be the value
at the time every visits them; elements that are deleted will have the value undefined .
- Availability
-
JavaScript 1.6|Gecko 1.8b2
|
filter( Function callback, Function thisObject) : Array
Creates a new array with all elements that meet the specified criteria.
|
Show Details |
no |
1.0+ |
3.0+ |
no |
no |
Parameters
Function |
callback |
Function that tests each element of an array. |
Function |
thisObject |
(zero-or-more)Object to use as this when executing callback.
|
Returns
Example: Filtering out all small values
The following example uses filter to create a filtered array that has all elements with values less than 10
removed.
function isBigEnough(element, index, array) {
return (element >= 10);
}
filtered = [12, 5, 8, 130, 44].filter(isBigEnough);
- Remarks
filter calls a provided callback function once for each element in an array, and constructs a
new array of all the values for which callback returns a true value. The produced array is dense; values which
do not pass the callback test are simply skipped, and are not assigned an index in the new array.
callback is invoked with three arguments: the value of the element, the index of the element, and the Array
object being traversed.
If a thisObject parameter is provided to filter , it will be used as the this for
each invocation of the callback . If it is not provided, or is null , the global object associated
with callback is used instead.
filter does not mutate the array on which it is called.
The range of elements processed by filter is set before the first invocation of callback . Elements
which are appended to the array after the call to filter begins will not be visited by callback .
If existing elements of the array are changed, or deleted, their value as passed tocallback will be the value
at the time filter visits them; elements that are deleted will have the value undefined .
- Availability
-
JavaScript 1.6|Gecko 1.8b2
|
forEach( Function callBack, Object thisObject) : Object
Executes the specified function once for each element in an array.
|
Show Details |
no |
1.0+ |
3.0+ |
no |
no |
Parameters
Function |
callBack |
Function to call once on each array element. |
Object |
thisObject |
(zero-or-more)Object to use as this when executing callback.
|
Returns
Example: Printing the contents of an array
The following code prints a line for each element in an array (and presumes the presence of a print function
to call!):
function printElt(element, index, array) {
print("[" + index + "] is " + element);
}
[2, 5, 9].forEach(printElt);
// Prints:
// [0] is 2
// [1] is 5
// [2] is 9
Example: Printing the contents of an array with an object method
The following code creates a simple writer object and then uses the writeln method to write one line per element
in the array. (This presumes the presence of a print function to call!):
var writer = {
sb: [],
write: function (s) {
this.sb.push(s);
},
writeln: function (s) {
this.write(s + "\n");
},
toString: function () {
return this.sb.join("");
}
};
[2, 5, 9].forEach(writer.writeln, writer);
print(writer.toString());
// Prints:
// 2
// 5
// 9
- Remarks
forEach executes the provided function (callback ) once for each element present in the array.
Arrays are treated as "dense", meaning that callback will be invoked for each index less than the array's length ,
even if a given index has never been explicitly assigned.
callback is invoked with three arguments: the value of the element, the index of the element, and the Array
object being traversed.
If a thisObject parameter is provided to forEach , it will be used as the this for
each invocation of the callback . If it is not provided, or is null , the global object associated
with callback is used instead.
forEach does not mutate the array on which it is called.
The range of elements processed by forEach is set before the first invocation of callback . Elements
which are appended to the array after the call to forEach begins will not be visited by callback .
If existing elements of the array are changed, or deleted, their value as passed to callback will be the value
at the time forEach visits them; elements that are deleted will have the value undefined .
- Availability
-
JavaScript 1.6|Gecko 1.8b2
|
indexOf([ Object searchElement,] [ Number fromIndex]) : Number
Returns the first index number at which the specified element can be found in the array. Returns -1 if the element is not
present.
|
Show Details |
no |
1.0+ |
3.0+ |
no |
no |
Parameters
Object |
searchElement |
(optional)Element to search for in the array.
|
Number |
fromIndex |
(optional)Index number to begin searching the array. Default is 0, which searches the whole array.
|
Returns
Example: Using indexOf
The following example uses indexOf to locate values in an array.
array = [2, 5, 9];
index = array.indexOf(2);
// index is 0
index = array.indexOf(7);
// index is -1
Example: Finding all the occurrences of an element
The following example uses indexOf to find all the indices of an element in a given array, using push
to add them to another array as they are found.
indices = [];
idx = array.indexOf(element)
while (idx != -1) {
indices.push(idx);
idx = array.indexOf(element, idx + 1);
}
- Remarks
indexOf compares searchElement to elements of the Array using strict equality (the same method
used by the triple-equals (===) operator).
For the fromIndex parameter, if the specified fromIndex is greater than or equal to the length
of the array, lastIndexOf does not search the array and returns -1. If the specified fromIndex is
negative, the search start position is the offset from the back end of the array; however, the array is still searched from
front to back.
- See Also
-
lastIndexOf
- Availability
-
JavaScript 1.6|Gecko 1.8b2
|
join([ String separator]) : String
Joins all elements of an array into a string.
|
Show Details |
4.0+ |
1.0+ |
3.0+ |
7.0+ |
1.0+ |
Parameters
String |
separator |
(optional)Specifies a string to separate each element of the array. The separator is converted to a string if necessary. If omitted,
the array elements are sparated with a comma.
|
Returns
-
Joining an array three different waysThe following example creates an array,
a , with three elements, then joins the array
three times: using the default separator, then a comma
and a space, and then a plus. a = new Array("Wind","Rain","Fire")
myVar1=a.join() // assigns "Wind,Rain,Fire" to myVar1
myVar2=a.join(", ") // assigns "Wind, Rain, Fire" to myVar2
myVar3=a.join(" + ") // assigns "Wind + Rain + Fire" to myVar3
- Remarks
-
The string conversions of all array elements are
joined into one string.
- See Also
-
String.split|reverse
- Availability
-
JavaScript 1.1|JScript 2.0|ECMAScript v1
|
lastIndexOf([ Object searchElement,] [ Number fromIndex]) : Number
Searches an array backwards starting from fromIndex and returns the last index number at which the specified element can be
found in the array. Returns -1 if the element is not present.
|
Show Details |
no |
1.0+ |
3.0+ |
no |
no |
Parameters
Object |
searchElement |
(optional)Element to search for in the array.
|
Number |
fromIndex |
(optional)Index number to begin searching the array backwards from. Default is the last element in the array, which searches the whole
array.
|
Returns
-
Example: Using lastIndexOf
The following example uses lastIndexOf to locate values in an array.
array = [2, 5, 9, 2];
index = array.lastIndexOf(2);
// index is 3
index = array.lastIndexOf(7);
// index is -1
index = array.lastIndexOf(2, 3);
// index is 3
index = array.lastIndexOf(2, 2);
// index is 0
index = array.lastIndexOf(2, -2);
// index is 0
index = array.lastIndexOf(2, -1);
// index is 3
Example: Finding all the occurrences of an element
The following example uses lastIndexOf to find all the indices of an element in a given array, using push
to add them to another array as they are found.
indices = [];
idx = array.lastIndexOf(element)
while (idx != -1) {
indices.push(idx);
idx = (idx > 0 ? array.lastIndexOf(element, idx - 1) : -1);
}
Note that we have to handle the case idx == 0 separately here because the element will always be found regardsless
the fromIndex parameter if it is the first element of the array. This is different from the indexOf
method.
- Remarks
indexOf compares searchElement to elements of the Array using strict equality (the same method
used by the triple-equals (===) operator).
For the fromIndex parameter, if the specified fromIndex is greater than or equal to the length
of the array, lastIndexOf does not search the array and returns -1. If the specified fromIndex is
negative, the search start position is the offset from the start of the array; however, the array is still searched from
back to front.
- See Also
-
indexOf
- Availability
-
JavaScript 1.6|Gecko 1.8b2
|
map( Function callBack, Object thisObject) : Array
Creates a new array with the results of calling a provided function on every element in this array.
|
Show Details |
no |
1.0+ |
3.0+ |
no |
no |
Parameters
Function |
callBack |
Function that creates an element of the new Array from an element of the current one. |
Object |
thisObject |
(zero-or-more)Object to use as this when executing callback.
|
Returns
Example: Upper-casing the strings in an array
The following code creates a new array which contains upper-case versions of all the strings in the original.
strings = ["hello", "Array", "WORLD"];
function makeUpperCase(v)
{
return v.toUpperCase();
}
uppers = strings.map(makeUpperCase);
// uppers is now ["HELLO", "ARRAY", "WORLD"]
// strings is unchanged
Example: Mapping an array of numbers to an array of square roots
The following code takes an array of numbers and creates a new array containing the square roots of the numbers in the
first array.
numbers = [1, 4, 9];
roots = numbers.map(Math.sqrt);
// roots is now [1, 2, 3]
// numbers is still [1, 4, 9]
- Remarks
map calls a provided callback function once for each element in an array, in order, and constructs
a new array from the results. Arrays are treated as "dense", meaning that callback will be invoked for each
index less than the array's length , even if a given index has never been explicitly assigned.
callback is invoked with three arguments: the value of the element, the index of the element, and the
Array object being traversed.
If a thisObject parameter is provided to map , it will be used as the this for
each invocation of the callback . If it is not provided, or is null , the global object associated
with callback is used instead.
map does not mutate the array on which it is called.
The range of elements processed by map is set before the first invocation of callback . Elements
which are appended to the array after the call to map begins will not be visited by callback . If
existing elements of the array are changed, or deleted, their value as passed to callback will be the value at
the time map visits them; elements that are deleted will have the value undefined .
- Availability
-
JavaScript 1.6|Gecko 1.8b2
|
Removes the last element from an array and returns
that element. This method changes the length of the
array.
|
Show Details |
5.5+ |
1.0+ |
4.0+ |
7.0+ |
1.0+ |
Returns
-
Removing the last element of an arrayThe following code creates the myFish array containing
four elements, then removes its last element. myFish = ["angel", "clown", "mandarin", "surgeon"];
popped = myFish.pop();
- See Also
-
push|shift|unshift
- Availability
-
JavaScript 1.2|JScript 5.5|ECMAScript v3
|
push( Object element1, ..., elementN) : Number
Adds one or more elements to the end of an array and
returns the new length of the array. This method changes
the length of the array.
|
Show Details |
5.5+ |
1.0+ |
4.0+ |
7.0+ |
1.0+ |
Parameters
Object |
element1, ..., elementN |
(one-or-more)The elements to add to the end of the array.
|
Returns
-
Adding elements to an arrayThe following code creates the myFish array containing
two elements, then adds two elements to it. After the
code executes, pushed contains 4. (In JavaScript 1.2,
pushed contains "lion" after the code executes.) myFish = ["angel", "clown"];
pushed = myFish.push("drum", "lion");
- Remarks
-
The behavior of the push method is
analogous to the push function in Perl 4 (not Perl 5).
- See Also
-
pop|shift|unshift
- Availability
-
JavaScript 1.2|JScript 5.5|ECMAScript v3
|
Transposes the elements of an array: the first array
element becomes the last and the last becomes the
first.
|
Show Details |
4.0+ |
1.0+ |
3.0+ |
7.0+ |
1.0+ |
Returns
-
Reversing the elements in an arrayThe following example creates an array myArray,
containing three elements, then reverses the array. myArray = new Array("one", "two", "three")
myArray.reverse() This code changes myArray so that: myArray[0] is "three"myArray[1]
is "two"myArray[2] is "one"
- Remarks
-
The reverse method transposes the
elements of the calling array object.
- See Also
-
join|sort
- Availability
-
JavaScript 1.1|JScript 2.0|ECMAScript v1
|
Removes the first element from an array and returns
that element. This method changes the length of the
array.
|
Show Details |
5.5+ |
1.0+ |
4.0+ |
7.0+ |
1.0+ |
Returns
-
Removing an element from an arrayThe following code displays the myFish
array before and after removing its first element. It
also displays the removed element: myFish = ["angel", "clown", "mandarin", "surgeon"];
document.writeln("myFish before: " + myFish);
shifted = myFish.shift();
document.writeln("myFish after: " + myFish);
document.writeln("Removed this element: " + shifted); This example displays the following: myFish before:
["angel", "clown", "mandarin", "surgeon"]
myFish after: ["clown", "mandarin", "surgeon"]
Removed this element: angel
- See Also
-
pop|push|unshift
- Availability
-
JavaScript 1.2|JScript 5.5|ECMAScript v3
|
slice( Object begin, Object end) : Array
Extracts a section of an array and returns a new
array.
|
Show Details |
4.0+ |
1.0+ |
4.0+ |
7.0+ |
1.0+ |
Parameters
Object |
begin |
Zero-based index at which to begin extraction. |
Object |
end |
Zero-based index at which to end extraction. slice extracts up to but not including end. |
Returns
-
Using slice In the following example, slice creates a
new array, newCar , from myCar .
Both include a reference to the object
myHonda . When the color of
myHonda is changed to purple, both arrays
reflect the change.
//Using slice, create newCar from myCar.
myHonda = {color:"red",wheels:4,engine:{cylinders:4,size:2.2}}
myCar = [myHonda, 2, "cherry condition", "purchased 1997"]
newCar = myCar.slice(0,2)
//Write the values of myCar, newCar, and the color of myHonda
// referenced from both arrays.
document.write("myCar = " + myCar + "<BR>")
document.write("newCar = " + newCar + "<BR>")
document.write("myCar[0].color = " + myCar[0].color + "<BR>")
document.write("newCar[0].color = " + newCar[0].color + "<BR><BR>")
//Change the color of myHonda.
myHonda.color = "purple"
document.write("The new color of my Honda is " + myHonda.color + "<BR><BR>")
//Write the color of myHonda referenced from both arrays.
document.write("myCar[0].color = " + myCar[0].color + "<BR>")
document.write("newCar[0].color = " + newCar[0].color + "<BR>")
This script writes: myCar = [{color:"red", wheels:4, engine:{cylinders:4, size:2.2}}, 2,
"cherry condition", "purchased 1997"]
newCar = [{color:"red", wheels:4, engine:{cylinders:4, size:2.2}}, 2]
myCar[0].color = red
newCar[0].color = red
The new color of my Honda is purple
myCar[0].color = purple
newCar[0].color = purple
- Remarks
-
slice does not alter the original array,
but returns a new "one level deep" copy that contains
copies of the elements sliced from the original array.
Elements of the original array are copied into the new
array as follows:
- For object references (and not the actual object),
slice copies object references into the
new array. Both the original and new array refer to the
same object. If a referenced object changes, the
changes are visible to both the new and original
arrays.
- For strings and numbers (not String
and Number
objects),
slice copies strings and numbers
into the new array. Changes to the string or number in
one array does not affect the other array.
If a new element is added to either array, the other
array is not affected.
- See Also
-
Array.splice
- Availability
-
JavaScript 1.2|JScript 3.0|ECMAScript v3
|
some([ Object searchElement,] [ Number fromIndex]) : Boolean
Returns true if some element in the array passes the test implemented by the provided function.
|
Show Details |
no |
1.0+ |
4.0+ |
no |
no |
Parameters
Object |
searchElement |
(optional)Element to search for in the array.
|
Number |
fromIndex |
(optional)Index number to begin searching the array backwards from. Default is the last element in the array, which searches the whole
array.
|
Returns
Example: Testing size of all array elements
The following example tests whether some element in the array is bigger than 10.
function isBigEnough(element, index, array) {
return (element >= 10);
}
passed = [2, 5, 8, 1, 4].some(isBigEnough);
// passed is false
passed = [12, 5, 8, 1, 44].some(isBigEnough);
// passed is true
- Remarks
some executes the provided function (callback ) once for each element present in the array until
it finds one where callback returns a true value. If such an element is found, the test aborts and true
is returned, otherwise (callback returned a false value for each of the elements) some will return
false . Arrays are treated as "dense", meaning that callback will be invoked for each index less
than the array's length , even if a given index has never been explicitly assigned.
callback is invoked with three arguments: the value of the element, the index of the element, and the Array
object being traversed.
If a thisObject parameter is provided to some , it will be used as the this for
each invocation of the callback . If it is not provided, or is null , the global object associated
with callback is used instead.
some does not mutate the array on which it is called.
The range of elements processed by some is set before the first invocation of callback . Elements
that are appended to the array after the call to some begins will not be visited by callback . If
an existing, unvisited element of the array is changed or deleted by callback , its value passed to the visiting
callback will be the value at the time that some visits that element's index; elements that are
deleted before being visited will have the value undefined .
- Availability
-
JavaScript 1.6|Gecko 1.8b2
|
sort([ Function compareFunction]) : Array
Sorts the elements of an array.
|
Show Details |
4.0+ |
1.0+ |
3.0+ |
7.0+ |
1.0+ |
Parameters
Function |
compareFunction |
(optional)Specifies a function that defines the sort order. If omitted, the array is sorted lexicographically (in dictionary order)
according to the string conversion of each element.
|
Returns
-
Creating, displaying, and sorting an
arrayThe following example creates four arrays and displays
the original array, then the sorted arrays. The numeric
arrays are sorted without, then with, a compare
function.
stringArray = new Array("Blue","Humpback","Beluga")
numericStringArray = new Array("80","9","700")
numberArray = new Array(40,1,5,200)
mixedNumericArray = new Array("80","9","700",40,1,5,200)
function compareNumbers(a, b) {
return a - b
}
document.write("stringArray: " + stringArray.join() +"<BR>")
document.write("Sorted: " + stringArray.sort() +"<P>")
document.write("numberArray: " + numberArray.join() +"<BR>")
document.write("Sorted without a compare function: " + numberArray.sort() +"<BR>")
document.write("Sorted with compareNumbers: " + numberArray.sort(compareNumbers) +"<P>")
document.write("numericStringArray: " + numericStringArray.join() +"<BR>")
document.write("Sorted without a compare function: " + numericStringArray.sort() +"<BR>")
document.write("Sorted with compareNumbers: " + numericStringArray.sort(compareNumbers) +"<P>")
document.write("mixedNumericArray: " + mixedNumericArray.join() +"<BR>")
document.write("Sorted without a compare function: " + mixedNumericArray.sort() +"<BR>")
document.write("Sorted with compareNumbers: " + mixedNumericArray.sort(compareNumbers) +"<BR>")
This example shows that when you use a compare function, the elements are sorted correctly whether they are numbers
or numeric strings. stringArray: Blue,Humpback,Beluga
Sorted: Beluga,Blue,Humpback
numberArray: 40,1,5,200
Sorted without a compare function: 1,200,40,5
Sorted with compareNumbers: 1,5,40,200
numericStringArray: 80,9,700
Sorted without a compare function: 700,80,9
Sorted with compareNumbers: 9,80,700
mixedNumericArray: 80,9,700,40,1,5,200
Sorted without a compare function: 1,200,40,5,700,80,9
Sorted with compareNumbers: 1,5,9,40,80,200,700
- Remarks
-
If compareFunction is not supplied,
elements are sorted by converting them to strings and
comparing strings in lexicographic ("dictionary" or
"telephone book," not numerical) order. For example, "80"
comes before "9" in lexicographic order, but in a numeric
sort 9 comes before 80. If compareFunction is supplied, the array
elements are sorted according to the return value of the
compare function. If a and b
are two elements being compared, then: - If
compareFunction(a, b) is less than
0, sort b to a lower index than
a .
- If
compareFunction(a, b) returns 0,
leave a and b unchanged with
respect to each other, but sorted with respect to all
different elements.
- If
compareFunction(a, b) is greater
than 0, sort b to a higher index than
a .
So, the compare function has the following form: function compare(a, b) {
if (a is less than b by some ordering criterion)
return -1
if (a is greater than b by the ordering criterion)
return 1
// a must be equal to b
return 0
} To compare numbers instead of strings, the compare
function can simply subtract b from
a : function compareNumbers(a, b) {
return a - b
} JavaScript uses a stable sort: the index partial order
of a and b does not change if
a and b are equal. If
a 's index was less than b 's
before sorting, it will be after sorting, no matter how
a and b move due to
sorting. The behavior of the sort method changed
between JavaScript 1.1 and JavaScript 1.2. In JavaScript 1.1, on some platforms, the
sort method does not work. This method works
on all platforms for JavaScript 1.2. In JavaScript 1.2, this method no longer converts
undefined elements to null; instead it sorts them to the
high end of the array. For example, assume you have this
script:
a = new Array();
a[0] = "Ant";
a[5] = "Zebra";
function writeArray(x) {
for (i = 0; i < x.length; i++) {
document.write(x[i]);
if (i < x.length-1) document.write(", ");
}
}
writeArray(a);
a.sort();
document.write("<BR><BR>");
writeArray(a);
In JavaScript 1.1, JavaScript prints: ant, null, null, null, null, zebra
ant, null, null, null, null, zebra In JavaScript 1.2, JavaScript prints: ant, undefined, undefined, undefined,
undefined, zebra
ant, zebra, undefined, undefined, undefined, undefined
- See Also
-
join|reverse
- Availability
-
JavaScript 1.1|JScript 2.0|ECMAScript v1
|
splice( Object index, [ Number howMany,] Object element1, ..., elementN) : Array
Returns the array with the specified elements inserted or removed.
|
Show Details |
5.5+ |
1.0+ |
4.0+ |
7.0+ |
1.0+ |
Parameters
Object |
index |
Index at which to start changing the array. |
Number |
howMany |
(optional)An integer indicating the number of old array elements to remove. If howMany is 0, no elements are removed. In this case,
you should specify at least one new element.
|
Object |
element1, ..., elementN |
(zero-or-more)The elements to add to the array. If you don't specify any elements, splice simply removes elements from the array.
|
Returns
-
Using splice The following script excerpt illustrates the use of splice:
myFish = ["angel", "clown", "mandarin", "surgeon"];
document.writeln("myFish: " + myFish + "<BR>");
removed = myFish.splice(2, 0, "drum");
document.writeln("After adding 1: " + myFish);
document.writeln("removed is: " + removed + "<BR>");
removed = myFish.splice(3, 1);
document.writeln("After removing 1: " + myFish);
document.writeln("removed is: " + removed + "<BR>");
removed = myFish.splice(2, 1, "trumpet");
document.writeln("After replacing 1: " + myFish);
document.writeln("removed is: " + removed + "<BR>");
removed = myFish.splice(0, 2, "parrot", "anemone", "blue");
document.writeln("After replacing 2: " + myFish);
document.writeln("removed is: " + removed);
This script displays:
myFish: ["angel", "clown", "mandarin", "surgeon"]
After adding 1: ["angel", "clown", "drum", "mandarin", "surgeon"]
removed is: undefined
After removing 1: ["angel", "clown", "drum", "surgeon"]
removed is: mandarin
After replacing 1: ["angel", "clown", "trumpet", "surgeon"]
removed is: drum
After replacing 2: ["parrot", "anemone", "blue", "trumpet", "surgeon"]
removed is: ["angel", "clown"]
- Remarks
-
If you insert a different number of elements than you remove, the array will
have a different length at the end of the call. The splice method returns an array
containing the removed elements. If you remove only one element, splice returns one element.
- See Also
-
Array.slice
- Availability
-
JavaScript 1.2|JScript 5.5|ECMAScript v3
|
Returns a localized string version of the array.
|
Show Details |
5.5+ |
1.0+ |
4.0+ |
7.0+ |
1.0+ |
Returns
- Throws
-
- Throws TypeError if toLocaleString is called on an object that is not an array.
- See Also
-
Array.toString|Object.toLocaleString
- Availability
-
JavaScript 1.5|JScript 5.5|ECMAScript v1
|
Returns a string representing the source code of the array.
|
Show Details |
no |
1.0+ |
3.0+ |
no |
no |
Returns
Example: Examining the source code of an array
To examine the source code of an array:
alpha = new Array("a", "b", "c")
alpha.toSource() //returns ["a", "b", "c"]
- Remarks
-
The toSource method returns the following values:
- For the built-in
Array object, toSource returns the following string indicating that
the source code is not available:
function Array() {
[native code]
}
- For instances of
Array , toSource returns a string representing the source code.
This method is usually called internally by JavaScript and not explicitly in code. You can call toSource
while debugging to examine the contents of an array.
- See Also
-
toString
- Availability
-
JavaScript 1.3
|
Returns a string representing the specified array and
its elements.
|
Show Details |
4.0+ |
1.0+ |
3.0+ |
7.0+ |
1.0+ |
Returns
- Remarks
-
The Array
object overrides the toString method of
Object.
For Array objects, the toString method joins
the array and returns one string containing each array
element separated by commas. For example, the following
code creates an array and uses toString to
convert the array to a string. var monthNames = new Array("Jan","Feb","Mar","Apr")
myVar=monthNames.toString() // assigns "Jan,Feb,Mar,Apr" to myVar JavaScript calls the toString method
automatically when an array is to be represented as a
text value or when an array is referred to in a string
concatenation.
- Throws
-
- Throws TypeError if toString is called on an object that is not an array.
- See Also
-
Array.toLocaleString|Object.toString
- Availability
-
JavaScript 1.1|JScript 2.0|ECMAScript v1
|
unshift( Object element1, ..., elementN) : Number
Adds one or more elements to the beginning of an array
and returns the new length of the array.
|
Show Details |
5.5+ |
1.0+ |
4.0+ |
7.0+ |
1.0+ |
Parameters
Object |
element1, ..., elementN |
(one-or-more)The elements to add to the front of the array.
|
Returns
-
Adding elements to an arrayThe following code displays the myFish
array before and after adding elements to it. myFish = ["angel", "clown"];
document.writeln("myFish before: " + myFish);
unshifted = myFish.unshift("drum", "lion");
document.writeln("myFish after: " + myFish);
document.writeln("New length: " + unshifted); This example displays the following: myFish before: ["angel",
"clown"]
myFish after: ["drum", "lion", "angel", "clown"]
New length: 4
- See Also
-
pop|push|shift
- Availability
-
JavaScript 1.2|JScript 5.5|ECMAScript v3
|
Returns the primitive value of an array or the primitive value of its elements.
|
Show Details |
4.0+ |
1.0+ |
3.0+ |
7.0+ |
1.0+ |
Returns
- Remarks
-
The table below displays how the data type of an array corresponds to the data type returned
by the valueOf method.
Data type of array element |
Return type |
Boolean |
Boolean |
Number or Date |
Number |
All other object types |
String |
- See Also
-
Object.valueOf
- Availability
-
JavaScript 1.1|JScript 2.0|ECMAScript v1
|
The following creates a two-dimensional array
and
assigns the results to myVar
.
An array is an ordered set of values associated with a
single variable name.
The following example creates an Array object with an
array literal; the coffees array contains three elements
and has a length of three:
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:
You
index an array by its ordinal number. For example,
assume you define the following array:
The following code creates an array of length 25, then
assigns values to the first three elements:
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.
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: