# Module: `gears.table`

Various functions to work with tables.

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

## Static module functions

gears.table.join (...) -> table | Join all tables given as arguments. |
gears.table.crush (target, source, raw) -> 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, max) -> table or nil | Get all matching table keys for a `matcher` function. |
gears.table.find_first_key (t, matcher, ordered) -> () | 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) -> table | Clone a table. |
gears.table.cycle_value (t, value, step_size, filter, start_at) -> number or nil | Get the next (or previous) value from a table and cycle if necessary. |
gears.table.iterate (t, filter, start) -> func | 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. |

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

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  ... |  | table | Tables to join.

  ### Returns:

  table A new table containing all entries from the arguments.
🔗 gears.table.crush (target, source, raw) -> 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:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  target |  | table | The target table. Values from `source` will be copied into this table. | Not applicable
  source |  | table | The source table. Its values will be copied into `target`. | Not applicable
  raw | Optional | bool | If `true`, values will be assigned with rawset. This will bypass metamethods on `target`. | `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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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, max) -> table or nil
  Get all matching table keys for a `matcher` function.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  t |  | table | The table. | Not applicable
  matcher |  | function | A function taking the key and value as arguments and returning a boolean. | Not applicable
  ordered | Optional | boolean | If true, only look for continuous numeric keys. | `false`
  max | Optional | number | The maximum number of entries to find. | `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) -> ()
  Find the first key that matches a function.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  t |  | table | The table. | Not applicable
  matcher |  | function | A function taking the key and value as arguments and returning a boolean. | Not applicable
  ordered | Optional | boolean | If true, only look for continuous numeric keys. | `false`

  ### Returns:

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

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  t |  | table | The table to reverse.

  ### Returns:

  table A reversed table.
🔗 gears.table.clone (t, deep) -> table
  Clone a table.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  t |  | table | The table to clone. | Not applicable
  deep | Optional | bool | If `true`, recurse into nested tables to create a deep clone. | `true`

  ### Returns:

  table A clone of `t`.
🔗 gears.table.cycle_value (t, value, step_size, filter, start_at) -> 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:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  t |  | table | The input table. | Not applicable
  value |  |  | The start value. Must be an element of the input table `t`. | Not applicable
  step_size | Optional | number | The amount to increment the index by. When this is negative, the function will cycle through the table backwards. | `1`
  filter | Optional | 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. | `nil`
  start_at | Optional | number | Where to start the lookup from. | `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, start) -> func
  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:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  t |  | table | The table to iterate. | Not applicable
  filter |  | func | A function that returns true to indicate a positive match. | Not applicable
  start | Optional | int | Index to start iterating from. Default is 1 (=> start of the table). | `1`

  ### Returns:

  func
🔗 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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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 | Optional | 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.

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

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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.5.0