Module:TableTools

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

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