Modul:TableTools

Dokumentacija za tutón modul hodźi so naModul:TableTools/Dokumentacijawutworić

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

locallibraryUtil=require('libraryUtil')

localp={}

-- Define often-used variables and functions.
localfloor=math.floor
localinfinity=math.huge
localcheckType=libraryUtil.checkType
localcheckTypeMulti=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.
------------------------------------------------------------------------------------
--]]
functionp.isPositiveInteger(v)
iftype(v)=='number'andv>=1andfloor(v)==vandv<infinitythen
returntrue
else
returnfalse
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.
------------------------------------------------------------------------------------
--]]
functionp.isNan(v)
iftype(v)=='number'andtostring(v)=='-nan'then
returntrue
else
returnfalse
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.
------------------------------------------------------------------------------------
--]]
functionp.shallowClone(t)
localret={}
fork,vinpairs(t)do
ret[k]=v
end
returnret
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.
------------------------------------------------------------------------------------
--]]
functionp.removeDuplicates(t)
checkType('removeDuplicates',1,t,'table')
localisNan=p.isNan
localret,exists={},{}
fori,vinipairs(t)do
ifisNan(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
ifnotexists[v]then
ret[#ret+1]=v
exists[v]=true
end
end
end
returnret
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.
------------------------------------------------------------------------------------
--]]
functionp.numKeys(t)
checkType('numKeys',1,t,'table')
localisPositiveInteger=p.isPositiveInteger
localnums={}
fork,vinpairs(t)do
ifisPositiveInteger(k)then
nums[#nums+1]=k
end
end
table.sort(nums)
returnnums
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}.
------------------------------------------------------------------------------------
--]]
functionp.affixNums(t,prefix,suffix)
checkType('affixNums',1,t,'table')
checkType('affixNums',2,prefix,'string',true)
checkType('affixNums',3,suffix,'string',true)

localfunctioncleanPattern(s)
-- Cleans a pattern so that the magic characters ()%.[]*+-?^$ are interpreted literally.
s=s:gsub('([%(%)%%%.%[%]%*%+%-%?%^%$])','%%%1')
returns
end

prefix=prefixor''
suffix=suffixor''
prefix=cleanPattern(prefix)
suffix=cleanPattern(suffix)
localpattern='^'..prefix..'([1-9]%d*)'..suffix..'$'

localnums={}
fork,vinpairs(t)do
iftype(k)=='string'then
localnum=mw.ustring.match(k,pattern)
ifnumthen
nums[#nums+1]=tonumber(num)
end
end
end
table.sort(nums)
returnnums
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.
------------------------------------------------------------------------------------
--]]
functionp.numData(t,compress)
checkType('numData',1,t,'table')
checkType('numData',2,compress,'boolean',true)
localret={}
fork,vinpairs(t)do
localprefix,num=mw.ustring.match(tostring(k),'^([^0-9]*)([1-9][0-9]*)$')
ifnumthen
num=tonumber(num)
localsubtable=ret[num]or{}
ifprefix==''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
localsubtable=ret.otheror{}
subtable[k]=v
ret.other=subtable
end
end
ifcompressthen
localother=ret.other
ret=p.compressSparseArray(ret)
ret.other=other
end
returnret
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.
------------------------------------------------------------------------------------
--]]
functionp.compressSparseArray(t)
checkType('compressSparseArray',1,t,'table')
localret={}
localnums=p.numKeys(t)
for_,numinipairs(nums)do
ret[#ret+1]=t[num]
end
returnret
end

--[[
------------------------------------------------------------------------------------
-- sparseIpairs
--
-- This is an iterator for sparse arrays. It can be used like ipairs, but can
-- handle nil values.
------------------------------------------------------------------------------------
--]]
functionp.sparseIpairs(t)
checkType('sparseIpairs',1,t,'table')
localnums=p.numKeys(t)
locali=0
locallim=#nums
returnfunction()
i=i+1
ifi<=limthen
localkey=nums[i]
returnkey,t[key]
else
returnnil,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.
------------------------------------------------------------------------------------
--]]

functionp.size(t)
checkType('size',1,t,'table')
locali=0
forkinpairs(t)do
i=i+1
end
returni
end


localfunctiondefaultKeySort(item1,item2)
-- "number" < "string", so numbers will be sorted before strings.
localtype1,type2=type(item1),type(item2)
iftype1~=type2then
returntype1<type2
else-- This will fail with table, boolean, function.
returnitem1<item2
end
end

--[[
Returns a list of the keys in a table, sorted using either a default
comparison function or a custom keySort function.
]]
functionp.keysToList(t,keySort,checked)
ifnotcheckedthen
checkType('keysToList',1,t,'table')
checkTypeMulti('keysToList',2,keySort,{'function','boolean','nil'})
end

locallist={}
localindex=1
forkey,valueinpairs(t)do
list[index]=key
index=index+1
end

ifkeySort~=falsethen
keySort=type(keySort)=='function'andkeySortordefaultKeySort

table.sort(list,keySort)
end

returnlist
end

--[[
Iterates through a table, with the keys sorted using the keysToList function.
If there are only numerical keys, sparseIpairs is probably more efficient.
]]
functionp.sortedPairs(t,keySort)
checkType('sortedPairs',1,t,'table')
checkType('sortedPairs',2,keySort,'function',true)

locallist=p.keysToList(t,keySort,true)

locali=0
returnfunction()
i=i+1
localkey=list[i]
ifkey~=nilthen
returnkey,t[key]
else
returnnil,nil
end
end
end

--[[
Returns true if all keys in the table are consecutive integers starting at 1.
--]]
functionp.isArray(t)
checkType("isArray",1,t,"table")

locali=0
fork,vinpairs(t)do
i=i+1
ift[i]==nilthen
returnfalse
end
end
returntrue
end

-- { "a", "b", "c" } -> { a = 1, b = 2, c = 3 }
functionp.invert(array)
checkType("invert",1,array,"table")

localmap={}
fori,vinipairs(array)do
map[v]=i
end

returnmap
end

--[[
{ "a", "b", "c" } -> { [ "a" ] = true, [ "b" ] = true, [ "c" ] = true }
--]]
functionp.listToSet(t)
checkType("listToSet",1,t,"table")

localset={}
for_,iteminipairs(t)do
set[item]=true
end

returnset
end

--[[
Recursive deep copy function.
Preserves identities of subtables.

]]
localfunction_deepCopy(orig,includeMetatable,already_seen)
-- Stores copies of tables indexed by the original table.
already_seen=already_seenor{}

localcopy=already_seen[orig]
ifcopy~=nilthen
returncopy
end

iftype(orig)=='table'then
copy={}
fororig_key,orig_valueinpairs(orig)do
copy[deepcopy(orig_key,includeMetatable,already_seen)]=deepcopy(orig_value,includeMetatable,already_seen)
end
already_seen[orig]=copy

ifincludeMetatablethen
localmt=getmetatable(orig)
ifmt~=nilthen
localmt_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
returncopy
end

functionp.deepCopy(orig,noMetatable,already_seen)
checkType("deepCopy",3,already_seen,"table",true)

return_deepCopy(orig,notnoMetatable,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"
]]
functionp.sparseConcat(t,sep,i,j)
locallist={}

locallist_i=0
for_,vinp.sparseIpairs(t)do
list_i=list_i+1
list[list_i]=v
end

returntable.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.
--]]
functionp.length(t)
locali=1
whilet[i]~=nildo
i=i+1
end
returni-1
end

functionp.inArray(arr,valueToFind)
checkType("inArray",1,arr,"table")

-- if valueToFind is nil, error?

for_,vinipairs(arr)do
ifv==valueToFindthen
returntrue
end
end

returnfalse
end

returnp