Module: gears.table

Table module for gears.

Examples

Using cycle_value, you can cycle through values in a table. When the end of the table is reached, cycle_value loops around to the beginning.

Usage example output:

Usage:

    local res = {"a", "b", "c", "d", "e"}
for i=1, #res do
    local k = res[i]
    local v = gears.table.cycle_value(res, k, 1)
    print(v)
end

Functions

gtable.count (t) Returns a set where each value if t is a key of the set.

Static module functions

gears.table.join (...) -> table Join all tables given as arguments.
gears.table.crush (target, source[, raw=false]) -> table Override elements in the target table with values from the source table.
gears.table.from_sparse (t) -> table Pack all elements with an integer key into a new table.
gears.table.hasitem (t, item) -> string or number or nil Check if a table has an item and return its key.
gears.table.find_keys (t, matcher[, ordered=false[, max=nil]]) -> table or nil Get all matching table keys for a matcher function.
gears.table.find_first_key (t, matcher[, ordered=false]) -> () Find the first key that matches a function.
gears.table.keys (t) -> table Get a sorted table with all keys from a table.
gears.table.count_keys (t) -> number Get the number of keys in a table, both integer and string indicies.
gears.table.keys_filter (t, ...) -> table Filter a table's keys for certain content type.
gears.table.reverse (t) -> table Reverse a table.
gears.table.clone (t[, deep=true]) -> table Clone a table.
gears.table.cycle_value (t, value[, step_size=1[, filter=nil[, start_at=1]]]) -> number or nil Get the next (or previous) value from a table and cycle if necessary.
gears.table.iterate (t[, filter=nil], start[, step_size=1[, cycle=false]]) Iterate over a table.
gears.table.merge (target, source) -> table Merge items from the source table into the target table.
gears.table.diff_merge (target, new, identifier[, merger]) -> (table, table, table, table) Update the target table with entries from the new table.
gears.table.map (f, tbl) -> table Map a function to a table.


Functions

Methods
gtable.count (t)
Returns a set where each value if t is a key of the set.

Parameters:

  • t table The input table.

Returns:

    table A table with all values of t as key and the number of instance as value.

Static module functions

gears.table.join (...) -> table
Join all tables given as arguments. This will iterate over all tables and insert their entries into a new table.

Parameters:

  • ... table Tables to join.

Returns:

    table A new table containing all entries from the arguments.
gears.table.crush (target, source[, raw=false]) -> table
Override elements in the target table with values from the source table.

Note that this method doesn't copy entries found in __index. Nested tables are copied by reference and not recursed into.

Parameters:

  • target table The target table. Values from source will be copied into this table.
  • source table The source table. Its values will be copied into target.
  • raw bool If true, values will be assigned with rawset. This will bypass metamethods on target. (default false)

Returns:

    table The target table.
gears.table.from_sparse (t) -> table
Pack all elements with an integer key into a new table. While both lua and luajit implement __len over sparse tables, the standard defines it as an implementation detail.

This function removes any entries with non-numeric keys.

Parameters:

  • t table A potentially sparse table.

Returns:

    table A packed table with only numeric keys.
gears.table.hasitem (t, item) -> string or number or nil
Check if a table has an item and return its key.

Parameters:

  • t table The table.
  • item The item to look for in values of the table.

Returns:

    string or number The key of the item.

Or

    nil
gears.table.find_keys (t, matcher[, ordered=false[, max=nil]]) -> table or nil
Get all matching table keys for a matcher function.

Parameters:

  • t table The table.
  • matcher function A function taking the key and value as arguments and returning a boolean.
  • ordered boolean If true, only look for continuous numeric keys. (default false)
  • max number The maximum number of entries to find. (default nil)

Returns:

    table or nil An ordered table with all the keys or nil if none were found.
gears.table.find_first_key (t, matcher[, ordered=false]) -> ()
Find the first key that matches a function.

Parameters:

  • t table The table.
  • matcher function A function taking the key and value as arguments and returning a boolean.
  • ordered boolean If true, only look for continuous numeric keys. (default false)

Returns:

    The table key or nil.
gears.table.keys (t) -> table
Get a sorted table with all keys from a table.

Parameters:

  • t table The table for which the keys to get.

Returns:

    table A table with keys.
gears.table.count_keys (t) -> number
Get the number of keys in a table, both integer and string indicies.

This is functionally equivalent, but faster than #gears.table.keys(t).

Usage example output:

Parameters:

  • t table The table for which to count the keys.

Returns:

    number The number of keys in the table.

Usage:

    local tab = { 1, nil, "a", "b", foo = "bar" }
local count = gears.table.count_keys(tab)
print("The table has " .. count .. " keys")
gears.table.keys_filter (t, ...) -> table
Filter a table's keys for certain content type.

Parameters:

  • t table The table to retrieve the keys for.
  • ... string The types to look for.

Returns:

    table A filtered table.
gears.table.reverse (t) -> table
Reverse a table.

Parameters:

  • t table The table to reverse.

Returns:

    table A reversed table.
gears.table.clone (t[, deep=true]) -> table
Clone a table.

Parameters:

  • t table The table to clone.
  • deep bool If true, recurse into nested tables to create a deep clone. (default true)

Returns:

    table A clone of t.
gears.table.cycle_value (t, value[, step_size=1[, filter=nil[, start_at=1]]]) -> number or nil
Get the next (or previous) value from a table and cycle if necessary.

If the table contains the same value multiple type (aka, is not a set), the first_index has to be specified.

Parameters:

  • t table The input table.
  • value The start value. Must be an element of the input table t.
  • step_size number The amount to increment the index by. When this is negative, the function will cycle through the table backwards. (default 1)
  • filter function An optional filter function. It receives a value from the table as parameter and should return a boolean. If it returns false, the value is skipped and cycle_value tries the next one. (default nil)
  • start_at number Where to start the lookup from. (default 1)

Returns:

  1. The next eligible value. If no value matches, nil is returned.
  2. number or nil If a value is found, this is its index within the input table.
gears.table.iterate (t[, filter=nil], start[, step_size=1[, cycle=false]])
Iterate over a table.

Returns an iterator to cycle through all elements of a table that match a given criteria, starting from the first element or the given index.

Parameters:

  • t table 
      the table to iterate
  • filter function a function that returns true to indicate a positive match (default nil)
  • start number what index to start iterating from. Default is 1 (=> start of the table)
  • step_size number A positive or negative quantity of element to iterate in each step. (default 1)
  • cycle boolean Allow number greater than #t and smaller than one in the start argument and assume it just cycled many time over the table. (default false)
gears.table.merge (target, source) -> table
Merge items from the source table into the target table.

Note that this only considers the array part of source (same semantics as ipairs). Nested tables are copied by reference and not recursed into.

Parameters:

  • target table The target table. Values from source will be copied into this table.
  • source table The source table. Its values will be copied into target.

Returns:

    table The target table.
gears.table.diff_merge (target, new, identifier[, merger]) -> (table, table, table, table)
Update the target table with entries from the new table.

Compared to gears.table.merge, this version is intended to work using both an identifier function and a merger function. This works only for indexed tables.

The main use case is when changing the table reference is not possible or when the target contains additional content that must be kept.

Note that calling this function involve a lot of looping and should not be done often.

Parameters:

  • target table The table to modify.
  • new table The table which contains the new content.
  • identifier function A function which take the table entry (either from the target or new table) and return an unique identifier. The identifier type isn't important as long as == works to compare them.
  • merger function A function takes the entry to modify as first parameter and the new entry as second. The function must return the merged value. If none is provided, there is no attempt to merge the content. (optional)

Returns:

  1. table The target table (for daisy chaining).
  2. table The new entries.
  3. table The removed entries.
  4. table The updated entries.

Usage:

    local output, added, removed, updated = gears.table.diff_merge(
    output, input, function(v) return v.id end, gears.table.crush,
)
gears.table.map (f, tbl) -> table
Map a function to a table.

The function is applied to each value in the table, returning a modified table.

Parameters:

  • f function The function to be applied to each value in the table.
  • tbl table The container table whose values will be operated on.

Returns:

    table
generated by LDoc 1.4.6 Last updated 2021-11-13 00:35:50