Module:table: Difference between revisions

From Linguifex
Jump to navigation Jump to search
No edit summary
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 15: Line 15:
]]
]]


local libraryUtil = require('libraryUtil')
local export = {}


local export = {}
local libraryUtil = require("libraryUtil")
local table = table


-- Define often-used variables and functions.
local floor = math.floor
local infinity = math.huge
local checkType = libraryUtil.checkType
local checkType = libraryUtil.checkType
local checkTypeMulti = libraryUtil.checkTypeMulti
local checkTypeMulti = libraryUtil.checkTypeMulti
local concat = table.concat
local format = string.format
local getmetatable = getmetatable
local insert = table.insert
local ipairs = ipairs
local is_callable = require("Module:fun").is_callable
local is_positive_integer -- defined as export.isPositiveInteger below
local keys_to_list -- defined as export.keysToList below
local next = next
local pairs = pairs
local rawequal = rawequal
local rawget = rawget
local setmetatable = setmetatable
local sort = table.sort
local string_sort = require("Module:collation").string_sort
local type = type
local infinity = math.huge


local function _check(funcName, expectType)
local function _check(funcName, expectType)
Line 33: Line 49:
return function(argIndex, arg, expectType, nilOk)
return function(argIndex, arg, expectType, nilOk)
if type(expectType) == "table" then
if type(expectType) == "table" then
checkTypeMulti(funcName, argIndex, arg, expectType, nilOk)
if not nilOk or arg ~= nil then
-- checkTypeMulti() doesn't accept a fifth `nilOk` argument, unlike the other check functions.
checkTypeMulti(funcName, argIndex, arg, expectType)
end
else
else
checkType(funcName, argIndex, arg, expectType, nilOk)
checkType(funcName, argIndex, arg, expectType, nilOk)
Line 41: Line 60:
end
end


--[[
--[==[
------------------------------------------------------------------------------------
Return true if the given value is a positive integer, and false if not. Although it doesn't operate on tables, it is
-- isPositiveInteger
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.
-- 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 export.isPositiveInteger(v)
function export.isPositiveInteger(v)
return type(v) == 'number' and v >= 1 and floor(v) == v and v < infinity
return type(v) == "number" and v >= 1 and v % 1 == 0 and v < infinity
end
end
is_positive_integer = export.isPositiveInteger


--[[
--[==[
------------------------------------------------------------------------------------
Return a clone of an object. If the object is 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.
-- isNan
]==]
--
function export.shallowcopy(orig)
-- This function returns true if the given number is a NaN value, and false
if type(orig) ~= "table" then
-- if not. Although it doesn't operate on tables, it is included here as it is
return orig
-- useful for determining whether a value can be a valid table key. Lua will
end
-- generate an error if a NaN is used as a table key.
local copy = {}
------------------------------------------------------------------------------------
for k, v in pairs(orig) do
--]]
copy[k] = v
function export.isNan(v)
if type(v) == 'number' and tostring(v) == '-nan' then
return true
else
return false
end
end
return copy
end
end


--[[
do
------------------------------------------------------------------------------------
local function rawpairs(t)
-- shallowClone
return next, t
--
-- 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 export.shallowClone(t)
local ret = {}
for k, v in pairs(t) do
ret[k] = v
end
end
return ret
end


--[[
local function make_copy(orig, memo, mt_flag, keep_loaded_data)
Shallow copy
if type(orig) ~= "table" then
]]
return orig
function export.shallowcopy(orig)
end
local orig_type = type(orig)
local memoized = memo[orig]
local copy
if memoized ~= nil then
if orig_type == 'table' then
return memoized
copy = {}
end
for orig_key, orig_value in pairs(orig) do
local mt = getmetatable(orig)
copy[orig_key] = orig_value
local loaded_data = mt and mt.mw_loadData
if loaded_data and keep_loaded_data then
memo[orig] = orig
return orig
end
local copy = {}
memo[orig] = copy
for k, v in (loaded_data and pairs or rawpairs)(orig) do
copy[make_copy(k, memo, mt_flag, keep_loaded_data)] = make_copy(v, memo, mt_flag, keep_loaded_data)
end
if loaded_data then
return copy
elseif mt_flag == "keep" then
setmetatable(copy, mt)
elseif mt_flag ~= "none" then
setmetatable(copy, make_copy(mt, memo, mt_flag, keep_loaded_data))
end
end
else -- number, string, boolean, etc
return copy
copy = orig
end
 
--[==[
Recursive deep copy function. Preserves copied identities of subtables.
A more powerful version of {mw.clone}, with customizable options.
* By default, metatables are copied, except for data loaded via mw.loadData (see below). If `metatableFlag` is set to "none", the copy will not have any metatables at all. Conversely, if `metatableFlag` is set to "keep", then the cloned table (and all its members) will have the exact same metatable as their original version.
* If `keepLoadedData` is true, then any data loaded via {mw.loadData} will not be copied, and the original will be used instead. This is useful in iterative contexts where it is necessary to copy data being destructively modified, because objects loaded via mw.loadData are immutable.
* Notes:
*# Protected metatables will not be copied (i.e. those hidden behind a __metatable metamethod), as they are not
  accessible by Lua's design. Instead, the output of the __metatable method will be used instead.
*# When iterating over the table, the __pairs metamethod is ignored, since this can prevent the table from being properly cloned.
*# Data loaded via mw.loadData is a special case in two ways: the metatable is stripped, because otherwise the cloned table throws errors when accessed; in addition, the __pairs metamethod is used, since otherwise the cloned table would be empty.]==]
function export.deepcopy(orig, metatableFlag, keepLoadedData)
return make_copy(orig, {}, metatableFlag, keepLoadedData)
end
end
return copy
end
end


--[[
--[==[
Recursive deep copy function
Append any number of tables together and returns the result. Compare the Lisp expression {(append list1 list2 ...)}.
Equivalent to mw.clone?
]==]
]]
function export.append(...)
local function deepcopy(orig, includeMetatable, already_seen)
local ret, n = {}, 0
-- Stores copies of tables indexed by the original table.
for i = 1, arg.n do
already_seen = already_seen or {}
for _, v in ipairs(arg[i]) do
n = n + 1
local copy = already_seen[orig]
ret[n] = v
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
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)
end
end
else -- number, string, boolean, etc
copy = orig
end
end
return copy
return ret
end
end


function export.deepcopy(orig, noMetatable, already_seen)
--[==[
checkType("deepcopy", 3, already_seen, "table", true)
Extend an existing list by a new list, modifying the existing list in-place. Compare the Python expression
{list.extend(new_items)}.
return deepcopy(orig, not noMetatable, already_seen)
end


--[[
`options` is an optional table of additional options to control the behavior of the operation. The following options are
------------------------------------------------------------------------------------
recognized:
-- append
* `insertIfNot`: Use {export.insertIfNot()} instead of {table.insert()}, which ensures that duplicate items do not get
--
  inserted (at the cost of an O((M+N)*N) operation, where M = #list and N = #new_items).
-- This appends two tables together and returns the result. Compare the Lisp
* `key`: As in {insertIfNot()}. Ignored otherwise.
-- expression (append list1 list2).
* `pos`: As in {insertIfNot()}. Ignored otherwise.
------------------------------------------------------------------------------------
]==]
--]]
function export.extendList(list, new_items, options)
function export.append(t1, t2)
local check = _check("extendList", "table")
checkType('append', 1, t1, 'table')
check(1, list)
checkType('append', 2, t2, 'table')
check(2, new_items)
local ret = {}
check(3, options, true)
for _, v in ipairs(t1) do
for _, item in ipairs(new_items) do
table.insert(ret, v)
if options and options.insertIfNot then
end
export.insertIfNot(list, item, options)
for _, v in ipairs(t2) do
else
table.insert(ret, v)
insert(list, item)
end
end
end
return ret
end
end


--[[
--[==[
------------------------------------------------------------------------------------
Remove 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.
-- removeDuplicates
-- -0, NaN and -NaN have special handling, as they can't be used as table keys.
--
]==]
-- 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 export.removeDuplicates(t)
function export.removeDuplicates(t)
checkType('removeDuplicates', 1, t, 'table')
checkType("removeDuplicates", 1, t, "table")
local isNan = export.isNan
local ret, n, seen, _neg_0, _pos_nan, _neg_nan = {}, 0, {}
local ret, exists = {}, {}
local index = 1
for _, v in ipairs(t) do
for _, v in ipairs(t) do
if isNan(v) then
local v_key = v
-- NaNs can't be table keys, and they are also unique, so we don't need to check existence.
-- -0
ret[index] = v
if v == 0 and 1 / v < 0 then
index = index + 1
_neg_0 = _neg_0 or {}
else
v_key = _neg_0
if not exists[v] then
-- NaN and -NaN.
ret[index] = v
elseif v ~= v then
index = index + 1
if format("%f", v) == "nan" then
exists[v] = true
_pos_nan = _pos_nan or {}
v_key = _pos_nan
else
_neg_nan = _neg_nan or {}
v_key = _neg_nan
end
end
end
if not seen[v_key] then
n = n + 1
ret[n] = v
seen[v_key] = true
end
end
end
end
Line 197: Line 204:
end
end


--[[
--[==[
------------------------------------------------------------------------------------
Given a table, return an array containing the numbers of any numerical keys that have non-nil values, sorted in
-- numKeys
numerical order.
--
]==]
-- 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 export.numKeys(t, checked)
function export.numKeys(t, checked)
if not checked then
if not checked then
checkType('numKeys', 1, t, 'table')
checkType("numKeys", 1, t, "table")
end
end
local isPositiveInteger = export.isPositiveInteger
local nums = {}
local nums = {}
local index = 1
local index = 1
for k, _ in pairs(t) do
for k in pairs(t) do
if isPositiveInteger(k) then
if is_positive_integer(k) then
nums[index] = k
nums[index] = k
index = index + 1
index = index + 1
end
end
end
end
table.sort(nums)
sort(nums)
return nums
return nums
end
end


--[==[
Return the maximum index of a table or array that possibly has holes in it, or 0 if there are no numerical keys in the
table.
]==]
function export.maxIndex(t)
function export.maxIndex(t)
checkType('maxIndex', 1, t, 'table')
local max = 0
local positiveIntegerKeys = export.numKeys(t)
for k in pairs(t) do
if positiveIntegerKeys[1] then
if is_positive_integer(k) and k > max then
return math.max(unpack(positiveIntegerKeys))
max = k
else
return 0 -- ???
end
end
 
--[[
------------------------------------------------------------------------------------
-- affixNums
--
-- This takes a table and returns an array containing the numbers of keys with the
-- specified prefix and suffix.
-- affixNums({a1 = 'foo', a3 = 'bar', a6 = 'baz'}, "a")
-- ↓
-- {1, 3, 6}.
------------------------------------------------------------------------------------
--]]
function export.affixNums(t, prefix, suffix)
local check = _check('affixNums')
check(1, t, 'table')
check(2, prefix, 'string', true)
check(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 = {}
local index = 1
for k, _ in pairs(t) do
if type(k) == 'string' then
local num = mw.ustring.match(k, pattern)
if num then
nums[index] = tonumber(num)
index = index + 1
end
end
end
end
end
table.sort(nums)
return max
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 export.numData(t, compress)
local check = _check('numData')
check(1, t, 'table')
check(2, compress, 'boolean', true)
local ret = {}
for k, v in pairs(t) do
local prefix, num = tostring(k):match('^([^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 = export.compressSparseArray(ret)
ret.other = other
end
return ret
end
end


--[[
--[==[
------------------------------------------------------------------------------------
This takes an array with one or more nil values, and removes the nil values
-- compressSparseArray
while preserving the order, so that the array can be safely traversed with
--
ipairs.
-- 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 export.compressSparseArray(t)
function export.compressSparseArray(t)
checkType('compressSparseArray', 1, t, 'table')
checkType("compressSparseArray", 1, t, "table")
local ret = {}
local ret = {}
local index = 1
local index = 1
Line 340: Line 255:
end
end


--[[
--[==[
------------------------------------------------------------------------------------
This is an iterator for sparse arrays. It can be used like ipairs, but can handle nil values.
-- sparseIpairs
]==]
--
-- This is an iterator for sparse arrays. It can be used like ipairs, but can
-- handle nil values.
------------------------------------------------------------------------------------
--]]
function export.sparseIpairs(t)
function export.sparseIpairs(t)
checkType('sparseIpairs', 1, t, 'table')
checkType("sparseIpairs", 1, t, "table")
local nums = export.numKeys(t)
local nums = export.numKeys(t)
local i = 0
local i = 0
Line 363: Line 273:
end
end


--[[
--[==[
------------------------------------------------------------------------------------
This returns the size of a key/value pair table. It will also work on arrays, but for arrays it is more efficient to
-- size
use the # operator.
--
]==]
-- 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 export.size(t)
function export.size(t)
checkType('size', 1, t, 'table')
checkType("size", 1, t, "table")
local i = 0
local i = 0
for _ in pairs(t) do
for _ in pairs(t) do
Line 380: Line 286:
end
end


--[[
--[==[
-- This returns the length of a table, or the first integer key n counting from
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 metamethods are involved. Intended to be used on data loaded with mw.loadData. For other tables, use #.
-- 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 #.
--]]
function export.length(t)
function export.length(t)
local i = 0
local i = 0
Line 394: Line 297:
end
end


--[[
Recursively compare two values that may be tables, including tables with
nested tables as values. Return true if both values are structurally equal.
Note that this handles arbitary levels of nesting. If all tables are known
to be lists (with only integral keys), use export.deepEqualsList, which will
be more efficient.


NOTE: This is *NOT* smart enough to properly handle cycles; in such a case, it
do
will get into an infinite loop.
local function is_equivalent(a, b, memo, include_mt)
]]
-- Raw equality check.
function export.deepEquals(x, y)
if rawequal(a, b) then
if type(x) == "table" and type(y) == "table" then
return true
-- Two tables are the same if they have the same number of elements
-- If not equal, a and b can only be equivalent if they're both tables.
-- and all keys that are present in one of the tables compare equal
elseif not (type(a) == "table" and type(b) == "table") then
-- to the corresponding keys in the other table, using structural
return false
-- comparison.
end
local sizex = 0
-- If a and b have been compared before, they must be equivalent.
for key, value in pairs(x) do
local memo_a = memo[a]
if not export.deepEquals(value, y[key]) then
if not memo_a then
memo[a] = {[b] = true}
elseif memo_a[b] then
return true
else
memo_a[b] = true
end
local memo_b = memo[b]
if not memo_b then
memo[b] = {[a] = true}
else -- We know memo_b won't have a, since memo_a didn't have b.
memo_b[a] = true
end
-- If include_mt is set, check the metatables are equivalent.
if (
include_mt and
not is_equivalent(getmetatable(a), getmetatable(b), memo, true)
) then
return false
end
-- Fast check: loop over keys in a, checking if an equivalent value exists at the same key in b. Any tables-as-keys are set aside for the laborious check instead.
local tablekeys_a, tablekeys_b, kb
for ka, va in next, a do
if type(ka) == "table" then
if not tablekeys_a then
tablekeys_a = {[ka] = va}
else
tablekeys_a[ka] = va
end
else
local vb = rawget(b, ka)
-- Faster to avoid recursion if possible, as we know va is not nil.
if vb == nil or not is_equivalent(va, vb, memo, include_mt) then
return false
end
end
-- Iterate over b simultaneously (to check it's the same size and to grab any tables-as-keys for the laborious check), but also separately (since it might iterate in a different order, as this is unpredictable in Lua).
local vb
kb, vb = next(b, kb)
-- Fail if b runs out of key/value pairs too early.
if kb == nil then
return false
return false
elseif type(kb) == "table" then
if not tablekeys_b then
tablekeys_b = {[kb] = vb}
else
tablekeys_b[kb] = vb
end
end
end
sizex = sizex + 1
end
end
local sizey = export.size(y)
-- Fail if there are too many key/value pairs in b.
if sizex ~= sizey then
if next(b, kb) ~= nil then
return false
return false
end  
-- If tablekeys_a == tablekeys_b they must be both nil, meaning there are no tables-as-keys to check, so success.
return true
elseif tablekeys_a == tablekeys_b then
return true
-- If only one them exists, then the tables can't be equivalent.
elseif not (tablekeys_a and tablekeys_b) then
return false
end
-- Laborious check: for each table-as-key in tablekeys_a, loop over tablekeys_b looking for an equivalent key/value pair.
for ka, va in next, tablekeys_a do
local kb
while true do
local vb
kb, vb = next(tablekeys_b, kb)
-- Fail if no equivalent is found.
if kb == nil then
return false
elseif (
is_equivalent(ka, kb, memo, include_mt) and
is_equivalent(va, vb, memo, include_mt)
) then
-- Remove match to prevent double-matching (and for speed).
tablekeys_b[kb] = nil
break
end
end
end
-- Success if tablekeys_b is now empty.
return next(tablekeys_b) == nil
end
 
--[==[
Recursively compare two values that may be tables, and returns true if all key-value pairs are structurally equivalent. Note that this handles arbitrary nesting of subtables (including recursive nesting) to any depth, for keys as well as values.
 
If `include_mt` is true, then metatables are also compared.]==]
function export.deepEquals(a, b, include_mt)
return is_equivalent(a, b, {}, include_mt)
end
end
return x == y
end
end


--[[
do
Recursively compare two values that may be lists (i.e. tables with integral
local function get_nested(a, b, ...)
keys), including lists with nested lists as values. Return true if both values
if a == nil then
are structurally equal. Note that this handles arbitary levels of nesting.
return nil
Results are undefined if tables with non-integral keys are present anywhere in
elseif ... ~= nil then
either structure; if that may be the case, use export.deepEquals, which will
return get_nested(a[b], ...)
handle such tables correctly but be less efficient on lists than
end
export.deepEqualsList.
return a[b]
end
 
--[==[
Given a table and an arbitrary number of keys, will successively access subtables using each key in turn, returning the value at the final key. For example, if {t} is { {[1] = {[2] = {[3] = "foo"}}}}, {export.getNested(t, 1, 2, 3)} will return {"foo"}.
 
If no subtable exists for a given key value, returns nil, but will throw an error if a non-table is found at an intermediary key.
]==]
function export.getNested(a, ...)
if a == nil or ... == nil then
error("Must provide a table and at least one key.")
end
return get_nested(a, ...)
end
end


NOTE: This is *NOT* smart enough to properly handle cycles; in such a case, it
do
will get into an infinite loop.
local function set_nested(a, b, c, ...)
]]
if ... == nil then
function export.deepEqualsList(x, y)
a[c] = b
if type(x) == "table" and type(y) == "table" then
return
if #x ~= #y then
end
return false
local t = a[c]
end
if t == nil then
for key, value in ipairs(x) do
t = {}
if not export.deepEqualsList(value, y[key]) then
a[c] = t
return false
end
end
return set_nested(t, b, ...)
end
 
--[==[
Given a table, value and an arbitrary number of keys, will successively access subtables using each key in turn, and sets the value at the final key. For example, if {t} is { {} }, {export.setNested(t, "foo", 1, 2, 3)} will modify {t} to { {[1] = {[2] = {[3] = "foo"} } } }.
 
If no subtable exists for a given key value, one will be created, but the function will throw an error if a non-table value is found at an intermediary key.
 
Note: the parameter order (table, value, keys) differs from functions like rawset, because the number of keys can be arbitrary. This is to avoid situations where an additional argument must be appended to arbitrary lists of variables, which can be awkward and error-prone: for example, when handling variable arguments ({{lua|...}}) or function return values.
]==]
function export.setNested(a, b, ...)
if a == nil or b == nil or ... == nil then
error("Must provide a table, value and at least one key.")
end
end
return true
return set_nested(a, b, ...)
end
end
return x == y
end
end


--[[
--[==[
Given a list and a value to be found, return true if the value is in the array
Given a list and a value to be found, return true if the value is in the array
portion of the list. Shallow comparison is used unless `deepCompare` is given
portion of the list. Comparison is by value, using `deepEquals`.
(in which case comparison is done using `deepEqualsList`).
]==]
]]
function export.contains(list, x, options)
function export.contains(list, x, deepCompare)
local check = _check("contains", "table")
checkType('contains', 1, list, 'table')
check(1, list)
if deepCompare then
check(3, options, true)
for _, v in ipairs(list) do
 
if export.deepEqualsList(v, x) then return true end
if options and options.key then
end
x = options.key(x)
else
end
for _, v in ipairs(list) do
for _, v in ipairs(list) do
if v == x then return true end
if options and options.key then
v = options.key(v)
end
end
if export.deepEquals(v, x) then return true end
end
end
return false
return false
end
end


--[[
--[==[
Given a general table and a value to be found, return true if the value is in
Given a general table and a value to be found, return true if the value is in
either the array or hashmap portion of the table. Shallow comparison is used
either the array or hashmap portion of the table. Comparison is by value, using
unless `deepCompare` is given (in which case comparison is done using
`deepEquals`.
`deepEquals`).
 
]]
NOTE: This used to do shallow comparison by default and accepted a third
function export.tableContains(tbl, x, deepCompare)
"deepCompare" param to do deep comparison. This param is still accepted but now
checkType('tableContains', 1, tbl, 'table')
ignored.
if deepCompare then
]==]
for _, v in pairs(tbl) do
function export.tableContains(tbl, x)
if export.deepEquals(v, x) then return true end
checkType("tableContains", 1, tbl, "table")
end
for _, v in pairs(tbl) do
else
if export.deepEquals(v, x) then return true end
for _, v in pairs(tbl) do
if v == x then return true end
end
end
end
return false
return false
end
end


--[[
--[==[
Given a list and a value to be inserted, append or insert the value if not
Given a `list` and a `new_item` to be inserted, append the value to the end of the list if not already present
already present in the list. Shallow comparison is used unless `deepCompare`
(or insert at an arbitrary position, if `options.pos` is given; see below). Comparison is by value, using {deepEquals}.
is given (in which case comparison is done using `deepEqualsList`). Appends to
 
the end, like the default behavior of table.insert(), unless `pos` is given,
`options` is an optional table of additional options to control the behavior of the operation. The following options are
in which case insertion happens at position `pos` (i.e. before the existing
recognized:
item at position `pos`).
* `pos`: Position at which insertion happens (i.e. before the existing item at position `pos`).
* `key`: Function of one argument to return a comparison key, as with {deepEquals}. The key function is applied to both
`item` and the existing item in `list` to compare against, and the comparison is done against the results.
This is useful when inserting a complex structure into an existing list while avoiding duplicates.
* `combine`: Function of three arguments (the existing item, the new item and the position, respectively) to combine an
existing item with `new_item`, when `new_item` is found in `list`. If unspecified, the existing item is
left alone.
 
Return {false} if entry already found, {true} if inserted.
 
For compatibility, `pos` can be specified directly as the third argument in place of `options`, but this is not
recommended for new code.


NOTE: The order of `item` and `pos` is reversed in comparison to table.insert(),
NOTE: This function is O(N) in the size of the existing list. If you use this function in a loop to insert several
which uses `table.insert(list, item)` to insert at the end but
items, you will get O(M*(M+N)) behavior, effectively O((M+N)^2). Thus it is not recommended to use this unless you are
`table.insert(list, pos, item)` to insert at position POS.
sure the total number of items will be small. (An alternative for large lists is to insert all the items without
]]
checking for duplicates, and use {removeDuplicates()} at the end.)
-- append to list if element not already present
]==]
function export.insertIfNot(list, item, pos, deepCompare)
function export.insertIfNot(list, new_item, options)
if not export.contains(list, item, deepCompare) then
local check = _check("insertIfNot")
if pos then
check(1, list, "table")
table.insert(list, pos, item)
check(3, options, {"table", "number"}, true)
 
if type(options) == "number" then
options = {pos = options}
end
if options and options.combine then
local new_item_key
-- Don't use options.key and options.key(new_item) or new_item in case the key is legitimately false or nil.
if options.key then
new_item_key = options.key(new_item)
else
else
table.insert(list, item)
new_item_key = new_item
end
for i, item in ipairs(list) do
local item_key
if options.key then
item_key = options.key(item)
else
item_key = item
end
if export.deepEquals(item_key, new_item_key) then
local retval = options.combine(item, new_item, i)
if retval ~= nil then
list[i] = retval
end
return false
end
end
end
elseif export.contains(list, new_item, options) then
return false
end
if options and options.pos then
insert(list, options.pos, new_item)
else
insert(list, new_item)
end
end
end
end


--[[
--[==[
Finds key for specified value in a given table.
Finds key for specified value in a given table. Roughly equivalent to reversing the key-value pairs in the table:
Roughly equivalent to reversing the key-value pairs in the table
* {reversed_table = { [value1] = key1, [value2] = key2, ... }}
reversed_table = { [value1] = key1, [value2] = key2, ... }
and then returning {reversed_table[valueToFind]}.
and then returning reversed_table[valueToFind].
 
The value can only be a string or a number (not nil, a boolean, a table, or a function).
The value can only be a string or a number
 
(not nil, a boolean, a table, or a function).
Only reliable if there is just one key with the specified value. Otherwise, the function returns the first key found,
and the output is unpredictable.
Only reliable if there is just one key with the specified value.
]==]
Otherwise, the function returns the first key found,
and the output is unpredictable.
]]
function export.keyFor(t, valueToFind)
function export.keyFor(t, valueToFind)
local check = _check('keyFor')
local check = _check("keyFor")
check(1, t, 'table')
check(1, t, "table")
check(2, valueToFind, { 'string', 'number' })
check(2, valueToFind, {"string", "number"})
 
for key, value in pairs(t) do
for key, value in pairs(t) do
if value == valueToFind then
if value == valueToFind then
Line 538: Line 576:
end
end
end
end
 
return nil
return nil
end
end


--[[
do
The default sorting function used in export.keysToList if no keySort
-- The default sorting function used in export.keysToList if no keySort is defined.
is defined.
local function defaultKeySort(key1, key2)
]]
-- "number" < "string", so numbers will be sorted before strings.
local function defaultKeySort(key1, key2)
local type1, type2 = type(key1), type(key2)
-- "number" < "string", so numbers will be sorted before strings.
if type1 ~= type2 then
local type1, type2 = type(key1), type(key2)
return type1 < type2
if type1 ~= type2 then
end
return type1 < type2
-- string_sort fixes a bug in < whereby all codepoints above U+FFFF are treated as equal.
else
return string_sort(key1, key2)
return key1 < key2
end
end
end


--[[
--[==[
Returns a list of the keys in a table, sorted using either the default
Return a list of the keys in a table, sorted using either the default table.sort function or a custom keySort function.
table.sort function or a custom keySort function.
If there are only numerical keys, numKeys is probably more efficient.
If there are only numerical keys, numKeys is probably more efficient.
]]
]==]
function export.keysToList(t, keySort, checked)
function export.keysToList(t, keySort, checked)
if not checked then
if not checked then
local check = _check('keysToList')
local check = _check("keysToList")
check(1, t, 'table')
check(1, t, "table")
check(2, keySort, 'function', true)
check(2, keySort, "function", true)
end
end
 
local list = {}
local list, i = {}, 0
local index = 1
for key in pairs(t) do
for key, _ in pairs(t) do
i = i + 1
list[index] = key
list[i] = key
index = index + 1
end
 
-- Use specified sort function, or otherwise defaultKeySort.
sort(list, keySort or defaultKeySort)
 
return list
end
end
keys_to_list = export.keysToList
-- Place numbers before strings, otherwise sort using <.
if not keySort then
keySort = defaultKeySort
end
table.sort(list, keySort)
return list
end
end


--[[
--[==[
Iterates through a table, with the keys sorted using the keysToList function.
Iterates through a table, with the keys sorted using the keysToList function. If there are only numerical keys,
If there are only numerical keys, sparseIpairs is probably more efficient.
sparseIpairs is probably more efficient.
]]
]==]
function export.sortedPairs(t, keySort)
function export.sortedPairs(t, keySort)
local check = _check('keysToList')
local check = _check("keysToList")
check(1, t, 'table')
check(1, t, "table")
check(2, keySort, 'function', true)
check(2, keySort, "function", true)
 
local list = export.keysToList(t, keySort, true)
local list, i = keys_to_list(t, keySort, true), 0
 
local i = 0
return function()
return function()
i = i + 1
i = i + 1
Line 602: Line 633:
if key ~= nil then
if key ~= nil then
return key, t[key]
return key, t[key]
else
return nil, nil
end
end
end
end
end
end


function export.reverseIpairs(list)
do
checkType('reverse_ipairs', 1, list, 'table')
local function iter(t, i)
local i = #list + 1
return function()
i = i - 1
i = i - 1
if list[i] ~= nil then
if i > 0 then
return i, list[i]
return i, t[i]
else
return nil, nil
end
end
end
function export.reverseIpairs(t)
checkType("reverseIpairs", 1, t, "table")
-- Not safe to use #t, as it can be unpredictable if there is a hash part.
local i = 0
repeat
i = i + 1
until t[i] == nil
return iter, t, i
end
end
end
end


--[=[
local function getIteratorValues(i, j , s, list)
Joins an array with serial comma and serial conjunction, normally "and".
i = (i and i < 0 and #list - i + 1) or i or (s and s < 0 and #list) or 1
An improvement on mw.text.listToText, which doesn't properly handle serial
j = (j and j < 0 and #list - j + 1) or j or (s and s < 0 and 1) or #list
commas.
s = s or (j < i and -1) or 1
if (
Options:
i == 0 or i % 1 ~= 0 or
- conj
j == 0 or j % 1 ~= 0 or
Conjunction to use; defaults to "and".
s == 0 or s % 1 ~= 0
- italicizeConj
) then
Italicize conjunction: for [[Module:Template:also]]
error("Arguments i, j and s must be non-zero integers.")
- dontTag
end
Don't tag the serial comma and serial "and". For error messages, in
return i, j, s
which HTML cannot be used.
end
]=]
 
--[==[
Given an array `list` and function `func`, iterate through the array applying {func(r, k, v)}, and returning the result,
where `r` is the value calculated so far, `k` is an index, and `v` is the value at index `k`. For example,
{reduce(array, function(a, b) return a + b end)} will return the sum of `array`.
 
Optional arguments:
* `i`: start index; negative values count from the end of the array
* `j`: end index; negative values count from the end of the array
* `s`: step increment
These must be non-zero integers. The function will determine where to iterate from, whether to iterate forwards or
backwards and by how much, based on these inputs (see examples below for default behaviours).
 
Examples:
# No values for i, j or s results in forward iteration from the start to the end in steps of 1 (the default).
# s=-1 results in backward iteration from the end to the start in steps of 1.
# i=7, j=3 results in backward iteration from indices 7 to 3 in steps of 1 (i.e. s=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, s=-1 results in backward iteration from the end to the 3rd last index.
Note: directionality generally only matters for `reduce`, but values of s > 1 (or s < -1) still affect the return value
of `apply`.
]==]
 
function export.reduce(list, func, i, j, s)
i, j, s = getIteratorValues(i, j , s, list)
local ret = list[i]
for k = i + s, j, s do
ret = func(ret, k, list[k])
end
return ret
end
 
--[==[
Given an array `list` and function `func`, iterate through the array applying {func(k, v)} (where `k` is an index, and
`v` is the value at index `k`), and return an array of the resulting values. For example,
{apply(array, function(a) return 2*a end)} will return an array where each member of `array` has been doubled.
 
Optional arguments:
* `i`: start index; negative values count from the end of the array
* `j`: end index; negative values count from the end of the array
* `s`: step increment
These must be non-zero integers. The function will determine where to iterate from, whether to iterate forwards or
backwards and by how much, based on these inputs (see examples below for default behaviours).
 
Examples:
# No values for i, j or s results in forward iteration from the start to the end in steps of 1 (the default).
# s=-1 results in backward iteration from the end to the start in steps of 1.
# i=7, j=3 results in backward iteration from indices 7 to 3 in steps of 1 (i.e. s=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, s=-1 results in backward iteration from the end to the 3rd last index.
Note: directionality makes the most difference for `reduce`, but values of s > 1 (or s < -1) still affect the return
value of `apply`.
]==]
function export.apply(list, func, i, j, s)
local modified_list = export.deepcopy(list)
i, j, s = getIteratorValues(i, j , s, modified_list)
for k = i, j, s do
modified_list[k] = func(k, modified_list[k])
end
return modified_list
end
 
--[==[
Given an array `list` and function `func`, iterate through the array applying {func(k, v)} (where `k` is an index, and
`v` is the value at index `k`), and returning whether the function is true for all iterations.
 
Optional arguments:
* `i`: start index; negative values count from the end of the array
* `j`: end index; negative values count from the end of the array
* `s`: step increment
These must be non-zero integers. The function will determine where to iterate from, whether to iterate forwards or
backwards and by how much, based on these inputs (see examples below for default behaviours).
 
Examples:
# No values for i, j or s results in forward iteration from the start to the end in steps of 1 (the default).
# s=-1 results in backward iteration from the end to the start in steps of 1.
# i=7, j=3 results in backward iteration from indices 7 to 3 in steps of 1 (i.e. s=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, s=-1 results in backward iteration from the end to the 3rd last index.
]==]
function export.all(list, func, i, j, s)
i, j, s = getIteratorValues(i, j , s, list)
local ret = true
for k = i, j, s do
ret = ret and not not (func(k, list[k]))
if not ret then break end
end
return ret
end
 
--[==[
Given an array `list` and function `func`, iterate through the array applying {func(k, v)} (where `k` is an index, and
`v` is the value at index `k`), and returning whether the function is true for at least one iteration.
 
Optional arguments:
* `i`: start index; negative values count from the end of the array
* `j`: end index; negative values count from the end of the array
* `s`: step increment
These must be non-zero integers. The function will determine where to iterate from, whether to iterate forwards or
backwards and by how much, based on these inputs (see examples below for default behaviours).
 
Examples:
# No values for i, j or s results in forward iteration from the start to the end in steps of 1 (the default).
# s=-1 results in backward iteration from the end to the start in steps of 1.
# i=7, j=3 results in backward iteration from indices 7 to 3 in steps of 1 (i.e. s=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, s=-1 results in backward iteration from the end to the 3rd last index.
]==]
function export.any(list, func, i, j, s)
i, j, s = getIteratorValues(i, j , s, list)
local ret = false
for k = i, j, s do
ret = ret or not not (func(k, list[k]))
if ret then break end
end
return ret
end
 
--[==[
Joins an array with serial comma and serial conjunction, normally {"and"}. An improvement on {mw.text.listToText},
which doesn't properly handle serial commas.
 
Options:
* `conj`: Conjunction to use; defaults to {"and"}.
* `italicizeConj`: Italicize conjunction: for [[Module:also]]
* `dontTag`: Don't tag the serial comma and serial {"and"}. For error messages, in which HTML cannot be used.
]==]
function export.serialCommaJoin(seq, options)
function export.serialCommaJoin(seq, options)
local check = _check("serialCommaJoin", "table")
local check = _check("serialCommaJoin", "table")
check(1, seq)
check(1, seq)
check(2, options, true)
check(2, options, true)
 
local length = #seq
local length = #seq
 
if not options then
if not options then
options = {}
options = {}
end
end
 
local conj
local conj
if length > 1 then
if length > 1 then
Line 654: Line 814:
end
end
end
end
 
if length == 0 then
if length == 0 then
return ""
return ""
Line 662: Line 822:
return seq[1] .. " " .. conj .. " " .. seq[2]
return seq[1] .. " " .. conj .. " " .. seq[2]
else
else
local comma = options.dontTag and "," or '<span class="serial-comma">,</span>'
local comma = options.dontTag and "," or "<span class=\"serial-comma\">,</span>"
conj = options.dontTag and ' ' .. conj .. " " or '<span class="serial-and"> ' .. conj .. '</span> '
conj = options.dontTag and " " .. conj .. " " or "<span class=\"serial-and\"> " .. conj .. "</span> "
return table.concat(seq, ", ", 1, length - 1) ..
return concat(seq, ", ", 1, length - 1) ..
comma .. conj .. seq[length]
comma .. conj .. seq[length]
end
end
end
end


--[[
--[==[
Concatenates all values in the table that are indexed by a number, in order.
Concatenate all values in the table that are indexed by a number, in order.
sparseConcat{ a, nil, c, d }  =>  "acd"
* {sparseConcat{ a, nil, c, d }}  =>  {"acd"}
sparseConcat{ nil, b, c, d }  =>  "bcd"
* {sparseConcat{ nil, b, c, d }}  =>  {"bcd"}
]]
]==]
function export.sparseConcat(t, sep, i, j)
function export.sparseConcat(t, sep, i, j)
local list = {}
local list = {}
 
local list_i = 0
local list_i = 0
for _, v in export.sparseIpairs(t) do
for _, v in export.sparseIpairs(t) do
Line 682: Line 842:
list[list_i] = v
list[list_i] = v
end
end
 
return table.concat(list, sep, i, j)
return concat(list, sep, i, j)
end
end


--[[
--[==[
Values of numberic keys in array portion of table are reversed:
Values of numeric keys in array portion of table are reversed: { { "a", "b", "c" }} -> { { "c", "b", "a" }}
{ "a", "b", "c" } -> { "c", "b", "a" }
]==]
--]]
function export.reverse(t)
function export.reverse(t)
checkType("reverse", 1, t, "table")
checkType("reverse", 1, t, "table")
-- Not safe to use #t, as it can be unpredictable if there is a hash part.
local new_t = {}
local ret, base = {}, 0
local new_t_i = 1
repeat
for i = #t, 1, -1 do
base = base + 1
new_t[new_t_i] = t[i]
until t[base] == nil
new_t_i = new_t_i + 1
for i = base - 1, 1, -1 do
ret[base - i] = t[i]
end
end
return new_t
return ret
end
end


function export.reverseConcat(t, sep, i, j)
function export.reverseConcat(t, sep, i, j)
return table.concat(export.reverse(t), sep, i, j)
return concat(export.reverse(t), sep, i, j)
end
end


-- { "a", "b", "c" } -> { a = 1, b = 2, c = 3 }
--[==[
Invert an array. For example, {invert({ "a", "b", "c" })} -> { { a = 1, b = 2, c = 3 }}
]==]
function export.invert(array)
function export.invert(array)
checkType("invert", 1, array, "table")
checkType("invert", 1, array, "table")
 
local map = {}
local map = {}
for i, v in ipairs(array) do
for i, v in ipairs(array) do
map[v] = i
map[v] = i
end
end
 
return map
return map
end
end


--[[
--[==[
{ "a", "b", "c" } -> { ["a"] = true, ["b"] = true, ["c"] = true }
Convert `list` (a table with a list of values) into a set (a table where those values are keys instead). This is a useful
--]]
way to create a fast lookup table, since looking up a table key is much, much faster than iterating over the whole list
function export.listToSet(t)
to see if it contains a given value.
checkType("listToSet", 1, t, "table")
 
By default, each item is given the value true. If the optional parameter `value` is a function or functor, then the value
local set = {}
for each item is determined by calling it with the item key as the first parameter, plus any additional arguments passed
for _, item in ipairs(t) do
to {listToSet}; if value is anything else, then it is used as the fixed value for every item.
set[item] = true
]==]
function export.listToSet(list, value, ...)
checkType("listToSet", 1, list, "table")
local set, i = {}, 0
if value == nil then
value = true
elseif is_callable(value) then
-- Separate loop avoids an "is callable" lookup each iteration.
while true do
i = i + 1
local item = list[i]
if item == nil then
return set
end
set[item] = value(item, ...)
end
end
while true do
i = i + 1
local item = list[i]
if item == nil then
return set
end
set[item] = value
end
end
return set
end
end


--[[
--[==[
Returns true if all keys in the table are consecutive integers starting at 1.
Return true if all keys in the table are consecutive integers starting at 1.
--]]
]==]
function export.isArray(t)
function export.isArray(t)
checkType("isArray", 1, t, "table")
checkType("isArray", 1, t, "table")
 
local i = 0
local i = 0
for _ in pairs(t) do
for _ in pairs(t) do
Line 745: Line 929:
end
end
return true
return true
end
--[==[
Add a list of aliases for a given key to a table. The aliases must be given as a table.
]==]
function export.alias(t, k, aliases)
for _, alias in pairs(aliases) do
t[alias] = t[k]
end
end
end


return export
return export

Latest revision as of 23:02, 29 August 2024



--[[
------------------------------------------------------------------------------------
--                      table (formerly 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.                                           --
------------------------------------------------------------------------------------
--]]

--[[
	Inserting new values into a table using a local "index" variable, which is
	incremented each time, is faster than using "table.insert(t, x)" or
	"t[#t + 1] = x". See the talk page.
]]

local export = {}

local libraryUtil = require("libraryUtil")
local table = table

local checkType = libraryUtil.checkType
local checkTypeMulti = libraryUtil.checkTypeMulti
local concat = table.concat
local format = string.format
local getmetatable = getmetatable
local insert = table.insert
local ipairs = ipairs
local is_callable = require("Module:fun").is_callable
local is_positive_integer -- defined as export.isPositiveInteger below
local keys_to_list -- defined as export.keysToList below
local next = next
local pairs = pairs
local rawequal = rawequal
local rawget = rawget
local setmetatable = setmetatable
local sort = table.sort
local string_sort = require("Module:collation").string_sort
local type = type

local infinity = math.huge

local function _check(funcName, expectType)
	if type(expectType) == "string" then
		return function(argIndex, arg, nilOk)
			checkType(funcName, argIndex, arg, expectType, nilOk)
		end
	else
		return function(argIndex, arg, expectType, nilOk)
			if type(expectType) == "table" then
				if not nilOk or arg ~= nil then
					-- checkTypeMulti() doesn't accept a fifth `nilOk` argument, unlike the other check functions.
					checkTypeMulti(funcName, argIndex, arg, expectType)
				end
			else
				checkType(funcName, argIndex, arg, expectType, nilOk)
			end
		end
	end
end

--[==[
Return 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 export.isPositiveInteger(v)
	return type(v) == "number" and v >= 1 and v % 1 == 0 and v < infinity
end
is_positive_integer = export.isPositiveInteger

--[==[
Return a clone of an object. If the object is 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 export.shallowcopy(orig)
	if type(orig) ~= "table" then
		return orig
	end
	local copy = {}
	for k, v in pairs(orig) do
		copy[k] = v
	end
	return copy
end

do
	local function rawpairs(t)
		return next, t
	end

	local function make_copy(orig, memo, mt_flag, keep_loaded_data)
		if type(orig) ~= "table" then
			return orig
		end
		local memoized = memo[orig]
		if memoized ~= nil then
			return memoized
		end
		local mt = getmetatable(orig)
		local loaded_data = mt and mt.mw_loadData
		if loaded_data and keep_loaded_data then
			memo[orig] = orig
			return orig
		end
		local copy = {}
		memo[orig] = copy
		for k, v in (loaded_data and pairs or rawpairs)(orig) do
			copy[make_copy(k, memo, mt_flag, keep_loaded_data)] = make_copy(v, memo, mt_flag, keep_loaded_data)
		end
		if loaded_data then
			return copy
		elseif mt_flag == "keep" then
			setmetatable(copy, mt)
		elseif mt_flag ~= "none" then
			setmetatable(copy, make_copy(mt, memo, mt_flag, keep_loaded_data))
		end
		return copy
	end

	--[==[
	Recursive deep copy function. Preserves copied identities of subtables.
	A more powerful version of {mw.clone}, with customizable options.
	* By default, metatables are copied, except for data loaded via mw.loadData (see below). If `metatableFlag` is set to "none", the copy will not have any metatables at all. Conversely, if `metatableFlag` is set to "keep", then the cloned table (and all its members) will have the exact same metatable as their original version.
	* If `keepLoadedData` is true, then any data loaded via {mw.loadData} will not be copied, and the original will be used instead. This is useful in iterative contexts where it is necessary to copy data being destructively modified, because objects loaded via mw.loadData are immutable.
	* Notes:
	*# Protected metatables will not be copied (i.e. those hidden behind a __metatable metamethod), as they are not
	   accessible by Lua's design. Instead, the output of the __metatable method will be used instead.
	*# When iterating over the table, the __pairs metamethod is ignored, since this can prevent the table from being properly cloned.
	*# Data loaded via mw.loadData is a special case in two ways: the metatable is stripped, because otherwise the cloned table throws errors when accessed; in addition, the __pairs metamethod is used, since otherwise the cloned table would be empty.]==]
	function export.deepcopy(orig, metatableFlag, keepLoadedData)
		return make_copy(orig, {}, metatableFlag, keepLoadedData)
	end
end

--[==[
Append any number of tables together and returns the result. Compare the Lisp expression {(append list1 list2 ...)}.
]==]
function export.append(...)
	local ret, n = {}, 0
	for i = 1, arg.n do
		for _, v in ipairs(arg[i]) do
			n = n + 1
			ret[n] = v
		end
	end
	return ret
end

--[==[
Extend an existing list by a new list, modifying the existing list in-place. Compare the Python expression
{list.extend(new_items)}.

`options` is an optional table of additional options to control the behavior of the operation. The following options are
recognized:
* `insertIfNot`: Use {export.insertIfNot()} instead of {table.insert()}, which ensures that duplicate items do not get
  inserted (at the cost of an O((M+N)*N) operation, where M = #list and N = #new_items).
* `key`: As in {insertIfNot()}. Ignored otherwise.
* `pos`: As in {insertIfNot()}. Ignored otherwise.
]==]
function export.extendList(list, new_items, options)
	local check = _check("extendList", "table")
	check(1, list)
	check(2, new_items)
	check(3, options, true)
	for _, item in ipairs(new_items) do
		if options and options.insertIfNot then
			export.insertIfNot(list, item, options)
		else
			insert(list, item)
		end
	end
end

--[==[
Remove 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.
-- -0, NaN and -NaN have special handling, as they can't be used as table keys.
]==]
function export.removeDuplicates(t)
	checkType("removeDuplicates", 1, t, "table")
	local ret, n, seen, _neg_0, _pos_nan, _neg_nan = {}, 0, {}
	for _, v in ipairs(t) do
		local v_key = v
		-- -0
		if v == 0 and 1 / v < 0 then
			_neg_0 = _neg_0 or {}
			v_key = _neg_0
		-- NaN and -NaN.
		elseif v ~= v then
			if format("%f", v) == "nan" then
				_pos_nan = _pos_nan or {}
				v_key = _pos_nan
			else
				_neg_nan = _neg_nan or {}
				v_key = _neg_nan
			end
		end
		if not seen[v_key] then
			n = n + 1
			ret[n] = v
			seen[v_key] = true
		end
	end
	return ret
end

--[==[
Given a table, return an array containing the numbers of any numerical keys that have non-nil values, sorted in
numerical order.
]==]
function export.numKeys(t, checked)
	if not checked then
		checkType("numKeys", 1, t, "table")
	end
	local nums = {}
	local index = 1
	for k in pairs(t) do
		if is_positive_integer(k) then
			nums[index] = k
			index = index + 1
		end
	end
	sort(nums)
	return nums
end

--[==[
Return the maximum index of a table or array that possibly has holes in it, or 0 if there are no numerical keys in the
table.
]==]
function export.maxIndex(t)
	local max = 0
	for k in pairs(t) do
		if is_positive_integer(k) and k > max then
			max = k
		end
	end
	return max
end

--[==[
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 export.compressSparseArray(t)
	checkType("compressSparseArray", 1, t, "table")
	local ret = {}
	local index = 1
	local nums = export.numKeys(t)
	for _, num in ipairs(nums) do
		ret[index] = t[num]
		index = index + 1
	end
	return ret
end

--[==[
This is an iterator for sparse arrays. It can be used like ipairs, but can handle nil values.
]==]
function export.sparseIpairs(t)
	checkType("sparseIpairs", 1, t, "table")
	local nums = export.numKeys(t)
	local i = 0
	return function()
		i = i + 1
		local key = nums[i]
		if key then
			return key, t[key]
		else
			return nil, nil
		end
	end
end

--[==[
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 export.size(t)
	checkType("size", 1, t, "table")
	local i = 0
	for _ in pairs(t) do
		i = i + 1
	end
	return i
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 metamethods are involved. Intended to be used on data loaded with mw.loadData. For other tables, use #.
]==]
function export.length(t)
	local i = 0
	repeat
		i = i + 1
	until t[i] == nil
	return i - 1
end


do
	local function is_equivalent(a, b, memo, include_mt)
		-- Raw equality check.
		if rawequal(a, b) then
			return true
		-- If not equal, a and b can only be equivalent if they're both tables.
		elseif not (type(a) == "table" and type(b) == "table") then
			return false
		end
		-- If a and b have been compared before, they must be equivalent.
		local memo_a = memo[a]
		if not memo_a then
			memo[a] = {[b] = true}
		elseif memo_a[b] then
			return true
		else
			memo_a[b] = true
		end
		local memo_b = memo[b]
		if not memo_b then
			memo[b] = {[a] = true}
		else -- We know memo_b won't have a, since memo_a didn't have b.
			memo_b[a] = true
		end
		-- If include_mt is set, check the metatables are equivalent.
		if (
			include_mt and
			not is_equivalent(getmetatable(a), getmetatable(b), memo, true)
		) then
			return false
		end
		-- Fast check: loop over keys in a, checking if an equivalent value exists at the same key in b. Any tables-as-keys are set aside for the laborious check instead.
		local tablekeys_a, tablekeys_b, kb
		for ka, va in next, a do
			if type(ka) == "table" then
				if not tablekeys_a then
					tablekeys_a = {[ka] = va}
				else
					tablekeys_a[ka] = va
				end
			else
				local vb = rawget(b, ka)
				-- Faster to avoid recursion if possible, as we know va is not nil.
				if vb == nil or not is_equivalent(va, vb, memo, include_mt) then
					return false
				end
			end
			-- Iterate over b simultaneously (to check it's the same size and to grab any tables-as-keys for the laborious check), but also separately (since it might iterate in a different order, as this is unpredictable in Lua).
			local vb
			kb, vb = next(b, kb)
			-- Fail if b runs out of key/value pairs too early.
			if kb == nil then
				return false
			elseif type(kb) == "table" then
				if not tablekeys_b then
					tablekeys_b = {[kb] = vb}
				else
					tablekeys_b[kb] = vb
				end
			end
		end
		-- Fail if there are too many key/value pairs in b.
		if next(b, kb) ~= nil then
			return false
		-- If tablekeys_a == tablekeys_b they must be both nil, meaning there are no tables-as-keys to check, so success.
		elseif tablekeys_a == tablekeys_b then
			return true
		-- If only one them exists, then the tables can't be equivalent.
		elseif not (tablekeys_a and tablekeys_b) then
			return false
		end
		-- Laborious check: for each table-as-key in tablekeys_a, loop over tablekeys_b looking for an equivalent key/value pair.
		for ka, va in next, tablekeys_a do
			local kb
			while true do
				local vb
				kb, vb = next(tablekeys_b, kb)
				-- Fail if no equivalent is found.
				if kb == nil then
					return false
				elseif (
					is_equivalent(ka, kb, memo, include_mt) and
					is_equivalent(va, vb, memo, include_mt)
				) then
					-- Remove match to prevent double-matching (and for speed).
					tablekeys_b[kb] = nil
					break
				end
			end
		end
		-- Success if tablekeys_b is now empty.
		return next(tablekeys_b) == nil
	end

	--[==[
	Recursively compare two values that may be tables, and returns true if all key-value pairs are structurally equivalent. Note that this handles arbitrary nesting of subtables (including recursive nesting) to any depth, for keys as well as values.

	If `include_mt` is true, then metatables are also compared.]==]
	function export.deepEquals(a, b, include_mt)
		return is_equivalent(a, b, {}, include_mt)
	end
end

do
	local function get_nested(a, b, ...)
		if a == nil then
			return nil
		elseif ... ~= nil then
			return get_nested(a[b], ...)
		end
		return a[b]
	end

	--[==[
	Given a table and an arbitrary number of keys, will successively access subtables using each key in turn, returning the value at the final key. For example, if {t} is { {[1] = {[2] = {[3] = "foo"}}}}, {export.getNested(t, 1, 2, 3)} will return {"foo"}.

	If no subtable exists for a given key value, returns nil, but will throw an error if a non-table is found at an intermediary key.
	]==]
	function export.getNested(a, ...)
		if a == nil or ... == nil then
			error("Must provide a table and at least one key.")
		end
		return get_nested(a, ...)
	end
end

do
	local function set_nested(a, b, c, ...)
		if ... == nil then
			a[c] = b
			return
		end
		local t = a[c]
		if t == nil then
			t = {}
			a[c] = t
		end
		return set_nested(t, b, ...)
	end

	--[==[
	Given a table, value and an arbitrary number of keys, will successively access subtables using each key in turn, and sets the value at the final key. For example, if {t} is { {} }, {export.setNested(t, "foo", 1, 2, 3)} will modify {t} to { {[1] = {[2] = {[3] = "foo"} } } }.

	If no subtable exists for a given key value, one will be created, but the function will throw an error if a non-table value is found at an intermediary key.

	Note: the parameter order (table, value, keys) differs from functions like rawset, because the number of keys can be arbitrary. This is to avoid situations where an additional argument must be appended to arbitrary lists of variables, which can be awkward and error-prone: for example, when handling variable arguments ({{lua|...}}) or function return values.
	]==]
	function export.setNested(a, b, ...)
		if a == nil or b == nil or ... == nil then
			error("Must provide a table, value and at least one key.")
		end
		return set_nested(a, b, ...)
	end
end

--[==[
Given a list and a value to be found, return true if the value is in the array
portion of the list. Comparison is by value, using `deepEquals`.
]==]
function export.contains(list, x, options)
	local check = _check("contains", "table")
	check(1, list)
	check(3, options, true)

	if options and options.key then
		x = options.key(x)
	end
	for _, v in ipairs(list) do
		if options and options.key then
			v = options.key(v)
		end
		if export.deepEquals(v, x) then return true end
	end
	return false
end

--[==[
Given a general table and a value to be found, return true if the value is in
either the array or hashmap portion of the table. Comparison is by value, using
`deepEquals`.

NOTE: This used to do shallow comparison by default and accepted a third
"deepCompare" param to do deep comparison. This param is still accepted but now
ignored.
]==]
function export.tableContains(tbl, x)
	checkType("tableContains", 1, tbl, "table")
	for _, v in pairs(tbl) do
		if export.deepEquals(v, x) then return true end
	end
	return false
end

--[==[
Given a `list` and a `new_item` to be inserted, append the value to the end of the list if not already present
(or insert at an arbitrary position, if `options.pos` is given; see below). Comparison is by value, using {deepEquals}.

`options` is an optional table of additional options to control the behavior of the operation. The following options are
recognized:
* `pos`: Position at which insertion happens (i.e. before the existing item at position `pos`).
* `key`: Function of one argument to return a comparison key, as with {deepEquals}. The key function is applied to both
		 `item` and the existing item in `list` to compare against, and the comparison is done against the results.
		 This is useful when inserting a complex structure into an existing list while avoiding duplicates.
* `combine`: Function of three arguments (the existing item, the new item and the position, respectively) to combine an
			 existing item with `new_item`, when `new_item` is found in `list`. If unspecified, the existing item is
			 left alone.

Return {false} if entry already found, {true} if inserted.

For compatibility, `pos` can be specified directly as the third argument in place of `options`, but this is not
recommended for new code.

NOTE: This function is O(N) in the size of the existing list. If you use this function in a loop to insert several
items, you will get O(M*(M+N)) behavior, effectively O((M+N)^2). Thus it is not recommended to use this unless you are
sure the total number of items will be small. (An alternative for large lists is to insert all the items without
checking for duplicates, and use {removeDuplicates()} at the end.)
]==]
function export.insertIfNot(list, new_item, options)
	local check = _check("insertIfNot")
	check(1, list, "table")
	check(3, options, {"table", "number"}, true)

	if type(options) == "number" then
		options = {pos = options}
	end
	if options and options.combine then
		local new_item_key
		-- Don't use options.key and options.key(new_item) or new_item in case the key is legitimately false or nil.
		if options.key then
			new_item_key = options.key(new_item)
		else
			new_item_key = new_item
		end
		for i, item in ipairs(list) do
			local item_key
			if options.key then
				item_key = options.key(item)
			else
				item_key = item
			end
			if export.deepEquals(item_key, new_item_key) then
				local retval = options.combine(item, new_item, i)
				if retval ~= nil then
					list[i] = retval
				end
				return false
			end
		end
	elseif export.contains(list, new_item, options) then
		return false
	end
	if options and options.pos then
		insert(list, options.pos, new_item)
	else
		insert(list, new_item)
	end
end

--[==[
Finds key for specified value in a given table. Roughly equivalent to reversing the key-value pairs in the table:
* {reversed_table = { [value1] = key1, [value2] = key2, ... }}
and then returning {reversed_table[valueToFind]}.

The value can only be a string or a number (not nil, a boolean, a table, or a function).

Only reliable if there is just one key with the specified value. Otherwise, the function returns the first key found,
and the output is unpredictable.
]==]
function export.keyFor(t, valueToFind)
	local check = _check("keyFor")
	check(1, t, "table")
	check(2, valueToFind, {"string", "number"})

	for key, value in pairs(t) do
		if value == valueToFind then
			return key
		end
	end

	return nil
end

do
	-- The default sorting function used in export.keysToList if no keySort is defined.
	local function defaultKeySort(key1, key2)
		-- "number" < "string", so numbers will be sorted before strings.
		local type1, type2 = type(key1), type(key2)
		if type1 ~= type2 then
			return type1 < type2
		end
		-- string_sort fixes a bug in < whereby all codepoints above U+FFFF are treated as equal.
		return string_sort(key1, key2)
	end

	--[==[
	Return a list of the keys in a table, sorted using either the default table.sort function or a custom keySort function.
	If there are only numerical keys, numKeys is probably more efficient.
	]==]
	function export.keysToList(t, keySort, checked)
		if not checked then
			local check = _check("keysToList")
			check(1, t, "table")
			check(2, keySort, "function", true)
		end

		local list, i = {}, 0
		for key in pairs(t) do
			i = i + 1
			list[i] = key
		end

		-- Use specified sort function, or otherwise defaultKeySort.
		sort(list, keySort or defaultKeySort)

		return list
	end
	keys_to_list = export.keysToList
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 export.sortedPairs(t, keySort)
	local check = _check("keysToList")
	check(1, t, "table")
	check(2, keySort, "function", true)

	local list, i = keys_to_list(t, keySort, true), 0

	return function()
		i = i + 1
		local key = list[i]
		if key ~= nil then
			return key, t[key]
		end
	end
end

do
	local function iter(t, i)
		i = i - 1
		if i > 0 then
			return i, t[i]
		end
	end

	function export.reverseIpairs(t)
		checkType("reverseIpairs", 1, t, "table")
		-- Not safe to use #t, as it can be unpredictable if there is a hash part.
		local i = 0
		repeat
			i = i + 1
		until t[i] == nil
		return iter, t, i
	end
end

local function getIteratorValues(i, j , s, list)
	i = (i and i < 0 and #list - i + 1) or i or (s and s < 0 and #list) or 1
	j = (j and j < 0 and #list - j + 1) or j or (s and s < 0 and 1) or #list
	s = s or (j < i and -1) or 1
	if (
		i == 0 or i % 1 ~= 0 or
		j == 0 or j % 1 ~= 0 or
		s == 0 or s % 1 ~= 0
	) then
		error("Arguments i, j and s must be non-zero integers.")
	end
	return i, j, s
end

--[==[
Given an array `list` and function `func`, iterate through the array applying {func(r, k, v)}, and returning the result,
where `r` is the value calculated so far, `k` is an index, and `v` is the value at index `k`. For example,
{reduce(array, function(a, b) return a + b end)} will return the sum of `array`.

Optional arguments:
* `i`: start index; negative values count from the end of the array
* `j`: end index; negative values count from the end of the array
* `s`: step increment
These must be non-zero integers. The function will determine where to iterate from, whether to iterate forwards or
backwards and by how much, based on these inputs (see examples below for default behaviours).

Examples:
# No values for i, j or s results in forward iteration from the start to the end in steps of 1 (the default).
# s=-1 results in backward iteration from the end to the start in steps of 1.
# i=7, j=3 results in backward iteration from indices 7 to 3 in steps of 1 (i.e. s=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, s=-1 results in backward iteration from the end to the 3rd last index.
Note: directionality generally only matters for `reduce`, but values of s > 1 (or s < -1) still affect the return value
of `apply`.
]==]

function export.reduce(list, func, i, j, s)
	i, j, s = getIteratorValues(i, j , s, list)
	local ret = list[i]
	for k = i + s, j, s do
		ret = func(ret, k, list[k])
	end
	return ret
end

--[==[
Given an array `list` and function `func`, iterate through the array applying {func(k, v)} (where `k` is an index, and
`v` is the value at index `k`), and return an array of the resulting values. For example,
{apply(array, function(a) return 2*a end)} will return an array where each member of `array` has been doubled.

Optional arguments:
* `i`: start index; negative values count from the end of the array
* `j`: end index; negative values count from the end of the array
* `s`: step increment
These must be non-zero integers. The function will determine where to iterate from, whether to iterate forwards or
backwards and by how much, based on these inputs (see examples below for default behaviours).

Examples:
# No values for i, j or s results in forward iteration from the start to the end in steps of 1 (the default).
# s=-1 results in backward iteration from the end to the start in steps of 1.
# i=7, j=3 results in backward iteration from indices 7 to 3 in steps of 1 (i.e. s=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, s=-1 results in backward iteration from the end to the 3rd last index.
Note: directionality makes the most difference for `reduce`, but values of s > 1 (or s < -1) still affect the return
value of `apply`.
]==]
function export.apply(list, func, i, j, s)
	local modified_list = export.deepcopy(list)
	i, j, s = getIteratorValues(i, j , s, modified_list)
	for k = i, j, s do
		modified_list[k] = func(k, modified_list[k])
	end
	return modified_list
end

--[==[
Given an array `list` and function `func`, iterate through the array applying {func(k, v)} (where `k` is an index, and
`v` is the value at index `k`), and returning whether the function is true for all iterations.

Optional arguments:
* `i`: start index; negative values count from the end of the array
* `j`: end index; negative values count from the end of the array
* `s`: step increment
These must be non-zero integers. The function will determine where to iterate from, whether to iterate forwards or
backwards and by how much, based on these inputs (see examples below for default behaviours).

Examples:
# No values for i, j or s results in forward iteration from the start to the end in steps of 1 (the default).
# s=-1 results in backward iteration from the end to the start in steps of 1.
# i=7, j=3 results in backward iteration from indices 7 to 3 in steps of 1 (i.e. s=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, s=-1 results in backward iteration from the end to the 3rd last index.
]==]
function export.all(list, func, i, j, s)
	i, j, s = getIteratorValues(i, j , s, list)
	local ret = true
	for k = i, j, s do
		ret = ret and not not (func(k, list[k]))
		if not ret then break end
	end
	return ret
end

--[==[
Given an array `list` and function `func`, iterate through the array applying {func(k, v)} (where `k` is an index, and
`v` is the value at index `k`), and returning whether the function is true for at least one iteration.

Optional arguments:
* `i`: start index; negative values count from the end of the array
* `j`: end index; negative values count from the end of the array
* `s`: step increment
These must be non-zero integers. The function will determine where to iterate from, whether to iterate forwards or
backwards and by how much, based on these inputs (see examples below for default behaviours).

Examples:
# No values for i, j or s results in forward iteration from the start to the end in steps of 1 (the default).
# s=-1 results in backward iteration from the end to the start in steps of 1.
# i=7, j=3 results in backward iteration from indices 7 to 3 in steps of 1 (i.e. s=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, s=-1 results in backward iteration from the end to the 3rd last index.
]==]
function export.any(list, func, i, j, s)
	i, j, s = getIteratorValues(i, j , s, list)
	local ret = false
	for k = i, j, s do
		ret = ret or not not (func(k, list[k]))
		if ret then break end
	end
	return ret
end

--[==[
Joins an array with serial comma and serial conjunction, normally {"and"}. An improvement on {mw.text.listToText},
which doesn't properly handle serial commas.

Options:
* `conj`: Conjunction to use; defaults to {"and"}.
* `italicizeConj`: Italicize conjunction: for [[Module:also]]
* `dontTag`: Don't tag the serial comma and serial {"and"}. For error messages, in which HTML cannot be used.
]==]
function export.serialCommaJoin(seq, options)
	local check = _check("serialCommaJoin", "table")
	check(1, seq)
	check(2, options, true)

	local length = #seq

	if not options then
		options = {}
	end

	local conj
	if length > 1 then
		conj = options.conj or "and"
		if options.italicizeConj then
			conj = "''" .. conj .. "''"
		end
	end

	if length == 0 then
		return ""
	elseif length == 1 then
		return seq[1] -- nothing to join
	elseif length == 2 then
		return seq[1] .. " " .. conj .. " " .. seq[2]
	else
		local comma = options.dontTag and "," or "<span class=\"serial-comma\">,</span>"
		conj = options.dontTag and " " .. conj .. " " or "<span class=\"serial-and\"> " .. conj .. "</span> "
		return concat(seq, ", ", 1, length - 1) ..
				comma .. conj .. seq[length]
	end
end

--[==[
Concatenate 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 export.sparseConcat(t, sep, i, j)
	local list = {}

	local list_i = 0
	for _, v in export.sparseIpairs(t) do
		list_i = list_i + 1
		list[list_i] = v
	end

	return concat(list, sep, i, j)
end

--[==[
Values of numeric keys in array portion of table are reversed: { { "a", "b", "c" }} -> { { "c", "b", "a" }}
]==]
function export.reverse(t)
	checkType("reverse", 1, t, "table")
	-- Not safe to use #t, as it can be unpredictable if there is a hash part.
	local ret, base = {}, 0
	repeat
		base = base + 1
	until t[base] == nil
	for i = base - 1, 1, -1 do
		ret[base - i] = t[i]
	end
	return ret
end

function export.reverseConcat(t, sep, i, j)
	return concat(export.reverse(t), sep, i, j)
end

--[==[
Invert an array. For example, {invert({ "a", "b", "c" })} -> { { a = 1, b = 2, c = 3 }}
]==]
function export.invert(array)
	checkType("invert", 1, array, "table")

	local map = {}
	for i, v in ipairs(array) do
		map[v] = i
	end

	return map
end

--[==[
Convert `list` (a table with a list of values) into a set (a table where those values are keys instead). This is a useful
way to create a fast lookup table, since looking up a table key is much, much faster than iterating over the whole list
to see if it contains a given value.

By default, each item is given the value true. If the optional parameter `value` is a function or functor, then the value
for each item is determined by calling it with the item key as the first parameter, plus any additional arguments passed
to {listToSet}; if value is anything else, then it is used as the fixed value for every item.
]==]
function export.listToSet(list, value, ...)
	checkType("listToSet", 1, list, "table")
	local set, i = {}, 0
	if value == nil then
		value = true
	elseif is_callable(value) then
		-- Separate loop avoids an "is callable" lookup each iteration.
		while true do
			i = i + 1
			local item = list[i]
			if item == nil then
				return set
			end
			set[item] = value(item, ...)
		end
	end
	while true do
		i = i + 1
		local item = list[i]
		if item == nil then
			return set
		end
		set[item] = value
	end
end

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

	local i = 0
	for _ in pairs(t) do
		i = i + 1
		if t[i] == nil then
			return false
		end
	end
	return true
end

--[==[
Add a list of aliases for a given key to a table. The aliases must be given as a table.
]==]
function export.alias(t, k, aliases)
	for _, alias in pairs(aliases) do
		t[alias] = t[k]
	end
end

return export