Module:table: Difference between revisions

--[==[ intro:

This module provides functions for dealing with Lua tables. All of them, except for two helper functions, take a table

as their first argument.

  consecutive integers starting at {1}):

Commons, but in the course of time this module has been almost completely rewritten, with many new functions added. The

Wiktionary.

]==]

local load_module = "Module:load"

local math_module = "Module:math"

local table = table

local signed_index -- defined as export.signedIndex

local table_len -- defined as export.length

local type = type

--[==[

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_integer(...)

is_integer = require(math_module).is_integer

return is_integer(...)

local function safe_require(...)

safe_require = require(load_module).safe_require

return safe_require(...)

--[==[

Given an array and a signed index, returns the true table index. If the signed index is negative, the array will be counted from the end, where {-1} is the highest index in the array; otherwise, the returned index will be the same. To aid optimization, the first argument may be a number representing the array length instead of the array itself; this is useful when the array length is already known, as it avoids recalculating it each time this function is called.]==]

function export.signedIndex(t, k)

if not is_integer(k) then

error("index must be an integer")

return k < 0 and (type(t) == "table" and table_len(t) or t) + k + 1 or k

--[==[

An iterator which works like `pairs`, but ignores any `__pairs` metamethod.]==]

function export.rawPairs(t)

return next, t, nil

--[==[

An iterator which works like `ipairs`, but ignores any `__ipairs` metamethod.]==]

function export.rawIpairs(t)

return ipairs_default_iter, t, 0

--[==[

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

repeat

return n - 1

local function getIteratorValues(i, j , step, t_len)

i, j = i and signed_index(t_len, i), j and signed_index(t_len, j)

if step == nil then

i, j = i or 1, j or t_len

return i, j, j < i and -1 or 1

elseif step == 0 or not is_integer(step) then

error("step must be a non-zero integer")

elseif step < 0 then

return i or t_len, j or 1, step

--[==[

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, _, v) return a + v end)} will return the sum of `array`.

* `i`: start index; negative values count from the end of the array

* `j`: end index; negative values count from the end of the array

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).

# 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.reduce(t, func, i, j, step)

i, j, step = getIteratorValues(i, j, step, table_len(t))

local ret = t[i]

for k = i + step, j, step do

ret = func(ret, k, t[k])

local function replace(t, func, i, j, step, generate)

local t_len = table_len(t)

-- Normalized i, j and step, based on the inputs.

local norm_i, norm_j, norm_step = getIteratorValues(i, j, step, t_len)

if norm_step > 0 then

i, j, step = 1, t_len, 1

i, j, step = t_len, 1, -1

-- "Signed" variables are multiplied by -1 if `step` is negative.

local t_new, signed_i, signed_j = generate and {} or t, norm_i * step, norm_j * step

for k = i, j, step do

-- Replace the values iff they're within the i to j range and `step` wouldn't skip the key.

-- Note: i > j if `step` is positive; i < j if `step` is negative. Otherwise, the range is empty.

local signed_k = k * step

if signed_k >= signed_i and signed_k <= signed_j and (k - norm_i) % norm_step == 0 then

t_new[k] = func(k, t[k])

-- Otherwise, add the existing value if `generate` is set.

elseif generate then

t_new[k] = t[k]

return t_new

--[==[

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`), replacing the relevant values with the result. For example,

{apply(array, function(_, v) return 2 * v end)} will double each member of the array.

* `i`: start index; negative values count from the end of the array

* `j`: end index; negative values count from the end of the array

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, step=-1 results in backward iteration from the end to the 3rd last index.]==]

function export.apply(t, func, i, j, step)

return replace(t, func, i, j, step, false)

--[==[

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 a shallow copy of the original array with the relevant values replaced. For example,

{generate(array, function(_, v) return 2 * v end)} will return a new array in which each value has been doubled.

* `i`: start index; negative values count from the end of the array

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).

 

# 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.generate(t, func, i, j, step)

return replace(t, func, i, j, step, true)

--[==[

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)

i, j, step = getIteratorValues(i, j, step, table_len(t))

if not func(k, t[k]) then

return false

--[==[

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.

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).

# 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)

i, j, step = getIteratorValues(i, j, step, table_len(t))

for k = i, j, step do

if not not (func(k, t[k])) then

return true

--[==[

Joins an array with serial comma and serial conjunction, normally {"and"}. An improvement on {mw.text.listToText},

* `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.

* `dump`: Each item will be serialized with {mw.dumpObject}. For warnings and error messages.]==]

-- If the `dump` option is set, determine the table length as part of the

-- dump loop, instead of calling `table_len` separately.

local length

if options and options.dump then

local i, item = 1, seq[1]

if item ~= nil then

local dumped = {}

i = i + 1

item = seq[i]

seq = dumped

 

return seq[1]

local conj = options and options.conj

if conj == nil then

conj = "and"

if length == 2 then

return seq[1] .. " " .. conj .. " " .. seq[2]

local punc, dont_tag

if options then

punc = options.punc

dont_tag = options.dontTag

punc = ","

end

comma = "" -- since by default the serial comma doesn't display, when we can't tag we shouldn't display it.

conj = " " .. conj .. " "

else

comma = "<span class=\"serial-comma\">" .. punc .. "</span>"

conj = "<span class=\"serial-and\"> " .. conj .. "</span> "

return concat(seq, punc .. " ", 1, length - 1) .. comma .. conj .. seq[length]

--[==[

A function which works like `table.concat`, but respects any `__index` metamethod. This is useful for data loaded via `mw.loadData`.]==]

function export.concat(t, sep, i, j)

local list, k = {}, 0

while true do

k = k + 1

local v = t[k]

if v == nil then

return concat(list, sep, i, j)

--[==[

Add a list of aliases for a given key to a table. The aliases must be given as a table.]==]

 

return submodule

 

return setmetatable(export, mt)