tabletools
Documentation Attention: | Ne pas modifier. Cette page est maintenue par un bot. Toutes les modifications doivent être effectuées sur mediawiki.org. (traduisez cet avertissement) Merci de nous aider à traduire cette page. |
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
| Fonction | Utilisation |
|---|---|
isPositiveInteger(value) | Prend en argument un objet quelconque et retourne true s'il s'agit d'un nombre 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 »). |
isNan(value) | Prend en argument un objet quelconque et retourne true 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. |
length(t) | Retourne la longueur d'un tableau t, c.-à-d. la première clé telle que la suivante est associée à la valeur nil. Il s'agit de l'équivalent de l'opérateur # pour des tableaux chargés avec mw.loadData. |
size(t) | Retourne la taille d'un tableau t, c.-à-d. le nombre de paires clé / valeur qu'il contient. |
isArray(t) | Retourne true si le tableau t est un array (les clés sont 1, 2, 3,...) et false sinon. |
inArray(arr, valueToFind) | Retourne true si valueToFind est dans l'array arr et false sinon. |
keysToList(t, keySort, checked) | Prend en argument un tableau t et retourne la liste de ses clés, triées selon keySort avec keySort une fonction prenant deux arguments et retournant true si, dans l'ordre, le premier est avant le second. Par défaut, keySort est le tri selon le signe <. Si keySort vaut false, aucun tri n'est effectué. checked est un booléen à mettre à true pour passer les tests de type. |
numKeys(t) | Prend en argument un tableau t et retourne la liste des clés entières positives associées à une valeur non-vide. Exemple : Appliquée au tableau {'foo', nil, 'bar', a = 'b'}, numKeys retourne {1, 3}. |
affixNums(t, prefix, suffix) | Prend en argument un tableau t et retourne la liste des clés commençant par prefix et finissant par suffix. |
Fonctions créant un nouveau tableau
| Fonction | Utilisation |
|---|---|
shallowClone(t) | Retourne une copie du tableau t, mais partageant ses éventuels sous-tableaux et fonctions. (c.-à-d. que modifier un sous-tableau de la copie modifie également t) |
deepCopy(t, noMetatable, alreadySeen) | Retourne une copie du tableau t, qui, contrairement à shallowClone ne partage rien avec t. Cette fonction fait la même chose que mw.clone mais fonctionne également sur des tableaux chargés avec mw.loadData. Si noMetatable vaut true, les méta-tables ne sont pas copiées. alreadySeen est un paramètre interne utilisé dans les appels récursifs et ne devrait pas être affecté manuellement. |
removeDuplicates(t) | Prend en argument un array t et retourne le même array sans les doublons. Les clés de t qui ne sont pas des entiers positifs sont ignorées et la fonction s'arrête à la première valeur nil rencontrée. Pour ignorer les nil, il faut d'abord utiliser la fonction compressSparseArray. |
compressSparseArray(t) | Prend en argument un array t et retourne le même array sans les éventuels nil et clés non entières positives, en préservant l'ordre. Exemple : Appliquée au tableau {1, nil, foo = 'bar', 3, 'nil'}, compressSparseArray renvoie {1, 3, 'nil'}. |
listToSet(arr) | Prend en argument un array arr et retourne un set, c.-à-d. un tableau dont l'index vaut true s'il est dans la liste. Exemple : Appliquée au tableau { "a", "b", "c" }, listToSet renvoie { ["a"] = true, ["b"] = true, ["c"] = true }. |
invert(t) | Prend en argument un tableau t et renvoie une copie de t où les clés et les valeurs sont échangées. Exemple : Appliquée au tableau { "a", "b", "c" }, invert renvoie { a = 1, b = 2, c = 3 }. |
sparseConcat(t, sep, i, j) | Prend en argument un tableau t et retourne une chaîne de caractères concaténant toutes les valeurs associées aux clés entières positives entre i et j (par défaut, du début à la fin) séparées par sep. |
numData(t, compress) | Prend en argument un tableau t 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 {"foo1" = 'texta', "bar1" = 'textb', "foo2" = 'textc', "baz2" = 'textd'}, numData renvoie { [1] = {foo = 'texta', bar = 'textb'}, [2] = {foo = 'textc', baz = 'textd'} }. Si compress vaut true, la fonction compressSparseArray 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érateurs sur des tableaux. Les itérateurs natifs de lua sont ipairs et pairs.
| Fonction | Utilisation |
|---|---|
sparseIpairs(t) | Similaire à ipairs, mais continue d'itérer même après avoir rencontré une clé associée à la valeur nil. Comme ipairs, itère sur les clés entières positives et ignore les autres clés. |
sortedPairs(t, keySort) | Crée un itérateur sur le tableau t en triant les clés avec keysToList(t, keySort). |
Exemple d'utilisation d'un itérateur :
for i, v in TableTools.sparseIpairs(t) do -- bloc de code end Modules externes et autres éléments dont ce module a besoin pour fonctionner
mw.ustring.match– Cherche la première correspondance d'un motif dans une chaine de caractères ;
libraryUtil– 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 local TableTools = require('Module:TableTools'). Les fonctions sont ensuite utilisables sous le nom TableTools.nomFonction.
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 
La documentation de ce module est générée par le modèle {{Documentation module}}.
Elle est incluse depuis sa sous-page de documentation. Veuillez placer les catégories sur cette page-là.
Les éditeurs peuvent travailler dans le bac à sable (créer).
Voir les statistiques d'appel depuis le wikicode sur l'outil wstat et les appels depuis d'autres modules.
--[[ ------------------------------------------------------------------------------------ -- TableTools -- -- -- -- This module includes a number of functions for dealing with Lua tables. -- -- It is a meta-module, meant to be called from other Lua modules, and should -- -- not be called directly from #invoke. -- ------------------------------------------------------------------------------------ --]] local libraryUtil = require('libraryUtil') local p = {} -- Define often-used variables and functions. local floor = math.floor local infinity = math.huge local checkType = libraryUtil.checkType local checkTypeMulti = libraryUtil.checkTypeMulti --[[ ------------------------------------------------------------------------------------ -- isPositiveInteger -- -- This function returns true if the given value is a positive integer, and false -- if not. Although it doesn't operate on tables, it is included here as it is -- useful for determining whether a given table key is in the array part or the -- hash part of a table. ------------------------------------------------------------------------------------ --]] function p.isPositiveInteger(v) if type(v) == 'number' and v >= 1 and floor(v) == v and v < infinity then return true else return false end end --[[ ------------------------------------------------------------------------------------ -- isNan -- -- This function returns true if the given number is a NaN value, and false -- if not. Although it doesn't operate on tables, it is included here as it is -- useful for determining whether a value can be a valid table key. Lua will -- generate an error if a NaN is used as a table key. ------------------------------------------------------------------------------------ --]] function p.isNan(v) if type(v) == 'number' and tostring(v) == '-nan' then return true else return false end end --[[ ------------------------------------------------------------------------------------ -- shallowClone -- -- This returns a clone of a table. The value returned is a new table, but all -- subtables and functions are shared. Metamethods are respected, but the returned -- table will have no metatable of its own. ------------------------------------------------------------------------------------ --]] function p.shallowClone(t) local ret = {} for k, v in pairs(t) do ret[k] = v end return ret end --[[ ------------------------------------------------------------------------------------ -- removeDuplicates -- -- This removes duplicate values from an array. Non-positive-integer keys are -- ignored. The earliest value is kept, and all subsequent duplicate values are -- removed, but otherwise the array order is unchanged. ------------------------------------------------------------------------------------ --]] function p.removeDuplicates(t) checkType('removeDuplicates', 1, t, 'table') local isNan = p.isNan local ret, exists = {}, {} for i, v in ipairs(t) do if isNan(v) then -- NaNs can't be table keys, and they are also unique, so we don't need to check existence. ret[#ret + 1] = v else if not exists[v] then ret[#ret + 1] = v exists[v] = true end end end return ret end --[[ ------------------------------------------------------------------------------------ -- numKeys -- -- This takes a table and returns an array containing the numbers of any numerical -- keys that have non-nil values, sorted in numerical order. ------------------------------------------------------------------------------------ --]] function p.numKeys(t) checkType('numKeys', 1, t, 'table') local isPositiveInteger = p.isPositiveInteger local nums = {} for k, v in pairs(t) do if isPositiveInteger(k) then nums[#nums + 1] = k end end table.sort(nums) return nums end --[[ ------------------------------------------------------------------------------------ -- affixNums -- -- This takes a table and returns an array containing the numbers of keys with the -- specified prefix and suffix. For example, for the table -- {a1 = 'foo', a3 = 'bar', a6 = 'baz'} and the prefix "a", affixNums will -- return {1, 3, 6}. ------------------------------------------------------------------------------------ --]] function p.affixNums(t, prefix, suffix) checkType('affixNums', 1, t, 'table') checkType('affixNums', 2, prefix, 'string', true) checkType('affixNums', 3, suffix, 'string', true) local function cleanPattern(s) -- Cleans a pattern so that the magic characters ()%.[]*+-?^$ are interpreted literally. s = s:gsub('([%(%)%%%.%[%]%*%+%-%?%^%$])', '%%%1') return s end prefix = prefix or '' suffix = suffix or '' prefix = cleanPattern(prefix) suffix = cleanPattern(suffix) local pattern = '^' .. prefix .. '([1-9]%d*)' .. suffix .. '$' local nums = {} for k, v in pairs(t) do if type(k) == 'string' then local num = mw.ustring.match(k, pattern) if num then nums[#nums + 1] = tonumber(num) end end end table.sort(nums) return nums end --[[ ------------------------------------------------------------------------------------ -- numData -- -- Given a table with keys like ("foo1", "bar1", "foo2", "baz2"), returns a table -- of subtables in the format -- { [1] = {foo = 'text', bar = 'text'}, [2] = {foo = 'text', baz = 'text'} } -- Keys that don't end with an integer are stored in a subtable named "other". -- The compress option compresses the table so that it can be iterated over with -- ipairs. ------------------------------------------------------------------------------------ --]] function p.numData(t, compress) checkType('numData', 1, t, 'table') checkType('numData', 2, compress, 'boolean', true) local ret = {} for k, v in pairs(t) do local prefix, num = mw.ustring.match(tostring(k), '^([^0-9]*)([1-9][0-9]*)$') if num then num = tonumber(num) local subtable = ret[num] or {} if prefix == '' then -- Positional parameters match the blank string; put them at the start of the subtable instead. prefix = 1 end subtable[prefix] = v ret[num] = subtable else local subtable = ret.other or {} subtable[k] = v ret.other = subtable end end if compress then local other = ret.other ret = p.compressSparseArray(ret) ret.other = other end return ret end --[[ ------------------------------------------------------------------------------------ -- compressSparseArray -- -- This takes an array with one or more nil values, and removes the nil values -- while preserving the order, so that the array can be safely traversed with -- ipairs. ------------------------------------------------------------------------------------ --]] function p.compressSparseArray(t) checkType('compressSparseArray', 1, t, 'table') local ret = {} local nums = p.numKeys(t) for _, num in ipairs(nums) do ret[#ret + 1] = t[num] end return ret end --[[ ------------------------------------------------------------------------------------ -- sparseIpairs -- -- This is an iterator for sparse arrays. It can be used like ipairs, but can -- handle nil values. ------------------------------------------------------------------------------------ --]] function p.sparseIpairs(t) checkType('sparseIpairs', 1, t, 'table') local nums = p.numKeys(t) local i = 0 local lim = #nums return function () i = i + 1 if i <= lim then local key = nums[i] return key, t[key] else return nil, nil end end end --[[ ------------------------------------------------------------------------------------ -- size -- -- This returns the size of a key/value pair table. It will also work on arrays, -- but for arrays it is more efficient to use the # operator. ------------------------------------------------------------------------------------ --]] function p.size(t) checkType('size', 1, t, 'table') local i = 0 for k in pairs(t) do i = i + 1 end return i end local function defaultKeySort(item1, item2) -- "number" < "string", so numbers will be sorted before strings. local type1, type2 = type(item1), type(item2) if type1 ~= type2 then return type1 < type2 else -- This will fail with table, boolean, function. return item1 < item2 end end --[[ Returns a list of the keys in a table, sorted using either a default comparison function or a custom keySort function. ]] function p.keysToList(t, keySort, checked) if not checked then checkType('keysToList', 1, t, 'table') checkTypeMulti('keysToList', 2, keySort, { 'function', 'boolean', 'nil' }) end local list = {} local index = 1 for key, value in pairs(t) do list[index] = key index = index + 1 end if keySort ~= false then keySort = type(keySort) == 'function' and keySort or defaultKeySort table.sort(list, keySort) end return list end --[[ Iterates through a table, with the keys sorted using the keysToList function. If there are only numerical keys, sparseIpairs is probably more efficient. ]] function p.sortedPairs(t, keySort) checkType('sortedPairs', 1, t, 'table') checkType('sortedPairs', 2, keySort, 'function', true) local list = p.keysToList(t, keySort, true) local i = 0 return function() i = i + 1 local key = list[i] if key ~= nil then return key, t[key] else return nil, nil end end end --[[ Returns true if all keys in the table are consecutive integers starting at 1. --]] function p.isArray(t) checkType("isArray", 1, t, "table") local i = 0 for k, v in pairs(t) do i = i + 1 if t[i] == nil then return false end end return true end -- { "a", "b", "c" } -> { a = 1, b = 2, c = 3 } function p.invert(array) checkType("invert", 1, array, "table") local map = {} for i, v in ipairs(array) do map[v] = i end return map end --[[ { "a", "b", "c" } -> { ["a"] = true, ["b"] = true, ["c"] = true } --]] function p.listToSet(t) checkType("listToSet", 1, t, "table") local set = {} for _, item in ipairs(t) do set[item] = true end return set end --[[ Recursive deep copy function. Preserves identities of subtables. ]] local function _deepCopy(orig, includeMetatable, already_seen) -- Stores copies of tables indexed by the original table. already_seen = already_seen or {} local copy = already_seen[orig] if copy ~= nil then return copy end if type(orig) == 'table' then copy = {} for orig_key, orig_value in pairs(orig) do copy[deepcopy(orig_key, includeMetatable, already_seen)] = deepcopy(orig_value, includeMetatable, already_seen) end already_seen[orig] = copy if includeMetatable then local mt = getmetatable(orig) if mt ~= nil then local mt_copy = deepcopy(mt, includeMetatable, already_seen) setmetatable(copy, mt_copy) already_seen[mt] = mt_copy end end else -- number, string, boolean, etc copy = orig end return copy end function p.deepCopy(orig, noMetatable, already_seen) checkType("deepCopy", 3, already_seen, "table", true) return _deepCopy(orig, not noMetatable, already_seen) end --[[ Concatenates all values in the table that are indexed by a number, in order. sparseConcat{ a, nil, c, d } => "acd" sparseConcat{ nil, b, c, d } => "bcd" ]] function p.sparseConcat(t, sep, i, j) local list = {} local list_i = 0 for _, v in p.sparseIpairs(t) do list_i = list_i + 1 list[list_i] = v end return table.concat(list, sep, i, j) end --[[ -- This returns the length of a table, or the first integer key n counting from -- 1 such that t[n + 1] is nil. It is similar to the operator #, but may return -- a different value when there are gaps in the array portion of the table. -- Intended to be used on data loaded with mw.loadData. For other tables, use #. -- Note: #frame.args in frame object always be set to 0, regardless of -- the number of unnamed template parameters, so use this function for -- frame.args. --]] function p.length(t) local i = 1 while t[i] ~= nil do i = i + 1 end return i - 1 end function p.inArray(arr, valueToFind) checkType("inArray", 1, arr, "table") -- if valueToFind is nil, error? for _, v in ipairs(arr) do if v == valueToFind then return true end end return false end return p