Array.prototype.filter()

El mètode filter() crea un nou array amb tots els elements que passin el test implementat per la funció que passa com a argument.

Sintaxi

arr.filter(callback[, thisArg])

Paràmetres

callback

Funció que s'emprarà per a testejar cada element de l'array. Aquesta serà invocada amb els arguments (element, posició, array). Ha de retornar true per als elements que es vulguin conservar i false en qualsevol altre cas.

thisArg

Opcional. Valor que rebrà this durant l'execució de la funció callback.

Descripció

filter() crida la funció callback proporcionada un cop per cada element de l'array, i construeix un nou array amb tots els elements per als quals la funció callback retorni el valor true o bé un valor que pugui ser interpretat com a true. Només escridarà la funció callback per a posicions de l'array que tinguin valors assignats; no es cridarà per a posicions que han estat esborrades o que mai hagin tingut assignat un element. Els elements que no passsin el test de callback seràn simplement ignorats i en cap cas seran afegits al nou array.

S'invoca callback tot passant-li els tres arguments següents:

1. el valor de l'element
2. la posició de l'element
3. L'objecte array que s'està recorrent

Si es proporciona el paràmetre thisArg a la crida de filter, aquest es passarà a callback quan s'invoqui per a ser utilitzat com a this dins la funció.  En qualsevol altre cas el valor que rebrà this dins la funció callback serà undefined. El valor de this que serà finalment observable dins de callback és determinat d'acord a les regles habituals per a determinar el valor de this observat dins d'una fuunció.

filter() mai modificarà l'array des del qual s'invoca.

El rang dels elements processats per filter() es determina abans de la primera invocació de callback. Els elements que s'afegeixin a l'array un cop la crida a  filter() hagi començat no seran visibles per a callback. Els elements que es modifiquin o s'esborrin durant aquest periode tindran el valor que els hi pertoqui al moment de cridar la funció callback; els elements que s'hagin eliminat no es visitaran.

Exemples

Exemple: Descartar tots els valors petits

L'exemple següent utilitza filter() per a crear un array filtrat que contindrà tots els elements amb valors menors de 10.

function esProuGran(valor) {
  return valor >= 10;
}
var filtrat = [12, 5, 8, 130, 44].filter(esProuGran);
// filtrat val [12, 130, 44]

Exemple: Descartar entrades invàlides de JSON

L'exemple següent utilitza filter() per a crear un array que no contingui cap entrada de JSON amb una id numèrica no vàlida o amb valor menor que zero.

var arr = [
  { id: 15 },
  { id: -1 },
  { id: 0 },
  { id: 3 },
  { id: 12.2 },
  { },
  { id: null },
  { id: NaN },
  { id: 'undefined' }
];

var invalidEntries = 0;

function filterByID(obj) {
  if ('id' in obj && typeof(obj.id) === 'number' && !isNaN(obj.id)) {
    return true;
  } else {
    invalidEntries++;
    return false;
  }
}

var arrByID = arr.filter(filterByID);

console.log('Array filtrat\n', arrByID); 
// [{ id: 15 }, { id: -1 }, { id: 0 }, { id: 3 }, { id: 12.2 }]

console.log('Nombre d'entrades invàlides = ', invalidEntries); 
// 4

Polyfill

filter() va ser afegit al standard ECMA-262 a la cinquena edició; degut a això aquesta funció pot no ser present a totes les implementacions del standard. Es pot solucionar aquest problema inserint el codi següent al principi dels scripts, permetent l'ús de filter() en implementacions de l'ECMA-262 que no la incorporin per defecte. Aquest algoritme és exactament l'especificat per l'ECMA-262, 5a edició, i assumeix que fn.call s'evalua al valor original de Function.prototype.call() i que Array.prototype.push() te el seu valor original.

if (!Array.prototype.filter) {
  Array.prototype.filter = function(fun/*, thisArg*/) {
    '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 res = [];
    var thisArg = arguments.length >= 2 ? arguments[1] : void 0;
    for (var i = 0; i < len; i++) {
      if (i in t) {
        var val = t[i];

        // NOTA: Tècnicament hauria de ser Object.defineProperty
        //       a la posició següent ja que push pot veure's afectat per
        //       les propietats de Object.prototype i Array.prototype.
        //       Però aquest mètode és nou i només hi haurà col·lisions
        //       en casos excepcionals, aixíq ue utilitzem l'alternativa més compatible.
        if (fun.call(thisArg, val, i, t)) {
          res.push(val);
        }
      }
    }

    return res;
  };
}

Especificacions

Compatibilitat amb navegadors

Vegeu també

• Array.prototype.forEach()
• Array.prototype.every()
• Array.prototype.some()
• Array.prototype.reduce()