cwc

• Index

Contents

• Static module functions

Utility libraries

• gears.debug
• gears.filesystem
• gears.geometry
• gears.math
• gears.object
• gears.protected_call
• gears.sort
• gears.string
• gears.table

Core components

• cwc
• cwc.client
• cwc.container
• cwc.kbd
• cwc.plugin
• cwc.pointer
• cwc.screen

Plugins

• cwc.cwcle

Theme related libraries

• gears.color

Libraries

• cuteful.client
• cuteful.enum
• cuteful.tag
• gears.matcher
• gears.surface

Classes

• gears.cache
• gears.matrix

Documentation

• Getting Started
• Custom Layout
• C Plugin

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.

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

Parameters:

Name		Type(s)	Description
t		table	The table for which to count the keys.

Returns:

number The number of keys in the table.

🔗 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