Array.prototype.find()

O método find() retorna um valor no array, se algum elemento no array satisfazer a função de teste provida. Caso contrario undefined é retornado.

Veja também o método findIndex(), que retorna o index de um elemento encontrado no array, ao invés do seu valor.

Sintaxe

arr.find(callback[, thisArg])

Parâmetros

callback

Função executada a cada iteração do array, recebendo três argumentos:

element

O elemento atual que está sendo processado no array.

index

O índice do elemento atualmente sendo processado no array.

array

O array sobre o qual find foi chamado.

thisArg

Opcional. Objeto usado como this quando executando o callback.

Descrição

O método find executa a função callback uma vez para cada elemento presente no array até que encontre um cujo callback  retorne o valor true. Se o elemento é encontrado, find retorna imediatamente o valor deste elemento. Caso contrário, find retorna   undefined. O callback somente é acionado para os índices do array que possuem valor atribuido; ele não é acionado para índices que tenham sido deletados ou que nunca tenham tido valores atribuídos.

O callback é acionado com três argumentos: o valor do elemento, o índice do elemento e o objeto do Array que está sendo cruzado.

Se um parâmetro thisArg é provido ao find, ele será usado como o this para cada acionamento do callback. Se não for provido, então undefined é usado.

O find não altera a array a qual foi acionado.

O alcance dos elementos processados por find é definido antes do primeiro acionamento do callback. Elementos que são anexados à array após o início da chamada to find não serão visitados pelo callback. Se um elemento existente, não visitado da array for alterado pelo callback, o valor que é passado ao callback  que o visita será o valor do momento que find visita o índice daquele elemento; elementos que são excluídos não são visitados.

Exemplos

Encontrar um número primo em uma array

O exemplo a seguir encontra um elemento dentro da array que é número primo (ou retorna undefined se não houverem números primos).

function isPrime(element, index, array) {
  var start = 2;
  while (start <= Math.sqrt(element)) {
    if (element % start++ < 1) {
      return false;
    }
  }
  return element > 1;
}

console.log([4, 6, 8, 12].find(isPrime)); // undefined, not found
console.log([4, 5, 8, 12].find(isPrime)); // 5

Polyfill

Este método foi adicionado à especificação do ECMAScript 2015 e pode não estar disponível em todas as implementações do JavaScript. Entretanto, você pode fazer um polyfill para o Array.prototype.find com o trecho de código abaixo:

if (!Array.prototype.find) {
  Array.prototype.find = function(predicate) {
    if (this === null) {
      throw new TypeError('Array.prototype.find called on null or undefined');
    }
    if (typeof predicate !== 'function') {
      throw new TypeError('predicate must be a function');
    }
    var list = Object(this);
    var length = list.length >>> 0;
    var thisArg = arguments[1];
    var value;

    for (var i = 0; i < length; i++) {
      value = list[i];
      if (predicate.call(thisArg, value, i, list)) {
        return value;
      }
    }
    return undefined;
  };
}

Especificações

Compatibilidade do Navegador

Veja também

• Array.prototype.findIndex()
• Array.prototype.every()