Array.prototype.filter()

La méthode filter() crée et retourne un nouveau tableau contenant tous les éléments du tableau d'origine pour lesquels la fonction callback retourne true.

function suffisammentGrand(element) {
  return element >= 10;
}
var filtre = [12, 5, 8, 130, 44].filter(suffisammentGrand);
// filtre vaut [12, 130, 44]

Syntaxe

var new_array = arr.filter(callback[, thisArg])

Paramètres

callback

La fonction de test (ou prédicat) à appliquer à chaque élément du tableau. Cette fonction est appelée avec les arguments suivants :

element

L'élément à traiter

index

Son indice.

array

Le tableau complet

Cette fonction renvoie true si l'élément doit être conservé pour le tableau résultat et false sinon.

thisArg

Objet à utiliser en tant que this quand la fonction callback est exécutée.

Valeur de retour

Un nouveau tableau contenant les éléments qui respectent la condition du filtre.

Description

filter() appelle la fonction callback fournie pour chacun des éléments d'un tableau, et construit un nouveau tableau contenant tous les éléments pour lesquels l'appel de callback retourne true ou une valeur équivalente à true dans un contexte booléen. La fonction callback n'est utilisée que pour les éléments du tableau ayant une valeur assignée - les index supprimés ou pour lesquels il n'y a jamais eu de valeur ne sont pas pris en compte. Les éléments du tableau qui ne passent pas le test effectué par la fonction callback sont simplement ignorés, et ne sont pas inclus dans le nouveau tableau.

La fonction callback est appelée avec trois arguments :

1. la valeur de l'élément courant
2. l'index de l'élément courant
3. l'objet Array traversé

Si le paramètre thisArg est fourni, il sera utilisé comme objet this lors de l'appel de la fonction callback. Sinon, la valeur undefined sera utilisée à la place. Par ailleurs, la valeur de this accessible depuis la fonction callback est déterminée selon les règles usuelles de pour déterminer la valeur this au sein d'une fonction.

filter() ne modifie pas le tableau d'origine.

La liste des éléments parcourus par filter() est définie avant la première invocation de la fonction callback. Les éléments qui sont ajoutés à la liste après le début de l'appel de filter() (grâce à la fonction callback par exemple) ne seront pas visités. Si des éléments existants de la liste sont modifiés ou supprimés, la valeur fournie à la fonction callback sera leur valeur au moment où filter() les visite - les éléments supprimés ne seront pas traités par la fonction.

Exemples

Filtrer les petites valeurs

L'exemple suivant utilise filter afin de créer une liste filtrée où on a retiré tous les éléments dont la valeur est inférieure à 10.

function suffisammentGrand(element) {
  return element >= 10;
}
var filtre = [12, 5, 8, 130, 44].filter(suffisammentGrand);
// filtre vaut [12, 130, 44] 

Filtrer des éléments JSON invalides et les trier en fonction d'un identifiant avec filter()

Dans l'exemple qui suit, on utilise filter() afin de créer un objet JSON qui contient des éléments avec un id qui est un entier.

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

var elementsInvalides = 0;

function filtrerParID(obj) {
  if (obj.id !== undefined && typeof(obj.id) === 'number' && !isNaN(obj.id)) {
    return true;
  } else {
    elementsInvalides++;
    return false;
  }
}

var arrByID = arr.filter(filtrerParID);

console.log('Tableau filtré\n', arrByID);
// Le tableau filtré est :
// [{ id: 15 }, { id: -1 }, { id: 0 }, { id: 3 }, { id: 12.2 }]

console.log('Nombre d\'éléments invalides = ', elementsInvalides);
// Nombre d'éléments invalides 4

Prothèse d'émulation (polyfill)

Array.prototype.filter() a été ajoutée avec la cinquième édition du standard ECMA-262 - ainsi elle pourrait ne pas être présente dans toutes les implémentations du standard. Ce problème peut être contourné en ajoutant le code suivant au début des scripts et permettra d'utiliser filter au sein d'implémentations qui n'en bénéficient pas nativement. Cet algorithme est celui exactement spécifié par la cinquième édition d'ECMA-262, en considérant que callbackfn.call est évaluée avec la valeur d'origine de Function.prototype.call et que Array.prototype.push a sa valeur d'origine.

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;
    
    // NOTE : fix to avoid very long loop on negative length value
    
    if (len > t.length || 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];

        // NOTE: Techniquement on devrait utiliser Object.defineProperty
        //       pour le prochain index car push peut être affecté
        //       par les propriétés d'Object.prototype et d'Array.prototype.
        //       Cependant cette méthode est récente et les cas de collisions
        //       devraient rester rares : on préfère donc l'alternative la plus
        //       compatible.
        if (fun.call(thisArg, val, i, t))
          res.push(val);
      }
    }

    return res;
  };
}

Spécifications

Compatibilité des navigateurs

Voir aussi

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