Modulo:Wikilib/tables

Questo modulo non ha ancora un manuale. Creane uno!

-- luacheck: new_globals table
-- Library table functions

local t = {}

-- Check whether a given value is an integer
local function isint(val)
    return type(val) == "number" and val == math.floor(val)
end

-- Returns true only if a is lexigographically greater than b
local function minor(a, b)
    if not b then
        return true
    end

    -- Converting to number for better comparison (eg. '01' and 1)
    local nA, nB = tonumber(a), tonumber(b)
    if nA and nB then
        return nA < nB
    end

    return tostring(a) < tostring(b)
end

--[[

Since lua5.2 unpack has been moved to table.unpack, this allows migration with
older versions on PCW.

--]]
table.unpack = table.unpack or unpack

--[[

Returns true if all of the elements in the list satisties a predicate.

The predicate function takes the value as the first argument, then the key;
usual key-value order is reversed because the key is often unnecessary, and
having it last leads to nicer syntax in the call site.

TODO: refactoring to use just built-ins

--]]
table.all = function(tab, funct, iter)
    return table.fold(tab, true, function(acc, value, key)
        return funct(value, key) and acc
    end, iter)
end

t.all = table.all

--[[

Returns true if at least one of the elements in the list satisties a predicate.

The predicate function takes the value as the first argument, then the key;
usual key-value order is reversed because the key is often unnecessary, and
having it last leads to nicer syntax in the call site.

TODO: refactoring to use just built-ins

--]]
table.any = function(tab, funct, iter)
    return table.fold(tab, false, function(acc, value, key)
        return funct(value, key) or acc
    end, iter)
end
t.any = table.any

--[[

Deep clones a table. It intentionally doesn't clone the metatables, as that's
the job of mw.clone.

--]]
table.copy = function(value)
    local dest = {}
    for k, v in pairs(value) do
        dest[k] = type(v) == "table" and table.copy(v) or v
    end
    return dest
end
t.copy = table.copy

--[[

Merges two tables into a new one. Integer indices of the second table will
follow the ones of the first. Other indices overwrite the ones of the first
in case of equality, unless the values are tables in both the source tables:
in this case they are merged recursively.

--]]
table.deepMerge = function(tab1, tab2)
    -- stylua: ignore
        -- Better to use mw.clone, so as to keep metatable of items.
    local dest = mw.clone(tab1)

    -- Double loop to keep integer keys sorted
    for _, value in ipairs(tab2) do
        table.insert(dest, value)
    end
    for key, value in pairs(tab2) do
        if not isint(key) then
            if
                dest[key]
                and type(dest[key]) == "table"
                and type(value) == "table"
            then
                dest[key] = table.deepMerge(dest[key], value)
            else
                dest[key] = value
            end
        end
    end
    return dest
end
table.deep_merge = table.deepMerge
t.deep_merge, t.deepMerge = table.deepMerge, table.deepMerge

--[[

Recursive search: looks for a value in a table and possible subtables. Returns
a list of indices, mapping the nesting of tables. This means that the last
index is the one of the element, the second last is the subtable it is found
in, the third last the subtable that contains such table an so on. If the
element is not found, returns nil.

Example:
table.deep_search({'a', {'b', 'c'}}, 'b') --> 2, 1

--]]
table.deepSearch = function(tab, value)
    for k, v in pairs(tab) do
        if v == value then
            return k
        end
        if type(v) == "table" then
            --[[
                If the last list element is not nil, value
                has been found, thus returning
            --]]
            local valueKeys = { table.deepSearch(v, value) }
            if valueKeys[#valueKeys] then
                return k, table.unpack(valueKeys)
            end
        end
    end
    -- No explicit return, thus nil
end
table.deep_search = table.deepSearch
t.deepSearch, t.deep_search = table.deepSearch, table.deepSearch

--[[

Returns true if table is empty, that is it has no values.

--]]
table.empty = function(tab)
    --[[
        next() is a stateless iterator, it doesn't modify the table;
        need to compare to nil as false is also a value
    --]]
    return next(tab) == nil
end
t.empty, t.isEmpty, t.is_empty = table.empty, table.empty, table.empty
table.isEmpty, table.is_empty = table.empty, table.empty

--[[

Returns whether two tables are equal: this means same keys mapped to same
values, where same is the == operator. For the sake of conveniente, it returns
true also for non-table arguments, as long as they computer equals.

--]]
table.equal = function(tab1, tab2)
    --[[
        Arguments are compared directly if:
            - One of them has the __eq metamethod
            - One of them is not a table
    --]]
    local mt1 = getmetatable(tab1)
    local mt2 = getmetatable(tab2)
    if
        mt1 and mt1.__eq
        or mt2 and mt2.__eq
        or type(tab1) ~= "table"
        or type(tab2) ~= "table"
    then
        return tab1 == tab2
    end

    -- Optimization: references to the same table can be assessed equal here
    if tab1 == tab2 then
        return true
    end

    --[[
        If the two tables have different number of items, they aren't equal.

        Furthermore, it covers the cases in which:
            - tab1 is empty, and the upcoming loop doesn't run at all.
            - tab1 is a subset of tab2, not covered by the loop, since only
                tab1 indices are used.
    --]]
    if table.getn(tab1) ~= table.getn(tab2) then
        return false
    end

    for key, value in pairs(tab1) do
        -- Easerie to compare this way, being table.equal very type-safe
        if not table.equal(value, tab2[key]) then
            return false
        end
    end

    return true
end
table.eq = table.equal
t.equal, t.eq = table.equal, table.equal

--[[

Returns a table containing only the elements that satisfy the passed predicate.
Integer keys are compacted, so that standard library functions will still work:
in fact, they don't get along well with "holes" in integer keys. Other keys are
kept unchanged.

The predicate takes as input an element and its key, in this order: in fact,
the key is often unnecessary, and would just clutter the code in these cases.
It returns a boolean: if this is true, the element is kept, else is discarded.

--]]
table.filter = function(tab, cond)
    local dest = {}

    -- Double loop to keep integer keys sorted and compact
    for key, value in ipairs(tab) do
        if cond(value, key) then
            table.insert(dest, value)
        end
    end
    for key, value in pairs(tab) do
        if not isint(key) and cond(value, key) then
            dest[key] = value
        end
    end
    return dest
end
t.filter = table.filter

--[[

Applies a function over all of the elements of a table returned by the passed
iterator. The function is expected to return a list. The lists produced from
the elements are merged together in the same way as table.merge would do. The
iterator defaults to pairs.

The function takes as input an element and its key, in this order: in fact, the
key is often unnecessary, and would just clutter the code in these cases.

--]]
table.flatMap = function(tab, funct, iter)
    iter = iter or pairs

    local dest = {}
    for k, v in iter(tab) do
        dest = table.merge(dest, funct(v, k))
    end
    return dest
end
table.flat_map = table.flatMap
t.flatMap, t.fat_map = table.flatMap, table.flatMap

--[[

Applies a function over all of the elements of a table returned by the passed
iterator. The function is expected to return a list. The lists produced from
the elements are converted to numeric lists: the order of the elements is
determined by the given iterator. These lists are then concatenated together,
in the order the elements of the initial list are returned by the iterator.

The function takes as input an element and its key, in this order: in fact, the
key is often unnecessary, and would just clutter the code in these cases.

--]]
table.flatMapToNum = function(tab, funct, iter)
    iter = iter or pairs

    local dest = {}
    for k, v in iter(tab) do
        for _, value in iter(funct(v, k)) do
            table.insert(dest, value)
        end
    end
    return dest
end
table.flat_map_to_num = table.flatMapToNum
t.flatMapToNum, t.flat_map_to_num = table.flatMapToNum, table.flatMapToNum

-- Returns the input table, but with keys and values swapped.
table.flip = function(tab)
    local flipped = {}
    for key, value in pairs(tab) do
        flipped[value] = key
    end
    return flipped
end
t.flip = table.flip

--[[

Removes one level of nesting in a table-of-tables. Returns a new table.
Non-table elements are left untouched, while subtables are merged in the
returned as they are given by the iterator. The iterator defaults to pairs.

As items are processed in the order they are returned by the iterator, care
should be taken regarding non-integer indices, since their value are overridden
in assignments. For example,

table.flatten({{1, 2, key1 = 5}, {key1 = 9}}, ipairs) --> {1, 2, key1 = 9}
table.flatten({{key1 = 9}, {1, 2, key1 = 5}}, ipairs) --> {1, 2, key1 = 5}

--]]
table.flatten = function(tab, iter)
    iter = iter or pairs

    local dest = {}
    for k, v in iter(tab) do
        if type(v) == "table" then
            dest = table.merge(dest, v)
        else
            dest[k] = v
        end
    end
    return dest
end
t.flatten = table.flatten

--[[

Classic fold on lists: applies a binary function to an accumulator and a
value-key pair taken from the list and returns the final result. The iterator
determines the order elements are scanned, and therefore the final result.

The function takes the accumulator as the first argument, then the value and
finally the key; usual key-value order is reversed because the key is often
unnecessary, and having it last leads to nicer syntax in callers.

--]]
table.fold = function(tab, zero, func, iter)
    iter = iter or pairs

    for key, value in iter(tab) do
        zero = func(zero, value, key)
    end

    return zero
end
t.fold = table.fold

--[[

Returns the number of elements in a table. It should only be used when
Scribunto overrides the # operator so that it doesn't work propertly.
If the second argument is 'num' it only counts items having a integer index,
otherwise it takes all elements in account.

--]]
---@diagnostic disable-next-line: duplicate-set-field
table.getn = function(self, count)
    count = count or "all"

    local n = 0
    local iterator = (count == true or tostring(count):lower() == "num")
            and ipairs
        or pairs

    for _ in iterator(self) do
        n = n + 1
    end

    return n
end
t.getn = table.getn

--[[

Returns a numeric table whose elements are the keys of the passed one, in an
unspecified order.

--]]
table.keys = function(tab)
    local keys = {}
    for key in pairs(tab) do
        table.insert(keys, key)
    end
    return keys
end
t.keys = table.keys

--[[

Applies a function to the elements of a table scanned by the passed iterator.
It returls a table holding the results of the function application, bound to
the same keys as the original items. If no iterator is passed, all elements
are scanned.

The function takes as input an element and its key, in this order: in fact, the
key is often unnecessary, and would just clutter the code in these cases.

--]]
table.map = function(tab, funct, iter)
    iter = iter or pairs

    local dest = {}
    for key, value in iter(tab) do
        dest[key] = funct(value, key)
    end
    return dest
end
t.map = table.map

--[[

Applies a function to the elements of a table scanned by the passed iterator.
It returls a table holding the results of the function application, bound to
integer keys in the order the original elements are returned by the iterator.
If no iterator is passed, all elements are scanned.

The function takes as input an element and its key, in this order: in fact, the
key is often unnecessary, and would just clutter the code in these cases.

--]]
table.mapToNum = function(tab, funct, iter)
    iter = iter or pairs

    local dest = {}
    for key, value in iter(tab) do
        table.insert(dest, funct(value, key))
    end
    return dest
end
table.map_to_num = table.mapToNum
t.mapToNum, t.map_to_num = table.mapToNum, table.mapToNum

--[[

Merges two tables into a new one. Integer indices of the second table will
follow the ones of the first; other indices overwrite the ones of the first
in case of equlity.

--]]
table.merge = function(tab1, tab2)
    -- stylua: ignore
        -- Better to use mw.clone, so as to keep metatable of items.
    local dest = mw.clone(tab1)

    -- Double loop to keep integer keys sorted
    for _, value in ipairs(tab2) do
        table.insert(dest, value)
    end
    for key, value in pairs(tab2) do
        if not isint(key) then
            dest[key] = value
        end
    end
    return dest
end
t.merge = table.merge

-- Predicate search. Returns the index of any value satisfying the predicate,
-- nil if no such values exists in the table. The last parameter iter is
-- optional and specifies the iterator to use (pairs is the default). The
-- predicate takes as arguments the value and the key (the order is reversed
-- because often the key isn't needed)
table.find = function(tab, pred, iter)
    iter = iter or pairs
    for k, v in iter(tab) do
        if pred(v, k) then
            return k
        end
    end
    return nil
end
t.find = table.find

-- Linear search. Returns the index of the passed value if found, else nil.
table.search = function(tab, value)
    for k, v in pairs(tab) do
        if v == value then
            return k
        end
    end
    return nil
end
t.search = table.search

--[[

Returns the elements of a numeric table whose indices are within the specified
range. The end of the range defaults to the end of the source table.

Negative values count from the end of the table. For example, -1 is the last
element, -2 is the second last and so on.

--]]
table.slice = function(tab, from, to)
    local length = #tab

    to = to or length
    if from < 0 then
        from = length + from + 1 -- + because from is negative
    end
    if to < 0 then
        to = length + to + 1 -- + because to is negative
    end

    local dest = {}
    for k = from, to do
        table.insert(dest, tab[k])
    end
    return dest
end
t.slice = table.slice

--[[

Aliases keys in a single table. Arguments:
    - tab: the source table
    - source: list of keys to be aliased
    - dest: list of tables, in which every element contains the aliases
        to its corresponding one in source.

Example:
table.tableKeysAlias(t, {'key', 'key1'}, {{'alias', alias1'},
    {'alias2', 'alias3'}})
Equivalent with assignments:
t.alias, t.alias1 = t.key, t.key
t.alias2, t.alias3 = t.key1, t.key1

--]]
table.tableKeysAlias = function(tab, source, dest)
    for destGroup, sourceKey in ipairs(source) do
        for _, destKey in ipairs(dest[destGroup]) do
            tab[destKey] = tab[sourceKey]
        end
    end
end

table.table_keys_alias, table.keysAlias, table.keys_alias =
    table.tableKeysAlias, table.tableKeysAlias, table.tableKeysAlias
t.tableKeysAlias, t.table_keys_alias, t.keysAlias, t.keys_alias =
    table.tableKeysAlias,
    table.tableKeysAlias,
    table.tableKeysAlias,
    table.tableKeysAlias

--[[

Returns a table with the same items of the input one, but without duplicates.
The keys of repeated elements that are kept are the first in lexicographic
order, unless they are integer: in this case they are compacted to allow
compatibility with standard library functions.

--]]
table.unique = function(tab)
    --[[
        Check is meant to be used to test uniqueness of values: the most
        efficient implementation is to keep values as indices, so that
        uniqueness can be checked with simple table indexing. The values are
        the indices in the final table, so that they can easily be flipped.

        n is used as incremental integer index, to avoid "holes" in the final
        table.
    --]]
    local check, n = {}, 1

    -- Minor is not used as ipairs returns integer keys in ascending order.
    for _, value in ipairs(tab) do
        if not check[value] then
            check[value] = n
            n = n + 1
        end
    end

    for key, value in pairs(tab) do
        if not isint(key) then
            -- If value is not in check, minor returns true, as the second argument
            -- is nil
            if minor(key, check[value]) then
                check[value] = key
            end
        end
    end

    return table.flip(check)
end
t.unique = table.unique

--[[

Returns a numeric table containing the values of the passed table, in the
order they are returned in by the iterator. Such iterator defaults to pairs.

--]]
table.values = function(tab, iter)
    iter = iter or pairs

    local values = {}
    for _, value in iter(tab) do
        table.insert(values, value)
    end
    return values
end
t.values = table.values

--[[

Returns a table from two sources. The items of the new table are obtained by
combining the elements with the same index in the two sources. The default
combinator creates a pair, as a table with two elements.

The used indices are those of the first table returned by the iterator. No
other indices will be considered, especially the extra indices of the second
table. The iterator defaults to pairs.

--]]
table.zip = function(tab1, tab2, combinator, iter)
    combinator = combinator or function(a, b)
        return { a, b }
    end
    iter = iter or pairs

    local res = {}
    for k, v in iter(tab1) do
        res[k] = combinator(v, tab2[k])
    end
    return res
end
t.zip = table.zip

--[[

Returns a table from a source, grouping elements by a function value. The items
of the new table are tables, each corresponding to a group. Groups are
determined by the return value of a function: the result is used as a key for
the group table, that contains all the elements of the passed table that
returned that value.

The getGroup function takes an element and its key, in this order: in fact, the
key is often unnecessary, and would just clutter the code in these cases.

--]]
table.groupBy = function(tab, getGroup, iter)
    iter = iter or pairs

    local groups = {}
    for _, v in iter(tab) do
        local groupID = getGroup(v)
        if not groups[groupID] then
            groups[groupID] = {}
        end
        table.insert(groups[groupID], v)
    end

    return groups
end
t.groupBy = table.groupBy

--[[

Insert into a list all elements from another list. The third parameter is an
optional iterator to specify how to get elements from the second list (default
to ipairs).

--]]
table.append = function(list, elems, iter)
    iter = iter or ipairs
    for _, v in iter(elems) do
        table.insert(list, v)
    end
    return list
end
t.append = table.append

return t