aboutsummaryrefslogtreecommitdiff
path: root/files/es/web/javascript/reference/global_objects/array/foreach/index.html
blob: d93888eb93712305cd9699ff385e03824d538295 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
---
title: Array.prototype.forEach()
slug: Web/JavaScript/Reference/Global_Objects/Array/forEach
tags:
  - Array
  - ECMAScript5
  - JavaScript
  - JavaScript 1.6
  - Method
  - Prototype
  - Referencia
  - polyfill
translation_of: Web/JavaScript/Reference/Global_Objects/Array/forEach
original_slug: Web/JavaScript/Referencia/Objetos_globales/Array/forEach
---
<div>{{JSRef}}</div>

<p>El método <code><strong>forEach()</strong></code> ejecuta la función indicada una vez por cada elemento del array.</p>

<p>{{EmbedInteractiveExample("pages/js/array-foreach.html")}}</p>

<h2 id="Sintaxis">Sintaxis</h2>

<pre class="syntaxbox notranslate"><var>arr</var>.forEach(function <var>callback(currentValue, index, array) {
    // tu iterador
}</var>[, <var>thisArg</var>]);</pre>

<h3 id="Parameters" name="Parameters">Parámetros</h3>

<dl>
 <dt><code>callback</code></dt>
 <dd>Función a ejecutar por cada elemento, que recibe tres argumentos:</dd>
 <dd>
 <dl>
  <dt><code>currentValue</code></dt>
  <dd>El elemento actual siendo procesado en el array.</dd>
  <dt><code>index</code> {{optional_inline}}</dt>
  <dd>El índice del elemento actual siendo procesado en el array.</dd>
  <dt><code>array</code> {{optional_inline}}</dt>
  <dd>El vector en el que <code>forEach()</code> esta siendo aplicado.</dd>
 </dl>
 </dd>
 <dt><code>thisArg</code> {{optional_inline}}</dt>
 <dd>Valor que se usará como <code>this</code> cuando se ejecute el <code>callback</code>.</dd>
</dl>

<h3 id="Valor_de_retorno">Valor de retorno</h3>

<p>{{jsxref("undefined")}}.</p>

<h2 id="Descripción">Descripción</h2>

<p><code>forEach()</code> ejecuta la función <code>callback</code> una vez por cada elemento presente en el array en orden ascendente. No es invocada para índices que han sido eliminados o que no hayan sido inicializados (Ej. sobre arrays <code>sparse</code>)</p>

<p><code>callback</code> es invocada con tres argumentos:</p>

<ol>
 <li>el valor del elemento</li>
 <li>el índice del elemento</li>
 <li>el array que está siendo recorrido</li>
</ol>

<p>Si un parámetro <code>thisArg</code> es proporcionado a <code>forEach</code>, será usado como el valor <code>this</code> para cada invocación de <code>callback</code> como si se llamara a <code>callback.call(thisArg, element, index, array)</code>. Si <code>thisArg</code> es <code>undefined</code> o <code>null</code>, el valor <code>this</code> dentro de la función depende si la función está o no en <a href="/es/docs/Web/JavaScript/Referencia/Modo_estricto" title="JavaScript/Strict_mode">modo estricto</a> (valor pasado si está en modo estricto, objeto global si está en modo no-estricto).</p>

<p>El rango de elementos procesados por <code>forEach()</code> se establece antes de la primera invocación del <code>callback</code>. Los elementos que sean añadidos al vector después de que inicie la llamada a <code>forEach</code> no serán visitados por <code>callback</code>. Si los valores de los elementos existentes en el vector son modificados, el valor pasado al <code>callback</code> será el valor al momento de que forEach los visite; no se evaluarán los elementos borrados antes de ser visitados por <code>forEach</code>.</p>

<p><code>forEach()</code> ejecuta la función <code>callback</code> una vez por cada elemento del array; a diferencia de {{jsxref("Array.prototype.map()", "map()")}}{{jsxref("Array.prototype.reduce()", "reduce()")}} este siempre devuelve el valor {{jsxref("undefined")}} y no es encadenable. El típico uso es ejecutar los efectos secundarios al final de la cadena.</p>

<p><code>foreach()</code> no muta/modifica el array desde el que es llamado (aunque <code>callback</code>, si se invoca, podría hacerlo).</p>

<div class="note"><strong>Nota :</strong> No hay forma de detener o cortar un bucle <code>forEach</code> que no sea lanzar una excepción. Si necesita dicho comportamiento, el método <code>.forEach()</code> es la herramienta equivocada, use una simple iteración en su lugar. Si está probando los elementos del array para un predicado y necesita devolver un valor boleano, puede usar {{jsxref("Array.prototype.every()", "every()")}}{{jsxref("Array.prototype.some()", "some()")}} en su lugar.</div>

<h2 id="Ejemplos">Ejemplos</h2>

<h3 id="Imprimiendo_el_contenido_de_un_array">Imprimiendo el contenido de un <code>array</code></h3>

<p>El siguiente código imprime una línea por cada elemento en un array:</p>

<pre class="brush:js notranslate">function logArrayElements(element, index, array) {
    console.log("a[" + index + "] = " + element);
}
// Nótese que se evita el 2° índice ya que no hay ningún elemento en esa posición del array
[2, 5, , 9].forEach(logArrayElements);
// salida:
// a[0] = 2
// a[1] = 5
// a[2] = 9
</pre>

<h3 id="Usando_thisArg">Usando <code>thisArg</code></h3>

<p>El siguiente ejemplo actualiza las propiedades del objeto por cada entrada en el array:</p>

<pre class="brush:js notranslate">function Counter() {
  this.sum = 0;
  this.count = 0;
}
Counter.prototype.add = function(array) {
  array.forEach(function(entry) {
    this.sum += entry;
    ++this.count;
  }, this);
  // ^---- Note
};

var obj = new Counter();
obj.add([2, 5, 9]);
obj.count
// 3
obj.sum
// 16</pre>

<p>Nota: Dado que el parámetro <code>thisArg</code> (this) se referencia en el <code>forEach()</code>, será pasado al <code>callback</code> cuando se invoque, para utilizarse como su valor <code>this</code>.</p>

<h3 id="Ejemplo_Función_que_copia_objetos">Ejemplo: Función que copia objetos</h3>

<p>El siguiente código crea una copia de un objeto dado. Hay diferentes formas de crear una copia de un objeto, ésta es sólo una de ellas y sirve para explicar cómo funciona <code>Array.prototype.forEach </code>utilizando funciones <code>Object.*</code> de ECMAScript 5.</p>

<pre class="brush: js notranslate">function copy(o){
  var copy = Object.create( Object.getPrototypeOf(o) );
  var propNames = Object.getOwnPropertyNames(o);

  propNames.forEach(function(name){
    var desc = Object.getOwnPropertyDescriptor(o, name);
    Object.defineProperty(copy, name, desc);
  });

  return copy;
}

var o1 = {a:1, b:2};
var o2 = copy(o1); // o2 ahora se parece a o1
</pre>

<h3 id="Si_el_array_se_modifica_durante_la_iteración_otros_elementos_pueden_ser_omitidos.">Si el array se modifica durante la iteración, otros elementos pueden ser omitidos.</h3>

<p>El siguiente ejemplo muestra por consola "uno", "dos", "cuatro". Cuando se alcanza el registro que contiene el valor "dos", el primer registro del array se desplaza, lo que hace que los registros restantes se muevan una posición. Debido a que el elemento "cuatro" está ahora en una posición anterior en el array, "tres" se omitirá. <code>forEach()</code> no hace una copia del array antes de iterar.</p>

<pre class="brush:js notranslate">var words = ['uno', 'dos', 'tres', 'cuatro'];
words.forEach(function(word) {
  console.log(word);
  if (word === 'dos') {
    words.shift();
  }
});
// uno
// dos
// cuatro
</pre>

<h2 id="Polyfill">Polyfill</h2>

<p><code>forEach</code> se agregó de manera reciente al estándar ECMA-262; así que puede no estar presente en otras implementaciones del estándar. Se puede asegurar el uso del <span style="font-family: consolas,monaco,andale mono,monospace;">forEach</span> con tan solo agregar el siguiente código al inicio de los scripts, permitiendo así el uso de <span style="font-family: consolas,monaco,andale mono,monospace;">forEach</span> en implementaciones que no lo soportan de manera nativa. El algoritmo es el mismo que se especifica en la quinta versión de ECMA-262, asumiendo que {{jsxref("Object")}} y {{jsxref("TypeError")}} tienen sus valores originales y que <span style="font-family: consolas,monaco,andale mono,monospace;">callback.call </span>evalúa el valor original de {{jsxref("Function.prototype.call()")}}.</p>

<pre class="brush: js notranslate">// Production steps of ECMA-262, Edition 5, 15.4.4.18
// Reference: http://es5.github.com/#x15.4.4.18
if (!Array.prototype.forEach) {

  Array.prototype.forEach = function forEach(callback, thisArg) {
    'use strict';
    var T, k;

    if (this == null) {
      throw new TypeError("this is null or not defined");
    }

    var kValue,
        // 1. Let O be the result of calling ToObject passing the |this| value as the argument.
        O = Object(this),

        // 2. Let lenValue be the result of calling the Get internal method of O with the argument "length".
        // 3. Let len be ToUint32(lenValue).
        len = O.length &gt;&gt;&gt; 0; // Hack to convert O.length to a UInt32

    // 4. If IsCallable(callback) is false, throw a TypeError exception.
    // See: http://es5.github.com/#x9.11
    if ({}.toString.call(callback) !== "[object Function]") {
      throw new TypeError(callback + " is not a function");
    }

    // 5. If thisArg was supplied, let T be thisArg; else let T be undefined.
    if (arguments.length &gt;= 2) {
      T = thisArg;
    }

    // 6. Let k be 0
    k = 0;

    // 7. Repeat, while k &lt; len
    while (k &lt; len) {

      // a. Let Pk be ToString(k).
      //   This is implicit for LHS operands of the in operator
      // b. Let kPresent be the result of calling the HasProperty internal method of O with argument Pk.
      //   This step can be combined with c
      // c. If kPresent is true, then
      if (k in O) {

        // i. Let kValue be the result of calling the Get internal method of O with argument Pk.
        kValue = O[k];

        // ii. Call the Call internal method of callback with T as the this value and
        // argument list containing kValue, k, and O.
        callback.call(T, kValue, k, O);
      }
      // d. Increase k by 1.
      k++;
    }
    // 8. return undefined
  };
}

</pre>

<h2 id="Especificaciones">Especificaciones</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Especificación</th>
   <th scope="col">Estado</th>
   <th scope="col">Comentario</th>
  </tr>
  <tr>
   <td>{{SpecName('ES5.1', '#sec-15.4.4.18', 'Array.prototype.forEach')}}</td>
   <td>{{Spec2('ES5.1')}}</td>
   <td>Definición inicial. Implementada en JavaScript 1.6.</td>
  </tr>
  <tr>
   <td>{{SpecName('ES6', '#sec-array.prototype.foreach', 'Array.prototype.forEach')}}</td>
   <td>{{Spec2('ES6')}}</td>
   <td></td>
  </tr>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-array.prototype.foreach', 'Array.prototype.forEach')}}</td>
   <td>{{Spec2('ESDraft')}}</td>
   <td></td>
  </tr>
 </tbody>
</table>

<h2 id="Compatibilidad_con_navegadores">Compatibilidad con navegadores</h2>

<div>{{Compat("javascript.builtins.Array.forEach")}}</div>

<div id="compat-mobile"></div>

<h2 id="Vea_también">Vea también</h2>

<ul>
 <li>{{jsxref("Array.prototype.find()")}}</li>
 <li>{{jsxref("Array.prototype.findIndex()")}}</li>
 <li>{{jsxref("Array.prototype.map()")}}</li>
 <li>{{jsxref("Array.prototype.every()")}}</li>
 <li>{{jsxref("Array.prototype.some()")}}</li>
 <li>{{jsxref("Map.prototype.forEach()")}}</li>
 <li>{{jsxref("Set.prototype.forEach()")}}</li>
</ul>