Array.prototype.filter()

O método filter() cria um novo array com todos os elementos que passaram ao teste (retornaram true) implementado pela função fornecida.

Sintaxe

arr.filter(callback[, thisArg])

Parâmetros

callback

Função para testar cada elemento do array. Invocada com os parâmetros (element, index, array). Retorna true para manter o elemento, false caso contrário.

thisArg

Opcional. Valor para ser usado como this quando executar o callback.

Descrição

filter() chama a função callback fornecida, uma vez para cada elemento do array, e constrói um novo array com todos os valores para os quais o callback retornou o valor true ou  um valor que seja convertido para true. O callback é chamado apenas para índices do array que possuem valores atribuídos; Ele não é invocado para índices que foram excluídos ou para aqueles que não tiveram valor atribuído. Elementos do array que não passaram no teste do callback são simplesmente ignorados, e não são incluídos no novo array.

callback é invocado com estes três argumentos:

1. o valor do elemento
2. o índice do elemento
3. o objeto do array a ser preenchido

So o parâmetro thisArg for provido para o filter, ele será passado para o callback quando invocado, para ser usado como o valor do this. Caso contrário, será passado undefined como o valor de this. O valor do this finalmente observado pela função de callback é determinado de acordo com a regra que define o valor do this geralmente visto por uma função.

filter() não altera a array a partir da qual foi invocado.

O intervalo de elementos processados pela função filter() é definido antes da invocação do primeiro callback. Elementos que forem adicionados ao array depois que a invocação do filter() não serão visitados pelo callback. Se elementos existentes no array forem alterados ou deletados, o valor deles passado para o callback será o valor que eles tenham quando o  filter() visitá-los; Elementos que forem deletados não são visitados..

Examples

Example: Filtering out all small values

Os exemplos a seguir usa filter() para criar um array filtrado cujo todos os elementos com valores menores que 10 foram removidos.

function isBigEnough(value) {
  return value >= 10;
}
var filtered = [12, 5, 8, 130, 44].filter(isBigEnough);
// filtered is [12, 130, 44]

Example: Filtrando entradas inválidas para JSON

O exemplo a seguir usa filter() para criar um json filtrado com todos seus elementos diferentes de zero, e id numérido.

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('Filtered Array\n', arrByID); 
// [{ id: 15 }, { id: -1 }, { id: 0 }, { id: 3 }, { id: 12.2 }]

console.log('Number of Invalid Entries = ', invalidEntries); 
// 4

Polyfill

filter() foi adicionado ao padrão ECMA-262 na 5ª edição; assim como pode não estar presente em todas as implementações do padrão. Você pode trabalhar com isso adicionando o seguinte código no início de seus scripts, permitindo o uso do filter() na implementação ECMA-262 que não tem suporte nativo. Esse algoritmo é exatamente aquele especificado na 5ª edição do ECMA-262, assumindo que fn.call veja o valor original de Function.prototype.call(), e que Array.prototype.push() tenha 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];

        // NOTE: Technically this should Object.defineProperty at
        //       the next index, as push can be affected by
        //       properties on Object.prototype and Array.prototype.
        //       But that method's new, and collisions should be
        //       rare, so use the more-compatible alternative.
        if (fun.call(thisArg, val, i, t)) {
          res.push(val);
        }
      }
    }

    return res;
  };
}

Especificações

Compatibilidade de Browser

Veja também

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