Module:TableTools/Documentation

La documentation pour ce module peut être créée à Module:TableTools/Documentation/doc

Erreur de script : Erreur Lua à la ligne 1 : unexpected symbol near '<'.

<includeonly>{{Shared Template Warning|Module:TableTools|Module:TableTools}}</includeonly>
== Utilisation ==
Ce module fournit diverses fonction pratiques pour les tableaux lua. Il est prévu pour un usage par d'autres modules et non pour une invocation directe dans un modèle.

=== Fonctions exportables ===
==== Fonctions d'analyse du contenu / des propriétés du tableau ====
{| class="wikitable
! scope="col" | Fonction !! scope="col" | Utilisation
|-
| <code>[[Module:TableTools#L-31|isPositiveInteger(value)]]</code> || Prend en argument un objet quelconque et retourne <syntaxhighlight lang="lua" inline>true</syntaxhighlight> s'il s'agit d'un '''nombre [[Entier naturel|entier positif]]'''. Cette fonction s'applique à une valeur seule et non à un tableau. Elle est utile pour déterminer si une clé correspond à une clé d'un array ({{c.-à-d.}} clé entier positif) ou à une clé de [[table de hachage]] ({{c.-à-d.}} clé « quelconque »).
|-
| <code>[[Module:TableTools#L-49|isNan(value)]]</code> || Prend en argument un '''objet quelconque''' et retourne <syntaxhighlight lang="lua" inline>true</syntaxhighlight> s'il s'agit de '''[[NaN]]''' (correspond généralement à un résultat d'opération mathématique non défini, comme 0/0). Cette fonction permet de déterminer si un objet est une clé de tableau valide.
|-
| <code>[[Module:TableTools#L-432|length(t)]]</code> || Retourne la '''longueur''' d'un tableau <code>t</code>, {{c.-à-d.}} la première clé telle que la suivante est associée à la valeur <syntaxhighlight lang="lua" inline>nil</syntaxhighlight>. Il s'agit de l'équivalent de l'opérateur # pour des tableaux chargés avec <code>mw.loadData</code>.
|-
| <code>[[Module:TableTools#L-255|size(t)]]</code> || Retourne la '''taille''' d'un tableau <code>t</code>, {{c.-à-d.}} le nombre de paires clé / valeur qu'il contient.
|-
| <code>[[Module:TableTools#L-326|isArray(t)]]</code> || Retourne <syntaxhighlight lang="lua" inline>true</syntaxhighlight> si le tableau <code>t</code> est un '''array''' (les clés sont 1, 2, 3,...) et <syntaxhighlight lang="lua" inline>false</syntaxhighlight> sinon.
|-
| <code>[[Module:TableTools#L-440|inArray(arr, valueToFind)]]</code> || Retourne <syntaxhighlight lang="lua" inline>true</syntaxhighlight> si <code>valueToFind</code> est '''dans l'array''' <code>arr</code> et <syntaxhighlight lang="lua" inline>false</syntaxhighlight> sinon.
|-
| <code>[[Module:TableTools#L-279|keysToList(t, keySort, checked)]]</code> || Prend en argument un tableau <code>t</code> et retourne la '''liste de ses clés''', triées selon <code>keySort</code> avec keySort une fonction prenant deux arguments et retournant <syntaxhighlight lang="lua" inline>true</syntaxhighlight> si, dans l'ordre, le premier est avant le second. Par défaut, <code>keySort</code> est le tri selon le signe <code><</code>. Si keySort vaut <syntaxhighlight lang="lua" inline>false</syntaxhighlight>, aucun tri n'est effectué. <code>checked</code> est un booléen à mettre à <syntaxhighlight lang="lua" inline>true</syntaxhighlight> pour passer les tests de type.
|-
| <code>[[Module:TableTools#L-109|numKeys(t)]]</code> || Prend en argument un tableau <code>t</code> et retourne la liste des '''clés entières positives''' associées à une valeur non-vide. Exemple : Appliquée au tableau <syntaxhighlight lang="lua" inline>{'foo', nil, 'bar', a = 'b'}</syntaxhighlight>, numKeys retourne <syntaxhighlight lang="lua" inline>{1, 3}</syntaxhighlight>.
|-
| <code>[[Module:TableTools#L-132|affixNums(t, prefix, suffix)]]</code> || Prend en argument un tableau <code>t</code> et retourne la liste des clés '''commençant''' par <code>prefix</code> et '''finissant''' par <code>suffix</code>.
|}

==== Fonctions créant un nouveau tableau ====
{| class="wikitable
! scope="col" | Fonction !! scope="col" | Utilisation
|-
| <code>[[Module:TableTools#L-66|shallowClone(t)]]</code> || Retourne une '''copie''' du tableau <code>t</code>, mais partageant ses éventuels sous-tableaux et fonctions. ({{c.-à-d.}} que modifier un sous-tableau de la copie modifie également t)
|-
| <code>[[Module:TableTools#L-400|deepCopy(t, noMetatable, alreadySeen)]]</code> || Retourne une '''copie''' du tableau <code>t</code>, qui, contrairement à <code>shallowClone</code> ne partage rien avec <code>t</code>. Cette fonction fait la même chose que <code>[[mw:Extension:Scribunto/Lua reference manual/fr#mw.clone|mw.clone]]</code> mais fonctionne également sur des tableaux chargés avec <code>mw.loadData</code>. Si <code>noMetatable</code> vaut <syntaxhighlight lang="lua" inline>true</syntaxhighlight>, les [[mw:Extension:Scribunto/Lua reference manual/fr#Méta-tables|méta-tables]] ne sont pas copiées. <code>alreadySeen</code> est un paramètre interne utilisé dans les appels [[Algorithme récursif|récursifs]] et ne devrait pas être affecté manuellement.
|-
| <code>[[Module:TableTools#L-83|removeDuplicates(t)]]</code> || Prend en argument un array <code>t</code> et retourne le même array sans les '''doublons'''. Les clés de <code>t</code> qui ne sont pas des entiers positifs sont ignorées et la fonction s'arrête à la première valeur <syntaxhighlight lang="lua" inline>nil</syntaxhighlight> rencontrée. Pour ignorer les <syntaxhighlight lang="lua" inline>nil</syntaxhighlight>, il faut d'abord utiliser la fonction <code>compressSparseArray</code>.
|-
| <code>[[Module:TableTools#L-212|compressSparseArray(t)]]</code> || Prend en argument un array <code>t</code> et retourne le même array sans les éventuels <syntaxhighlight lang="lua" inline>nil</syntaxhighlight> et clés non entières positives, en préservant l'ordre. Exemple : Appliquée au tableau <syntaxhighlight lang="lua" inline>{1, nil, foo = 'bar', 3, 'nil'}</syntaxhighlight>, compressSparseArray renvoie <syntaxhighlight lang="lua" inline>{1, 3, 'nil'}</syntaxhighlight>.
|-
| <code>[[Module:TableTools#L-354|listToSet(arr)]]</code> || Prend en argument un array <code>arr</code> et retourne un '''set''', {{c.-à-d.}} un tableau dont l'index vaut <syntaxhighlight lang="lua" inline>true</syntaxhighlight> s'il est dans la liste. Exemple : Appliquée au tableau <syntaxhighlight lang="lua" inline>{ "a", "b", "c" }</syntaxhighlight>, listToSet renvoie <syntaxhighlight lang="lua" inline>{ ["a"] = true, ["b"] = true, ["c"] = true }</syntaxhighlight>.
|-
| <code>[[Module:TableTools#L-340|invert(t)]]</code> || Prend en argument un tableau <code>t</code> et renvoie une copie de t où '''les clés et les valeurs sont échangées'''. Exemple : Appliquée au tableau <syntaxhighlight lang="lua" inline>{ "a", "b", "c" }</syntaxhighlight>, invert renvoie <syntaxhighlight lang="lua" inline>{ a = 1, b = 2, c = 3 }</syntaxhighlight>.
|-
| <code>[[Module:TableTools#L-411|sparseConcat(t, sep, i, j)]]</code> || Prend en argument un tableau <code>t</code> et retourne une chaîne de caractères '''[[Concaténation|concaténant]]''' toutes les valeurs associées aux clés entières positives entre <code>i</code> et <code>j</code> (par défaut, du début à la fin) séparées par <code>sep</code>.
|-
| <code>[[Module:TableTools#L-174|numData(t, compress)]]</code> || Prend en argument un tableau <code>t</code> dont toutes les clés finissent par des nombres et retourne un tableau de sous-tableau trié par ces nombres. Exemple : Appliquée au tableau <syntaxhighlight lang="lua" inline>{"foo1" = 'texta', "bar1" = 'textb', "foo2" = 'textc', "baz2" = 'textd'}</syntaxhighlight>, numData renvoie <syntaxhighlight lang="lua" inline>{ [1] = {foo = 'texta', bar = 'textb'}, [2] = {foo = 'textc', baz = 'textd'} }</syntaxhighlight>. Si <code>compress</code> vaut <syntaxhighlight lang="lua" inline>true</syntaxhighlight>, la fonction <code>compressSparseArray</code> est appliquée au résultat, permettant une itération sur le tableau avec ipairs.
|}

==== Itérateurs sur un tableau ====
Ce module fournit deux [[itérateur]]s sur des tableaux. Les itérateurs natifs de lua sont <code>[[mw:Extension:Scribunto/Lua reference manual/fr#ipairs|ipairs]]</code> et <code>[[mw:Extension:Scribunto/Lua reference manual/fr#pairs|pairs]]</code>.
{| class="wikitable
! scope="col" | Fonction !! scope="col" | Utilisation
|-
| <code>[[Module:TableTools#L-230|sparseIpairs(t)]]</code> || Similaire à <code>ipairs</code>, mais continue d'itérer même après avoir rencontré une clé associée à la valeur <syntaxhighlight lang="lua" inline>nil</syntaxhighlight>. Comme ipairs, itère sur les clés entières positives et ignore les autres clés.
|-
| <code>[[Module:TableTools#L-305|sortedPairs(t, keySort)]]</code> || Crée un itérateur sur le tableau <code>t</code> en triant les clés avec <code>keysToList(t, keySort)</code>.
|}

Exemple d'utilisation d'un itérateur :
<syntaxhighlight lang="lua">
for i, v in TableTools.sparseIpairs(t) do
   -- bloc de code
end
</syntaxhighlight>

=== Modules externes et autres éléments dont ce module a besoin pour fonctionner ===
* <code>[[mw:Extension:Scribunto/Lua reference manual/fr#mw.ustring.match|mw.ustring.match]]</code> – Cherche la première correspondance d'un motif dans une chaine de caractères ;

* <code>[[mw:Extension:Scribunto/Lua reference manual/fr#Bibliothèque libraryUtil|libraryUtil]]</code> – Bibliothèque de fonctions pour retourner une erreur lorsque le type d'un objet n'est pas celui attendu.

== Exemple ==
Pour utiliser les fonctions de ce module, celui-ci doit être importé avec <syntaxhighlight lang="lua" inline>local TableTools = require('Module:TableTools')</syntaxhighlight>. Les fonctions sont ensuite utilisables sous le nom <code>TableTools.nomFonction</code>.
<syntaxhighlight lang="lua">
local TableTools = require('Module:TableTools')

local p={}

function p.main(tableau)
    if TableTools.isArray(tableau) then
        return "Le tableau est un array."
    else
        return "Le tableau n'est pas un array."
    end
end

return p
</syntaxhighlight>

{{Projet Scribunto}}

<includeonly>
[[Catégorie:Méta-module]]
[[Catégorie:Module appelé par un autre module]]
</includeonly>