https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/forEach
Summary
Executes a provided function once per array element.
Method of Array | |
Implemented in: | JavaScript 1.6 (Gecko 1.8b2 and later) |
ECMAScript Edition: | ECMA-262 Edition 5 |
Syntax
array .forEach(callback [, thisObject ]);
Parameters
- Function to execute for each element.
-
Object to use as
this
when executingcallback
.
callback
thisObject
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 bycallback
. 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.
Compatibility
forEach
is a recent addition 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 implementations which do not natively support it. This algorithm is exactly the one specified in ECMA-262, 5th edition, assuming Object
and TypeError
have their original values and that fun.call
evaluates to the original value of Function.prototype.call
.
if (!Array.prototype.forEach)
{
Array.prototype.forEach = function(fun /*, thisp */)
{
"use strict";
if (this === void 0 || this === null)
throw new TypeError();
var t = Object(this);
var len = t.length >>> 0;
if (typeof fun !== "function")
throw new TypeError();
var thisp = arguments[1];
for (var i = 0; i < len; i++)
{
if (i in t)
fun.call(thisp, t[i], i, t);
}
};
}
Examples
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
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