Module:TableTools

 Documentation[voir] [modifier] [historique] [purger]

Ne pas modifier. Cette page est maintenue par un outil externe. Toutes les modifications doivent être effectuées sur mediawiki.org.

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

--[[
------------------------------------------------------------------------------------
-- 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

return p