Bibliothèque table

La bibliothèque table fournit les opérations courantes sur les tables utilisées comme « séquences » (tableaux indexés 1..n sans trou) : insertion, suppression, tri, concaténation, empaquetage des arguments variadiques, fusion.

La plupart des fonctions acceptent, à la place d'une vraie table, n'importe quelle valeur dotée d'une métatable fournissant les métaméthodes nécessaires (__index/__newindex/__len selon l'opération), pour permettre d'utiliser ces fonctions sur des objets qui « se comportent » comme des tables.

Vue d'ensemble

table.concat(list [, sep [, i [, j]]])

Étant donné une liste dont tous les éléments concernés sont des chaînes ou des nombres, retourne la chaîne list[i]..sep..list[i+1]..· · ·..sep..list[j]. sep vaut la chaîne vide par défaut, i vaut 1 et j vaut #list. Si i > j, retourne la chaîne vide. Lève une erreur si un élément de la plage n'est pas une chaîne (ou un nombre convertible).

print(table.concat({ "a", "b", "c" }, ", "))   --> a, b, c

table.insert(list, [pos,] value)

Insère value à la position pos de list, décalant vers le haut les éléments list[pos], list[pos+1], ···, list[#list]. Sans pos, insère value en fin de liste (équivalent à pos = #list + 1). Lève une erreur si pos est hors de [1, #list + 1], ou si le nombre d'arguments n'est ni 2 ni 3.

local t = { "a", "b", "c" }
table.insert(t, "d")        -- { "a", "b", "c", "d" }
table.insert(t, 1, "z")     -- { "z", "a", "b", "c", "d" }

table.remove(list [, pos])

Retire de list l'élément à la position pos, et le retourne. Quand pos est compris entre 1 et #list, décale vers le bas les éléments list[pos+1], ···, list[#list]. pos peut aussi valoir 0 quand #list vaut 0, ou #list + 1 (retrait « au-delà de la fin », sans effet de décalage). Par défaut, pos vaut #list (retire le dernier élément). Lève une erreur si pos est hors de [1, #list + 1] (en tenant compte du cas 0).

local t = { "a", "b", "c" }
print(table.remove(t))       --> c      (t == { "a", "b" })
print(table.remove(t, 1))    --> a      (t == { "b" })

table.sort(list [, comp])

Trie les éléments de list, en place, de list[1] à list[#list]. comp, si fourni, est une fonction de comparaison recevant deux éléments et retournant vrai si le premier doit précéder le second dans l'ordre final ; sans comp, c'est l'opérateur < qui est utilisé. Le résultat n'est garanti que si comp définit un ordre strict et cohérent (comme un opérateur < classique).

local t = { 5, 3, 1, 4, 2 }
table.sort(t)
table.sort(t, function(a, b) return a > b end)   -- ordre décroissant

table.pack(···)

Retourne une nouvelle table contenant tous les arguments reçus, rangés aux clés 1, 2, ···, avec en plus un champ n donnant le nombre total d'arguments. Comme certains arguments peuvent être nil, la table résultante n'est pas nécessairement une séquence sans trou — utiliser le champ n plutôt que # pour connaître le nombre réel d'éléments empaquetés.

local t = table.pack(1, nil, 3)
print(t.n, t[1], t[2], t[3])   --> 3   1   nil   3

table.unpack(list [, i [, j]])

Retourne les éléments de list comme autant de valeurs de retour : équivalent à return list[i], list[i+1], ···, list[j]. i vaut 1 par défaut, j vaut #list par défaut. Ne retourne aucune valeur si i > j.

local function f(...) return ... end
print(f(table.unpack({ 1, 2, 3 })))   --> 1   2   3

table.move(a1, f, e, t [, a2])

Déplace les éléments de la table a1 vers la table a2, équivalent à l'affectation multiple a2[t], ··· = a1[f], ···, a1[e]. a2 vaut a1 par défaut, ce qui permet aussi bien de déplacer des éléments à l'intérieur d'une même table que de les copier vers une autre — les plages source et destination peuvent se chevaucher (le déplacement est fait dans le bon ordre pour éviter d'écraser des valeurs pas encore lues). Retourne a2.

local t = { 1, 2, 3, 4, 5 }
table.move(t, 1, 3, 3)   -- décale les 3 premiers éléments vers la position 3
-- t == { 1, 2, 1, 2, 3 }

table.merge([deep,] t1, t2, ···)

Fusionne toutes les paires clé/valeur de t2, ··· dans t1, et retourne t1. Une clé déjà présente dans t1 est écrasée par la dernière table source qui la définit. Si le premier argument deep (booléen, optionnel) vaut true, une valeur qui est une table à la fois dans la destination et dans la table source est fusionnée récursivement au lieu d'être simplement écrasée (les autres valeurs sont toujours remplacées).

local defaults = { a = 1, b = { x = 1, y = 2 } }
local overrides = { b = { y = 20, z = 3 }, c = 4 }
table.merge(true, defaults, overrides)
-- defaults == { a = 1, b = { x = 1, y = 20, z = 3 }, c = 4 }