diff options
Diffstat (limited to 'files/pt-pt/web/javascript/reference/global_objects/array/find/index.html')
| -rw-r--r-- | files/pt-pt/web/javascript/reference/global_objects/array/find/index.html | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/files/pt-pt/web/javascript/reference/global_objects/array/find/index.html b/files/pt-pt/web/javascript/reference/global_objects/array/find/index.html new file mode 100644 index 0000000000..3eedeb54a9 --- /dev/null +++ b/files/pt-pt/web/javascript/reference/global_objects/array/find/index.html @@ -0,0 +1,210 @@ +--- +title: Array.prototype.find() +slug: Web/JavaScript/Reference/Global_Objects/Array/find +tags: + - Array + - ECMAScript 2015 + - JavaScript + - Method + - polyfill +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 primeiro elemento do array que satisfaça a função de teste fornecida. Caso contrário o valor {{jsxref("undefined")}} é retornado.</p> + +<div>{{EmbedInteractiveExample("pages/js/array-find.html")}}</div> + + + +<p>Ver também o método {{jsxref("Array.findIndex", "findIndex()")}} , o qual retorna o <strong>index</strong> de um elemento encontrado num array, em alternativa do seu valor.</p> + +<p>É possível obter a posição de um elemento ou verificar a sua existência num array, através da função {{jsxref("Array.prototype.indexOf()")}} ou {{jsxref("Array.prototype.includes()")}}.</p> + +<h2 id="Sintaxe">Sintaxe</h2> + +<pre class="syntaxbox"><var>arr</var>.find(<var>callback</var>[, <var>thisArg</var>])</pre> + +<h3 id="Parâmetros">Parâmetros</h3> + +<dl> + <dt><code>callback</code></dt> + <dd>Função a executar em cada elemento do array, utilizando três argumentos: + <dl> + <dt><code>element</code></dt> + <dd>O elemento a ser processado no array.</dd> + <dt><code>index</code>{{optional_inline}}</dt> + <dd>O index do elemento a ser processado no array.</dd> + <dt><code>array</code>{{optional_inline}}</dt> + <dd>O array no qual o método <code>find</code> foi chamado.</dd> + </dl> + </dd> + <dt><code>thisArg</code> <code>{{Optional_inline}}</code></dt> + <dd>Objeto para usar como <code>this</code> ao executar a <code>callback</code>.</dd> +</dl> + +<h3 id="Valor_de_retorno">Valor de retorno</h3> + +<p>Um valor do array caso um elemento passe no teste; caso contrário, {{jsxref("undefined")}}.</p> + +<h2 id="Descrição">Descrição</h2> + +<p>O método<code>find</code> executa a <code>callback</code> uma vez para cada index do array até ser encontrado um no qual a <code>callback</code> retorna o valor true. Caso um elemento seja encontrado, o método <code>find</code> retorna imediatamente o seu valor. Caso contrário, o método <code>find</code> retorna {{jsxref("undefined")}}. A função de <code>callback</code> é invocada para cada index do array do <code>0</code> ao <code>length - 1</code> e é invocada para todos os indexes, não apenas nos que tem valor. Isto pode significar que é menos eficiente para o um array com muitos elementos sem valor (sparse array) do que outros métodos que visitam apenas os elementos com valor.</p> + +<p>A função de <code>callback</code> é invocada com 3 parâmetros: o valor do elemento, o index do elemento, e o Array no qual é executado.</p> + +<p>Se o parâmetro <code>thisArg</code> for disponibilizado ao método <code>find</code>, este será usado como <code>this</code> para cada invocação da <code>callback</code>. Caso contrário, será usado o valor {{jsxref("undefined")}}.</p> + +<p>O método <code>find</code> não altera o array no qual é invocado.</p> + +<p>A quantidade de elementos processados pelo método <code>find</code> é definida antes da invocação da <code>callback</code>. Os elementos adicionados ao array após o método <code>find</code> ter iniciado não serão visitados pela <code>callback</code>. Se um elemento existente e não visitado, for alterado pela <code>callback</code>, o seu valor que foi passado para a <code>callback</code> será o valor a ser avaliado pelo método <code>find</code>; Os elementos eliminados após o inicio do método find também serão visitados.</p> + +<h2 id="Exemplos">Exemplos</h2> + +<h3 id="Encontrar_um_objeto_num_array_através_de_uma_das_suas_propriedades">Encontrar um objeto num array através de uma das suas propriedades</h3> + +<pre class="brush: js">var inventory = [ + {name: 'apples', quantity: 2}, + {name: 'bananas', quantity: 0}, + {name: 'cherries', quantity: 5} +]; + +function isCherries(fruit) { + return fruit.name === 'cherries'; +} + +console.log(inventory.find(isCherries)); +// { name: 'cherries', quantity: 5 }</pre> + +<h3 id="Encontrar_um_número_primo_num_array">Encontrar um número primo num array</h3> + +<p>O seguinte exemplo encontra um elemento no array que seja um número primo (caso não exista, retorna {{jsxref("undefined")}} ).</p> + +<pre class="brush: js">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> + +<p>O seguinte exemplo, apresenta como os elementos não existentes e eliminados são visitados e o seu valor passado para a callback será o seu valor quando visitado.</p> + +<pre class="brush: js">// Declare array with no element at index 2, 3 and 4 +var a = [0,1,,,,5,6]; + +// Shows all indexes, not just those that have been assigned values +a.find(function(value, index) { + console.log('Visited index ' + index + ' with value ' + value); +}); + +// Shows all indexes, including deleted +a.find(function(value, index) { + + // Delete element 5 on first iteration + if (index == 0) { + console.log('Deleting a[5] with value ' + a[5]); + delete a[5]; + } + // Element 5 is still visited even though deleted + console.log('Visited index ' + index + ' with value ' + value); +}); + +</pre> + +<h2 id="Polyfill">Polyfill</h2> + +<p>Este método foi adicionado ao <em>ECMAScript 2015 Language Specification </em>e pode não estar disponível em todas as implementações de JavaScript. É possível desenvolver o polyfill do método find com o seguinte código:</p> + +<pre class="brush: js">// https://tc39.github.io/ecma262/#sec-array.prototype.find +if (!Array.prototype.find) { + Object.defineProperty(Array.prototype, 'find', { + value: function(predicate) { + // 1. Let O be ? ToObject(this value). + if (this == null) { + throw new TypeError('"this" is null or not defined'); + } + + var o = Object(this); + + // 2. Let len be ? ToLength(? Get(O, "length")). + var len = o.length >>> 0; + + // 3. If IsCallable(predicate) is false, throw a TypeError exception. + if (typeof predicate !== 'function') { + throw new TypeError('predicate must be a function'); + } + + // 4. If thisArg was supplied, let T be thisArg; else let T be undefined. + var thisArg = arguments[1]; + + // 5. Let k be 0. + var k = 0; + + // 6. Repeat, while k < len + while (k < len) { + // a. Let Pk be ! ToString(k). + // b. Let kValue be ? Get(O, Pk). + // c. Let testResult be ToBoolean(? Call(predicate, T, « kValue, k, O »)). + // d. If testResult is true, return kValue. + var kValue = o[k]; + if (predicate.call(thisArg, kValue, k, o)) { + return kValue; + } + // e. Increase k by 1. + k++; + } + + // 7. Return undefined. + return undefined; + } + }); +} +</pre> + +<p>É melhor não utilizar o polyfill <code>Array.prototype</code> para motores JavaScript obsoletos que não suportem métodos <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty">Object.defineProperty</a></code>, uma vez que, não é possível torna-los não-enumeráveis.</p> + +<h2 id="Especificações">Especificações</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificação</th> + <th scope="col">Estado</th> + <th scope="col">Comentário</th> + </tr> + <tr> + <td>{{SpecName('ES2015', '#sec-array.prototype.find', 'Array.prototype.find')}}</td> + <td>{{Spec2('ES2015')}}</td> + <td>Initial definition.</td> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-array.prototype.find', 'Array.prototype.find')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidade_de_Browsers">Compatibilidade de Browsers</h2> + +<div> + + +<p>{{Compat("javascript.builtins.Array.find")}}</p> +</div> + +<h2 id="Ver_também">Ver também</h2> + +<ul> + <li>{{jsxref("Array.prototype.findIndex()")}} – procurar e obter um index</li> + <li>{{jsxref("Array.prototype.includes()")}} – testar se existe um valor num array</li> + <li>{{jsxref("Array.prototype.filter()")}} – encontrar todos os elementos</li> + <li>{{jsxref("Array.prototype.every()")}} – testar se todos os elementos cumprem o requisito</li> +</ul> |