diff options
Diffstat (limited to 'files/pt-br/web/javascript/reference/global_objects/array/find')
| -rw-r--r-- | files/pt-br/web/javascript/reference/global_objects/array/find/index.html | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/files/pt-br/web/javascript/reference/global_objects/array/find/index.html b/files/pt-br/web/javascript/reference/global_objects/array/find/index.html new file mode 100644 index 0000000000..904f65c200 --- /dev/null +++ b/files/pt-br/web/javascript/reference/global_objects/array/find/index.html @@ -0,0 +1,157 @@ +--- +title: Array.prototype.find() +slug: Web/JavaScript/Reference/Global_Objects/Array/find +translation_of: Web/JavaScript/Reference/Global_Objects/Array/find +--- +<div>{{JSRef}}</div> + +<p>O método <code><strong>find()</strong></code> retorna o <strong>valor </strong>do <strong>primeiro elemento</strong> do array que satisfizer a função de teste provida. Caso contrario, {{jsxref("undefined")}} é retornado.</p> + +<div>{{EmbedInteractiveExample("pages/js/array-find.html")}}</div> + +<p class="hidden">O código-fonte desse exemplo interativo está em um repositório do GitHub. Se você quiser contribuir para o projeto de exemplos interativos, clone <a href="https://github.com/mdn/interactive-examples">https://github.com/mdn/interactive-examples</a> e nos envie um pull request.</p> + +<p>Veja também o método {{jsxref("Array.findIndex", "findIndex()")}}, que retorna o <strong>índice</strong> do elemento encontrado no array ao invés do seu valor.</p> + +<p>Se você precisa encontrar a posição de um elemento ou se um elemento existe em um array, use {{jsxref("Array.prototype.indexOf()")}} ou {{jsxref("Array.prototype.includes()")}}.</p> + +<h2 id="Sintaxe">Sintaxe</h2> + +<pre class="syntaxbox notranslate"><var>arr</var>.find(<var>callback(element[, index[, array]])</var>[, <var>thisArg</var>])</pre> + +<h3 id="Parâmetros">Parâmetros</h3> + +<dl> + <dt><code>callback</code></dt> + <dd>Função executada a cada iteração do array, recebendo três argumentos: + <dl> + <dt><code>element</code></dt> + <dd>O elemento atual que está sendo processado no array.</dd> + <dt><code>index</code>{{optional_inline}}</dt> + <dd>O índice do elemento atualmente sendo processado no array.</dd> + <dt><code>array</code>{{optional_inline}}</dt> + <dd>O array sobre o qual <code>find</code> foi chamado.</dd> + </dl> + </dd> + <dt><code>thisArg</code>{{optional_inline}}</dt> + <dd>Opcional. Objeto usado como <code>this</code> quando executando o <code>callback</code>.</dd> +</dl> + +<h3 id="Valor_retornado">Valor retornado</h3> + +<p>O <strong>valor</strong> do <strong>primeiro elemento</strong> do array que satisfaz a função de teste fornecida; caso contrário, {{jsxref("undefined")}}.</p> + +<h2 id="Descrição">Descrição</h2> + +<p>O método <code>find</code> executa a função <code>callback </code>uma vez para cada elemento presente no array até que encontre um onde <code>callback</code> retorne o valor true. Se o elemento é encontrado, <code>find</code> retorna imediatamente o valor deste elemento. Caso contrário, <code>find</code> retorna {{jsxref("Global_Objects/undefined", "undefined")}}. O <code>callback </code>é acionado para todos os índices do array de <code>0</code> a <code>tamanho-1</code>, não apenas para aqueles que possuem valores atribuídos. Sendo assim, ele pode ser menos eficiente para arrays muito grandes em que existem outros métodos que só visitam os índices que tenham valor atribuído.</p> + +<p>O <code>callback</code> é acionado com três argumentos: o valor do elemento, o índice do elemento e o objeto do Array que está sendo executado.</p> + +<p>Se um parâmetro <code>thisArg</code> é provido ao <code>find</code>, ele será usado como o <code>this</code> para cada acionamento do <code>callback</code>. Se não for provido, então {{jsxref("Global_Objects/undefined", "undefined")}} é usado.</p> + +<p>O <code>find</code> não altera a array à qual foi acionado.</p> + +<p>O conjunto dos elementos processados por <code>find</code> é definido antes do primeiro acionamento do <code>callback</code>. Elementos que são anexados à array após o início da chamada ao <code>find</code> não serão visitados pelo <code>callback</code>. Se um elemento existente ainda não visitado da array for alterado pelo <code>callback</code>, o valor passado ao <code>callback</code> quando o visitar será o valor no momento que <code>find</code> visita o índice daquele elemento; elementos excluídos ainda são visitados.</p> + +<h2 id="Exemplos">Exemplos</h2> + +<h3 id="Encontrar_um_objeto_em_um_array_por_uma_de_suas_propriedades">Encontrar um objeto em um array por uma de suas propriedades</h3> + +<pre class="brush: js notranslate">const inventory = [ + {name: 'apples', quantity: 2}, + {name: 'bananas', quantity: 0}, + {name: 'cerejas', quantity: 5} +]; + +function isCherries(fruit) { + return fruit.name === 'cerejas'; +} + +console.log(inventory.find(isCherries)); +// { name: 'cerejas', quantity: 5 }</pre> + +<h4 id="Utilizando_arrow_function">Utilizando arrow function</h4> + +<pre class="brush: js notranslate">const inventory = [ + {name: 'maças', quantity: 2}, + {name: 'bananas', quantity: 0}, + {name: 'cherries', quantity: 5} +]; + +const result = inventory.find( fruit => fruit.name === 'cherries' ); + +console.log(result) // { name: 'cherries', quantity: 5 }</pre> + +<h3 id="Encontrar_um_número_primo_em_um_array">Encontrar um número primo em um array</h3> + +<p>O exemplo a seguir encontra um elemento dentro da array que é número primo (ou retorna {{jsxref("Global_Objects/undefined", "undefined")}} se não houverem números primos).</p> + +<pre class="brush: js notranslate">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 +</pre> + +<h2 id="Polyfill">Polyfill</h2> + +<p>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 <code>Array.prototype.find</code> com o trecho de código abaixo:</p> + +<pre class="brush: js notranslate">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; + }; +} +</pre> + +<h2 id="Especificações">Especificações</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificação</th> + <th scope="col">Status</th> + <th scope="col">Comentário</th> + </tr> + <tr> + <td>{{SpecName('ES6', '#sec-array.prototype.find', 'Array.prototype.find')}}</td> + <td>{{Spec2('ES6')}}</td> + <td>Definição inicial.</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidade_do_Navegador">Compatibilidade do Navegador</h2> + +<div>{{Compat("javascript.builtins.Array.find")}}</div> + +<h2 id="Veja_também">Veja também</h2> + +<ul> + <li>{{jsxref("Array.prototype.findIndex()")}} {{experimental_inline}}</li> + <li>{{jsxref("Array.prototype.every()")}}</li> +</ul> |