Exibir código-fonte para Módulo:TableTools/doc

<section begin=header />
{{#ifeq:{{#invoke:String|find|{{FULLPAGENAME}}|Testes}}|0|<includeonly>{{alto-risco|113000}}</includeonly>}}
<section end=header />
<!---->
{{Lua|Módulo:Exponential search|noprotcat=yes}}
Este módulo inclui várias funções para lidar com tabelas Lua. É um metamódulo, destinado a ser chamado a partir de outros módulos Lua e não deve ser chamado diretamente a partir de "#invoke".

==Carregando o módulo==
Para usar qualquer uma das funções, primeiro é necessário carregar o módulo.
<syntaxhighlight lang="lua">
local TableTools = require('Módulo:TableTools')
</syntaxhighlight>

==isPositiveInteger==
<syntaxhighlight lang="lua">
TableTools.isPositiveInteger(value)
</syntaxhighlight>
Esta função retorna <code>true</code> se <code>''value''</code> for um número inteiro positivo e <code>false</code> se não for. Embora não opere em tabelas, está incluída aqui porque é útil para determinar se uma determinada chave de tabela está na parte arranjo ou na parte ''hash'' de uma tabela.

==isNan==
<syntaxhighlight lang="lua">
TableTools.isNan(value)
</syntaxhighlight>
Esta função retorna <code>true</code> se <code>''value''</code> for um valor ''[[NaN]]'' e <code>false</code> se não for. Embora não opere em tabelas, está incluída aqui porque é útil para determinar se um valor pode ser uma chave de tabela válida. (Lua gerará um erro se um valor ''NaN'' for usado como uma chave de tabela.)

==shallowClone==
<syntaxhighlight lang="lua">
TableTools.shallowClone(t)
</syntaxhighlight>
Esta função retorna um clone de uma tabela. O valor retornado é uma nova tabela, mas todas as subtabelas e funções são compartilhadas. Os metamétodos são respeitados, mas a tabela retornada não terá metatabela própria. Se você quiser criar uma nova tabela sem subtabelas compartilhadas e com metatabelas transferidas, você pode usar <code>[[mw:Extension:Scribunto/Lua reference manual/pt-br#mw.clone|mw.clone]]</code>. Se você deseja criar uma nova tabela sem subtabelas compartilhadas e sem metatabelas transferidas, use <code>[[#deepCopy|deepCopy]]</code> com a opção <code>noMetatable</code>.

==removeDuplicates==
<syntaxhighlight lang="lua">
TableTools.removeDuplicates(t)
</syntaxhighlight>
Esta função remove valores duplicados de um arranjo. Esta função foi projetada para funcionar apenas com arranjos padrões: as chaves que não são números inteiros positivos são ignoradas, assim como todos os valores após o primeiro valor <code>nil</code>. (Para arranjos contendo valores <code>nil</code>, você pode usar <code>[[#compressSparseArray|compressSparseArray]]</code> primeiro.) A função tenta preservar a ordem do arranjo: o primeiro valor que não for exclusivo (único) é mantido e todos os valores duplicados subsequentes são removidos. Por exemplo, para a tabela {{Código|code={5, 4, 4, 3, 4, 2, 2, 1}|lang=lua}} <code>removeDuplicates</code> retornará {{Código|code ={5, 4, 3, 2, 1}|lang=lua}}.

==numKeys==
<syntaxhighlight lang="lua">
TableTools.numKeys(t)
</syntaxhighlight>
Esta função pega uma tabela <code>''t''</code> e retorna um arranjo contendo os números de quaisquer chaves inteiras positivas que tenham valores que não são nulos, classificados em ordem numérica. Por exemplo, para a tabela {{Código|code={'foo', nil, 'bar', 'baz', a = 'b'}|lang=lua}}, <code>numKeys</code> retornará {{Código|code={1, 3, 4}|lang=lua}}.

==affixNums==
<syntaxhighlight lang="lua">
TableTools.affixNums(t, prefix, suffix)
</syntaxhighlight>
Esta função pega uma tabela <code>''t''</code> e retorna um arranjo contendo os números de chaves com o prefixo opcional <code>''prefix''</code> e o sufixo opcional <code>''suffix''</code>. Por exemplo, para a tabela {{Código|code={a1 = 'foo', a3 = 'bar', a6 = 'baz'}|lang=lua}} e o prefixo <code>'a'</code> , <code>affixNums</code> retornará {{Código|code={1, 3, 6}|lang=lua}}. Todos os caracteres em <code>''prefix''</code> e <code>''suffix''</code> são interpretados literalmente.

==numData==
<syntaxhighlight lang="lua">
TableTools.numData(t, compress)
</syntaxhighlight>
Dada uma tabela com chaves como <code>"foo1"</code>, <code>"bar1"</code>, <code>"foo2"</code> e <code>"baz2"</code>, esta função retorna uma tabela de subtabelas no formato {{Código|code={ [1] = {foo = 'text', bar = 'text'}, [2] = {foo = 'text', baz = 'text' } }|lang=lua}}. As chaves que não terminam com um número inteiro são armazenadas em uma subtabela chamada <code>"other"</code>. A opção "compress" comprime a tabela para que possa ser iterada com <code>ipairs</code>.

==compressSparseArray==
<syntaxhighlight lang="lua">
TableTools.compressSparseArray(t)
</syntaxhighlight>
Esta função pega um arranjo <code>''t''</code> com um ou mais valores nulos, e remove os valores nulos enquanto preserva a ordem, para que o arranjo possa ser percorrido com segurança com <code>ipairs</code>. Quaisquer chaves que não sejam números inteiros positivos são removidas. Por exemplo, para a tabela {{Código|code={1, nil, foo = 'bar', 3, 2}|lang=lua}}, <code>compressSparseArray</code> retornará {{Código|code={1, 3, 2}|lang=lua}}.

==sparseIpairs==
<syntaxhighlight lang="lua">
TableTools.sparseIpairs(t)
</syntaxhighlight>
Esta é uma função iteradora para percorrer um arranjo esparso <code>''t''</code>. É semelhante a <code>[[mw:Extension:Scribunto/Lua reference manual/pt-br#ipairs|ipairs]]</code>, mas continuará a iterar até a chave numérica mais alta, enquanto <code>ipairs</code> pode parar após o primeiro valor <code>nil</code>. Quaisquer chaves que não sejam números inteiros positivos são ignoradas.

Normalmente, <code>sparseIpairs</code> é usada em um ''loop'' <code>for</code> genérico.
<syntaxhighlight lang="lua">
for i, v in TableTools.sparseIpairs(t) do
   -- bloco de código
end
</syntaxhighlight>
Observe que <code>sparseIpairs</code> usa a função <code>[[mw:Extension:Scribunto/Lua reference manual/pt-br#pairs|pairs]]</code> em sua implementação. Embora algumas chaves da tabela pareçam ser ignoradas, todas as chaves da tabela são acessadas quando ela é executada.

==size==
<syntaxhighlight lang="lua">
TableTools.size(t)
</syntaxhighlight>
Localiza o tamanho de uma tabela de pares chave/valor ([[Vetor associativo|arranjo associativo]]). Por exemplo, para a tabela {{Código|code={foo = 'foo', bar = 'bar'}|lang=lua}}, <code>size</code> retornará <code>2</code>. A função também funcionará em arranjos, mas para arranjos é mais eficiente usar o operador <code>#</code>. Observe que para encontrar o tamanho, esta função usa a função <code>[[mw:Extension:Scribunto/Lua reference manual/pt-br#pairs|pairs]]</code> para percorrer todas as chaves.

==keysToList==
<syntaxhighlight lang="lua">
TableTools.keysToList(t, keySort, checked)
</syntaxhighlight>
Esta função retorna uma lista das chaves em uma tabela, classificadas usando uma função de comparação padrão ou uma função <code>''keySort''</code> personalizada, que segue as mesmas regras da função <code>comp</code> fornecida para <code>[[mw:Extension:Scribunto/Lua reference manual/pt-br#table.sort|table.sort]]</code>. Se <code>''keySort''</code> for <code>false</code>, nenhuma classificação será feita. É necessário definir <code>''checked''</code> como <code>true</code> para pular a verificação interna de tipo.

==sortedPairs==
<syntaxhighlight lang="lua">
TableTools.sortedPairs(t, keySort)
</syntaxhighlight>
Esta função itera por meio de uma tabela, com as chaves classificadas usando a função <code>keysToList</code>. Se houver apenas chaves numéricas, <code>sparseIpairs</code> provavelmente será mais eficiente.

==isArray==
<syntaxhighlight lang="lua">
TableTools.isArray(value)
</syntaxhighlight>
Esta função retorna <code>true</code> se <code>''value''</code> for uma tabela e todas as chaves forem inteiros consecutivos começando em 1.

==isArrayLike==
<syntaxhighlight lang="lua">
TableTools.isArrayLike(value)
</syntaxhighlight>
Esta função retorna <code>true</code> se <code>''value''</code> for iterável e todas as chaves forem inteiros consecutivos começando em 1.

==invert==
<syntaxhighlight lang="lua">
TableTools.invert(arr)
</syntaxhighlight>
Esta função transpõe as chaves e valores em um arranjo. Por exemplo, {{Código|invert{ "a", "b", "c" }|lua}} resulta em {{Código|code={ a=1, b=2, c=3 }|lang=lua}}.

==listToSet==
<syntaxhighlight lang="lua">
TableTools.listToSet(arr)
</syntaxhighlight>
Esta função cria um conjunto a partir da parte arranjo da tabela <code>''arr''</code>. A indexação do conjunto por qualquer um dos valores do arranjo retorna <code>true</code>. Por exemplo, {{Código|listToSet{ "a", "b", "c" }|lua}} resulta em {{Código|code={ a=true, b=true, c=true }|lang=lua}}.

==deepCopy==
<syntaxhighlight lang="lua">
TableTools.deepCopy(orig, noMetatable, alreadySeen)
</syntaxhighlight>
Esta função cria uma cópia da tabela <code>''orig''</code>. Como em <code>mw.clone</code>, todos os valores que não são funções são duplicados e a identidade das tabelas é preservada. Se <code>''noMetatable''</code> for <code>true</code>, então a metatabela (se houver) não será copiada. Ela pode copiar tabelas carregadas com <code>mw.loadData</code>.

Similar à <code>mw.clone</code>, mas <code>mw.clone</code> não pode copiar tabelas carregadas com <code>mw.loadData</code> e não permite que metatabelas <em>não</em> sejam copiadas.

==sparseConcat==
<syntaxhighlight lang="lua">
TableTools.sparseConcat(t, sep, i, j)
</syntaxhighlight>
Esta função concatena todos os valores na tabela que são indexados por um número inteiro positivo, em ordem. Por exemplo, {{Código|sparseConcat{ "a", nil, "c", "d" }|lua}} resulta em {{Código|"acd"|lua}} e {{Código|sparseConcat{ nil, "b ", "c", "d" }|lua}} resulta em {{Código|"bcd"|lua}}.

==length==
<syntaxhighlight lang="lua">
TableTools.length(t, prefix)
</syntaxhighlight>
Esta função localiza o comprimento de um arranjo ou de um quasi-arranjo com chaves com um <code>''prefix''</code> opcional como "data1", "data2", etc. Ela usa um algoritmo de [[Busca exponencial|pesquisa exponencial]] para encontrar o comprimento, de modo a usar o mínimo possível de pesquisas de tabela.

Este algoritmo é útil para arranjos que usam metatabelas (por exemplo, [[mw:Extension:Scribunto/Lua reference manual/pt-br#frame.args|frame.args]]) e para quasi-arranjos. Para arranjos normais, basta usar o [[mw:Extension:Scribunto/Lua reference manual/pt-br#Length operator|operador #]], pois ele é implementado em [[C (linguagem de programação)|C]] e será mais rápido.

==inArray==
<syntaxhighlight lang="lua">TableTools.inArray(array, searchElement)
TableTools.inArray(array, searchElement, fromIndex)</syntaxhighlight>
Retorna <code>true</code> se <code>''searchElement''</code> for um membro do arranjo <code>''array''</code>, e <code>false</code> caso contrário. Equivalente à função ''javascript'' [https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/Array/includes Array.prototype.includes()], exceto que "fromIndex" é indexado em 1 em vez de indexado em zero.

===fromIndex===
<code>fromIndex</code> é o índice opcional de base 1 no qual iniciar a pesquisa. Se <code>fromIndex</code> não estiver presente, todos os valores no array serão pesquisados e o array será tratado como uma tabela/array associativo (será iterado usando <syntaxhighlight lang="lua" inline>pairs()</syntaxhighlight>).

Se <code>fromIndex</code> estiver presente e for um inteiro, o arranjo é assumido como um arranjo/sequência/lista convencional (indexado com chaves inteiras consecutivas começando em <code>1</code>, e interagindo usando <syntaxhighlight lang="lua" inline>ipairs()</syntaxhighlight>). Somente os valores cujo índice é <code>fromIndex</code> ou maior serão pesquisados.

Nos exemplos a seguir, <code>#array</code> representa o comprimento da parte com chave inteira do arranjo.
*Se <code>fromIndex < 0</code>, ele contará de volta do final do arranjo, por exemplo, um valor de <code>-1</code> pesquisará apenas o último elemento com chave de inteiro no arranjo. Se <code>fromIndex <= (-1 * #array)</code>, toda a porção com chave de inteiro do arranjo será pesquisada.
*Se <code>fromIndex = 0</code>, ele será tratado como <code>1</code> e toda a porção com chave de inteiro do arranjo será pesquisada.
*Se <code>fromIndex > #array</code>, o arranjo não será pesquisado e <code>false</code> será retornado.

==merge==
<syntaxhighlight lang="lua">
TableTools.merge(...)
</syntaxhighlight>
Dados os arranjos, retorna um arranjo contendo os elementos de cada arranjo de entrada em sequência.

==extend==
<syntaxhighlight lang="lua">
TableTools.extend(arr1, arr2)
</syntaxhighlight>
Estende o primeiro arrabjo no local anexando todos os elementos do segundo arranjo.

<includeonly>{{Testes outro||
[[Categoria:!Metamódulos Lua|TableTools]]
}}</includeonly>