Core JavaScript 1.5 Reference:Global Objects:Array:forEach
From MDC
Contents |
[edit] Summary
Executes a provided function once per array element.
| Method of Array | |
| Implemented in: | JavaScript 1.6 (Gecko 1.8b2 and later) |
| ECMAScript Edition: | none |
[edit] Syntax
array.forEach(callback[, thisObject]);
[edit] Parameters
-
callback - Function to execute for each element.
-
thisObject - Object to use as
thiswhen executingcallback.
[edit] Description
forEach executes the provided function (callback) once for each element present in the array. callback is invoked only for indexes of the array which have assigned values; it is not invoked for indexes which have been deleted or which have never been assigned values.
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 are not visited.
[edit] Compatibility
forEach is a JavaScript extension to the ECMA-262 standard; as such it may not be present in other implementations of the standard. You can work around this by inserting the following code at the beginning of your scripts, allowing use of forEach in ECMA-262 implementations which do not natively support it. This algorithm is exactly the one used in Firefox and SpiderMonkey.
if (!Array.prototype.forEach)
{
Array.prototype.forEach = function(fun /*, thisp*/)
{
var len = this.length;
if (typeof fun != "function")
throw new TypeError();
var thisp = arguments[1];
for (var i = 0; i < len; i++)
{
if (i in this)
fun.call(thisp, this[i], i, this);
}
};
}
[edit] Examples
[edit] Example: Printing the contents of an array
The following code prints a line for each element in an array:
function printElt(element, index, array) {
print("[" + index + "] is " + element); // assumes print is already defined
}
[2, 5, 9].forEach(printElt);
// Prints:
// [0] is 2
// [1] is 5
// [2] is 9
[edit] 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:
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()); // assumes print is already defined
// Prints:
// 2
// 5
// 9