Module:table
Documentation for this module may be created at Module:table/doc
--[[
------------------------------------------------------------------------------------
-- 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. --
------------------------------------------------------------------------------------
--]]
local export = {}
local collation_module = "Module:collation"
local function_module = "Module:fun"
local table = table
local concat = table.concat
local contains -- defined as export.contains
local deep_copy -- defined as export.deepcopy
local deep_equals -- defined as export.deepEquals
local format = string.format
local getmetatable = getmetatable
local index_pairs -- defined as export.indexPairs
local insert = table.insert
local insert_if_not -- defined as export.insertIfNot
local ipairs = ipairs
local ipairs_default_iter = ipairs{export}
local is_positive_integer -- defined as export.isPositiveInteger
local keys_to_list -- defined as export.keysToList
local next = next
local num_keys -- defined as export.numKeys
local pairs = pairs
local pcall = pcall
local rawequal = rawequal
local rawget = rawget
local require = require
local select = select
local setmetatable = setmetatable
local sort = table.sort
local sparse_ipairs -- defined as export.sparseIpairs
local table_len -- defined as export.length
local table_reverse -- defined as export.reverse
local type = type
local infinity = math.huge
--[==[
Loaders for functions in other modules, which overwrite themselves with the target function when called. This ensures modules are only loaded when needed, retains the speed/convenience of locally-declared pre-loaded functions, and has no overhead after the first call, since the target functions are called directly in any subsequent calls.]==]
local function is_callable(...)
is_callable = require(function_module).is_callable
return is_callable(...)
end
local function string_sort(...)
string_sort = require(collation_module).string_sort
return string_sort(...)
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 index_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
deep_copy = export.deepcopy
end
--[==[
Append any number of tables together and returns the result. Compare the Lisp expression {(append list1 list2 ...)}.]==]
function export.append(...)
local args, list, n = {...}, {}, 0
for i = 1, select("#", ...) do
local t, j = args[i], 0
while true do
j = j + 1
local v = t[j]
if v == nil then
break
end
n = n + 1
list[n] = v
end
end
return list
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 i, insert_if_not_option = 0, options and options.insertIfNot
while true do
i = i + 1
local item = new_items[i]
if item == nil then
return
elseif insert_if_not_option then
insert_if_not(list, item, options)
else
insert(list, item)
end
end
end
do
local pos_nan, neg_nan
--[==[
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.]==]
function export.removeDuplicates(t)
local list, seen, i, n = {}, {}, 0, 0
while true do
i = i + 1
local v = t[i]
if v == nil then
return list
end
local memo_key
if v == v then
memo_key = v
-- NaN
elseif format("%f", v) == "nan" then
if not pos_nan then
pos_nan = {}
end
memo_key = pos_nan
-- -NaN
else
if not neg_nan then
neg_nan = {}
end
memo_key = neg_nan
end
if not seen[memo_key] then
n = n + 1
list[n], seen[memo_key] = v, true
end
end
return list
end
end
--[==[
Given a table, return an array containing all positive integer keys, sorted in numerical order.]==]
function export.numKeys(t)
local nums, i = {}, 0
for k in index_pairs(t) do
if is_positive_integer(k) then
i = i + 1
nums[i] = k
end
end
sort(nums)
return nums
end
num_keys = export.numKeys
--[==[
Return the highest positive integer index of a table or array that possibly has holes in it, or otherwise 0 if no positive integer keys are found. Note that this differs from `table.maxn`, which returns the highest positive numerical index, even if it is not an integer.]==]
function export.maxIndex(t)
local max = 0
for k in index_pairs(t) do
if k > max then
max = k
end
end
return is_positive_integer(max) and max or 0
end
--[==[
This takes a list with one or more nil values, and removes the nil values while preserving the order, so that the list can be safely traversed with ipairs.]==]
function export.compressSparseArray(t)
local list, keys, i = {}, num_keys(t), 0
while true do
i = i + 1
local k = keys[i]
if k == nil then
return list
end
list[i] = t[k]
end
end
do
local current
--[==[
An iterator which works like `pairs`, except that it also respects the `__index` metamethod. This works by iterating over the input table with `pairs`, followed by the table at its `__index` metamethod (if any). This is then repeated for that table's `__index` table and so on, with any repeated keys being skipped over, until there are no more tables, or a table repeats (so as to prevent an infinite loop). If `__index` is a function, however, then it is ignored, since there is no way to iterate over its return values.
A `__pairs` metamethod will be respected for any given table instead of iterating over it directly, but these will be ignored if the `raw` flag is set.
Note: this function can be used as a `__pairs` metamethod. In such cases, it does not call itself, since this would cause an infinite loop, so it treats the relevant table as having no `__pairs` metamethod. Other `__pairs` metamethods on subsequent tables will still be respected.]==]
function export.indexPairs(t, raw)
-- If there's no metatable, result is identical to `pairs`.
-- To prevent infinite loops, act like `pairs` if `current` is set with `t`, which means this function is being used as a __pairs metamethod.
if current and current[t] or getmetatable(t) == nil then
return next, t, nil
end
-- `seen_k` memoizes keys, as they should never repeat; `seen_t` memoizes tables iterated over.
local seen_k, seen_t, iterate, iter, state = {}, {}
local function catch_values(k, ...)
if k ~= nil then
-- If a repeated key is found, skip and iterate again.
if seen_k[k] then
return catch_values(iter(state, k))
end
seen_k[k] = true
return k, ...
end
-- If there's an __index metamethod, iterate over it iff it's a table not already seen before. Otherwise, return.
local mt = getmetatable(t)
-- `mt` might not be a table if __metatable is used.
if mt == nil or type(mt) ~= "table" then
return nil
end
t = rawget(mt, "__index")
if t == nil or type(t) ~= "table" or seen_t[t] then
return nil
end
seen_t[t], iter = true, nil
return iterate()
end
function iterate(_, k)
if iter ~= nil then
-- Metamethods can return an arbitrary number of values, so catch them to avoid creating a table.
return catch_values(iter(state, k))
end
-- If `raw` is set, use `next`.
if raw then
iter, state, k = next, t, nil
-- Otherwise, call `pairs`, setting `current` with `t` so that export.indexPairs knows to return `next` if it's being used as a metamethod, as this prevents infinite loops. `t` is then unset, so that `current` doesn't get polluted if the loop breaks early.
else
if not current then
current = {}
end
current[t] = true
-- Use `pcall`, so that `t` can always be unset from `current`.
local success
success, iter, state, k = pcall(pairs, t)
current[t] = nil
-- If there was an error, raise it.
if not success then
error(iter)
end
end
return catch_values(iter(state, k))
end
return iterate
end
index_pairs = export.indexPairs
end
do
local current
local function ipairs_func(t, i)
i = i + 1
local v = t[i]
if v ~= nil then
return i, v
end
end
--[==[
An iterator which works like `ipairs`, except that it also respects the `__index` metamethod. This works by looking up values in the table, iterating integers from key `1` until no value is found.
An `__ipairs` metamethod for the input table will be respected, but it will be ignored if the `raw` flag is set.
Note: this function can be used as an `__ipairs` metamethod. In such cases, it does not call itself, since this would cause an infinite loop, so it treats the input table as having no `__ipairs` metamethod.]==]
function export.indexIpairs(t, raw)
-- If there's no metatable, result is identical to `ipairs`.
if getmetatable(t) == nil then
if not current then
current = {}
end
return ipairs_default_iter, t, 0
-- To prevent infinite loops, don't check for a metamethod if `current` is set with `t`, which means this function is being used as an __ipairs metamethod. Also if `raw` is set.
elseif raw or current and current[t] then
return ipairs_func, t, 0
elseif not current then
current = {}
end
current[t] = true
-- Use `pcall`, so that `t` can always be unset from `current`.
local success, iter, state, k = pcall(ipairs, t)
current[t] = nil
-- If there was an error, raise it.
if not success then
error(iter)
-- If `iter` is just the default `ipairs` iterator, then use `ipairs_func`. There could still be an __ipairs metamethod, but it's safe to use `ipairs_func` on whatever `state` and `k` values were returned.
elseif iter == ipairs_default_iter then
iter = ipairs_func
end
return iter, state, k
end
end
--[==[
This is an iterator for sparse arrays. It can be used like ipairs, but can handle nil values.]==]
function export.sparseIpairs(t)
local keys, i = num_keys(t), 0
return function()
i = i + 1
local k = keys[i]
if k then
return k, t[k]
end
end
end
sparse_ipairs = export.sparseIpairs
--[==[
This returns the size of a key/value pair table. If `raw` is set, then metamethods will be ignored, giving the true table size.
For arrays, it is faster to use `export.length`.]==]
function export.size(t, raw)
local i, iter, state, k = 0
if raw then
iter, state = next, t
else
iter, state, k = index_pairs(t)
end
for _ in iter, state, k 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 a more reliable form of the operator `#`, which can become unpredictable under certain circumstances due to the implementation of tables under the hood in Lua, and therefore should not be used when dealing with arbitrary tables. `#` also does not use metamethods, so will return the wrong value in cases where it is desirable to take these into account (e.g. data loaded via `mw.loadData`). If `raw` is set, then metamethods will be ignored, giving the true table length.
For arrays, this function is faster than `export.size`.]==]
function export.length(t, raw)
local n = 0
if raw then
for i in ipairs_default_iter, t, 0 do
n = i
end
return n
end
repeat
n = n + 1
until t[n] == nil
return n - 1
end
table_len = export.length
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, return the memoized result.
-- This is probably true, but during the laborious check a match failure won't fail the whole check outright, so it could be false.
local memo_a = memo[a]
if memo_a then
local result = memo_a[b]
if result ~= nil then
return result
end
-- To avoid infinite loops, assume the tables being compared are equivalent; this will be corrected if there's a match failure.
memo_a[b] = true
else
memo_a = {[b] = true}
memo[a] = memo_a
end
-- Don't bother checking `memo_b` for `a`, since if these tables had been compared before then `b` would be in `memo_a`.
local memo_b = memo[b]
if memo_b then
memo_b[a] = true
else
memo_b = {[a] = true}
memo[b] = memo_b
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
memo_a[b], memo_b[a] = false, false
return false
end
-- Fast check: iterate over the keys in `a` with `next` (which circumvents metamethods), checking if an equivalent value exists at the same key in `b`. Any tables-as-keys that aren't found in the other table are set aside for the laborious check.
local tablekeys_a, tablekeys_b, kb
for ka, va in next, a do
local vb = rawget(b, ka)
if vb == nil then
-- If `ka` isn't in `b`, `a` and `b` can't be equivalent unless it's a table.
if type(ka) ~= "table" then
memo_a[b], memo_b[a] = false, false
return false
-- Otherwise, `a` and `b` can only be equivalent if `b` has a key that's not in `a` but is equivalent to `ka`.
-- This is found via the laborious check, so set `ka` aside for that.
elseif not tablekeys_a then
tablekeys_a = {}
end
tablekeys_a[ka] = va
-- Otherwise, if `ka` exists in `a` and `b`, `va` and `vb` must be equivalent.
elseif not is_equivalent(va, vb, memo, include_mt) then
memo_a[b], memo_b[a] = false, false
return false
end
-- Iterate over `b` with `next` simultaneously, to check it's the same size and to find any tables-as-keys that need the laborious check.
kb, vb = next(b, kb)
-- Fail if `b` runs out of key/value pairs too early.
if kb == nil then
memo_a[b], memo_b[a] = false, false
return false
-- If `kb` is a table not found in `a`, set it aside for the laborious check.
-- Note: if it is in `a`, it doesn't need the laborious check, since the values will be compared during this loop.
elseif type(kb) == "table" and rawget(a, kb) == nil then
if not tablekeys_b then
tablekeys_b = {}
end
tablekeys_b[kb] = vb
end
end
-- Fail if there are too many key/value pairs in `b`.
if next(b, kb) ~= nil then
memo_a[b], memo_b[a] = false, false
return false
-- If tablekeys_a == tablekeys_b they must be both nil, meaning that neither had tables as keys, so there's nothing left to check.
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
memo_a[b], memo_b[a] = false, false
return false
end
-- Laborious check: for each table-as-key in `tablekeys_a`, iterate over the pool in `tablekeys_b` looking for an equivalent key/value pair. If one if found, end the search and remove the match from `tablekeys_b`, to ensure one-to-one correspondence. If all keys in `tablekeys_a` match, `tablekeys_b` will be empty iff the two are equivalent.
for ka, va in next, tablekeys_a do
local kb
while true do
local vb
kb, vb = next(tablekeys_b, kb)
-- Fail if `tablekeys_b` runs out of keys, as `ka` still hasn't matched.
if kb == nil then
memo_a[b], memo_b[a] = false, false
return false
-- Keys/value pairs must be equivalent in order to match.
elseif (
-- Check values first for speed, since they might not be tables.
is_equivalent(va, vb, memo, include_mt) and
is_equivalent(ka, kb, memo, include_mt)
) then
-- Remove matched key from the pool, and break the inner loop.
tablekeys_b[kb] = nil
break
end
end
end
-- Success iff `tablekeys_b` is now empty.
local result = next(tablekeys_b) == nil
if not result then
memo_a[b], memo_b[a] = false, false
end
return result
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
deep_equals = export.deepEquals
end
do
local function get_nested(t, k, ...)
if t == nil then
return nil
elseif select("#", ...) ~= 0 then
return get_nested(t[k], ...)
end
return t[k]
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(t, ...)
if t == nil or select("#", ...) == 0 then
error("Must provide a table and at least one key.")
end
return get_nested(t, ...)
end
end
do
local function set_nested(t, v, k, ...)
if select("#", ...) == 0 then
t[k] = v
return
end
local next_t = t[k]
if next_t == nil then
-- If there's no next table while setting nil, there's nothing more to do.
if v == nil then
return
end
next_t = {}
t[k] = next_t
end
return set_nested(next_t, v, ...)
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(t, ...)
if t == nil or select("#", ...) < 2 then
error("Must provide a table and at least one key.")
end
return set_nested(t, ...)
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)
if options and options.key then
x = options.key(x)
end
local i = 0
while true do
i = i + 1
local v = list[i]
if v == nil then
return false
elseif options and options.key then
v = options.key(v)
end
if deep_equals(v, x) then
return true
end
end
end
contains = export.contains
--[==[
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)
for _, v in index_pairs(tbl) do
if deep_equals(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)
if type(options) == "number" then
options = {pos = options}
end
if options and options.combine then
local new_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_key = options.key(new_item)
else
new_key = new_item
end
local i = 0
while true do
i = i + 1
local item, key = list[i]
if item == nil then
break
elseif options.key then
key = options.key(item)
else
key = item
end
if deep_equals(key, new_key) then
local retval = options.combine(item, new_item, i)
if retval ~= nil then
list[i] = retval
end
return false
end
end
elseif contains(list, new_item, options) then
return false
end
local pos = options and options.pos
if pos then
insert(list, pos, new_item)
else
insert(list, new_item)
end
end
insert_if_not = export.insertIfNot
--[==[
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)
for key, value in index_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 default_sort(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, `export.numKeys` is probably faster.]==]
function export.keysToList(t, keySort)
local list, i = {}, 0
for key in index_pairs(t) do
i = i + 1
list[i] = key
end
-- Use specified sort function, or otherwise default_sort.
sort(list, keySort or default_sort)
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, `export.sparseIpairs` is probably faster.]==]
function export.sortedPairs(t, keySort)
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
-- Loader.
local function really_reverse_ipairs(...)
really_reverse_ipairs = require(function_module).reverseIter(ipairs)
return really_reverse_ipairs(...)
end
local function reverse_ipairs_func(t, i)
if i > 1 then
i = i - 1
-- Use rawget and check `v` is not nil, in case `t` has been modified during the loop.
local v = rawget(t, i)
if v ~= nil then
return i, v
end
end
end
function export.reverseIpairs(t)
-- If there's no metatable, it's faster and cheaper to iterate backwards over the array part via direct table access.
-- Note: not safe to use #t for the initial value of `i`, as it can be unpredictable if there's a hash part.
if getmetatable(t) == nil then
return reverse_ipairs_func, t, table_len(t, true) + 1
end
-- Otherwise, there could be an __ipairs metamethod (which may be hidden if the real metatable uses __metatable), so we have to assume there is one.
-- These can return arbitrary values (i.e. the first value might not be `i`), so use reverseIter in [[Module:fun]] to guarantee accuracy.
return really_reverse_ipairs(t)
end
end
local function getIteratorValues(i, j , step, t_len)
i = (i and i < 0 and t_len - i + 1) or i or (step and step < 0 and t_len) or 1
j = (j and j < 0 and t_len - j + 1) or j or (step and step < 0 and 1) or t_len
step = step or (j < i and -1) or 1
if (
i == 0 or i % 1 ~= 0 or
j == 0 or j % 1 ~= 0 or
step == 0 or step % 1 ~= 0
) then
error("Arguments i, j and step must be non-zero integers.")
end
return i, j, step
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
* `step`: 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 step results in forward iteration from the start to the end in steps of 1 (the default).
# step=-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. step=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, step=-1 results in backward iteration from the end to the 3rd last index.
Note: directionality generally only matters for `reduce`, but values of step > 1 (or step < -1) still affect the return value
of `apply`.]==]
function export.reduce(t, func, i, j, step)
local t_len = table_len(t)
i, j, step = getIteratorValues(i, j , step, t_len)
local ret = t[i]
for k = i + step, j, step do
ret = func(ret, k, t[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
* `step`: 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 step results in forward iteration from the start to the end in steps of 1 (the default).
# step=-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. step=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, step=-1 results in backward iteration from the end to the 3rd last index.
Note: directionality makes the most difference for `reduce`, but values of step > 1 (or step < -1) still affect the return
value of `apply`.]==]
function export.apply(t, func, i, j, step)
local t_new = deep_copy(t)
local t_new_len = table_len(t_new)
i, j, step = getIteratorValues(i, j , step, t_new_len)
for k = i, j, step do
t_new[k] = func(k, t_new[k])
end
return t_new
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
* `step`: 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 step results in forward iteration from the start to the end in steps of 1 (the default).
# step=-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. step=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, step=-1 results in backward iteration from the end to the 3rd last index.]==]
function export.all(t, func, i, j, step)
local t_len = table_len(t)
i, j, step = getIteratorValues(i, j , step, t_len)
for k = i, j, step do
if not func(k, t[k]) then
return false
end
end
return true
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
* `step`: 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 step results in forward iteration from the start to the end in steps of 1 (the default).
# step=-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. step=-1).
# j=-3 results in forward iteration from the start to the 3rd last index.
# j=-3, step=-1 results in backward iteration from the end to the 3rd last index.]==]
function export.any(t, func, i, j, step)
local t_len = table_len(t)
i, j, step = getIteratorValues(i, j , step, t_len)
for k = i, j, step do
if not not (func(k, t[k])) then
return true
end
end
return false
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"}.
* `punc`: Punctuation to use; default to {","}.
* `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 length = table_len(seq)
if length == 0 then
return ""
elseif length == 1 then
return seq[1]
end
if length == 2 then
return seq[1] .. " " .. (options and options.conj or "and") .. " " .. seq[2]
end
local conj, punc, dont_tag
if options then
conj = options.conj or "and"
punc = options.punc or ","
dont_tag = options.dontTag
else
conj, punc = "and", ","
end
local comma
if dont_tag then
comma = punc
conj = " " .. conj .. " "
else
comma = "<span class=\"serial-comma\">" .. punc .. "</span>"
conj = "<span class=\"serial-and\"> " .. conj .. "</span> "
end
return concat(seq, punc .. " ", 1, length - 1) .. comma .. conj .. seq[length]
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, list_i = {}, 0
for _, v in sparse_ipairs(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)
local list, t_len = {}, table_len(t)
for i = t_len, 1, -1 do
list[t_len - i + 1] = t[i]
end
return list
end
table_reverse = export.reverse
function export.reverseConcat(t, sep, i, j)
return concat(table_reverse(t), sep, i, j)
end
--[==[
Invert a list. For example, {invert({ "a", "b", "c" })} -> { { a = 1, b = 2, c = 3 }}]==]
function export.invert(list)
local map, i = {}, 0
while true do
i = i + 1
local v = list[i]
if v == nil then
return map
end
map[v] = i
end
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 as an iterator, with the item's index in the list as the first argument, its key
as the second, 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, ...)
local set, i, callable = {}, 0
if value == nil then
value = true
else
callable = is_callable(value)
end
while true do
i = i + 1
local item = list[i]
if item == nil then
return set
end
if callable then
set[item] = value(i, item, ...)
else
set[item] = value
end
end
end
--[==[
Return true if all keys in the table are consecutive integers starting at 1.]==]
function export.isArray(t)
local i = 0
for _ in index_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 index_pairs(aliases) do
t[alias] = t[k]
end
end
return export