Module: gears.table

Table module for gears

Static module functions

gears.table.join (...) Join all tables given as arguments.
gears.table.crush (t, set[, raw=false]) Override elements in the first table by the one in the second.
gears.table.from_sparse (t) Pack all elements with an integer key into a new table.
gears.table.hasitem (t, item) Check if a table has an item and return its key.
gears.table.find_keys (t, matcher[, ordered=false[, max=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) Get a sorted table with all integer keys from a table.
gears.table.keys_filter (t, ...) Filter a table’s keys for certain content type.
gears.table.reverse (t) Reverse a table.
gears.table.clone (t[, deep=true]) Clone a table.
gears.table.iterate (t, filter, start) Iterate over a table.
gears.table.merge (t, set) Merge items from one table to another one.
gears.table.diff_merge (target, new, identifier[, merger]) Update the target table with entries from the new table.
gears.table.map (f, tbl) Map a function to a table.


Static module functions

gears.table.join (...)
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 (t, set[, raw=false])
Override elements in the first table by the one in the second.

Note that this method doesn’t copy entries found in __index.

Parameters:

  • t table the table to be overriden
  • set table the table used to override members of t
  • raw bool Use rawset (avoid the metatable) (default false)

Returns:

    table t (for convenience)
gears.table.from_sparse (t)
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)
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]])
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)
Get a sorted table with all integer keys from a table.

Parameters:

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

Returns:

    table A table with keys.
gears.table.keys_filter (t, ...)
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)
Reverse a table.

Parameters:

  • t table The table to reverse.

Returns:

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

Parameters:

  • t table The table to clone.
  • deep bool Create a deep clone? (default true)

Returns:

    table A clone of t.
gears.table.iterate (t, filter, start)
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 func A function that returns true to indicate a positive match.
  • start int Index to start iterating from. Default is 1 (=> start of the table). (default 1)

Returns:

    func
gears.table.merge (t, set)
Merge items from one table to another one.

Parameters:

  • t table The container table
  • set table The mixin table.

Returns:

    table (for convenience).
gears.table.diff_merge (target, new, identifier[, merger])
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)
Map a function to a table.

The function is applied to each value on 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 2030-01-01 00:00:00