Module table

Tables utilities module

Functions

concat (tbl1, tbl2, force) Concat tbl2 into tbl1
Values from tbl1 will be taken over values from tbl2 unless ‘force’ argument is set to true
contains (tbl, key) Check if a table contains a key
If the key is associated to a nil value, it will be considered as not here
find (tbl, value) Finds a key that is associated to the given value
The first founded key with the value will be returned
copy (tbl) Deep copy a table with all its content
allOf (tbl, fn, ...) Ensure every key/value pair of tbl produce a true return of fn
anyOf (tbl, fn, ...) Check if one of the key/value pair of tbl produce a true return of fn
noneOf (tbl, fn, ...) Check if all of tbl’s key/value pais produce a false return of fn
forEach (tbl, fn, ...) Execute a function with all key/value pair of a table


Functions

concat (tbl1, tbl2, force)
Concat tbl2 into tbl1
Values from tbl1 will be taken over values from tbl2 unless ‘force’ argument is set to true

Parameters:

  • tbl1 table The first table to concat the second into
  • tbl2 table The second table to concat into the first
  • force ? boolean If tbl2 values should be taking over values from tbl1

Returns:

    table # A new table with tbl2 concat into tbl1

Raises:

error if tbl1 is not a table
error if tbl2 is not a table
error if force is not a boolean

Usage:

    local tbl1 = { one = 1, three = 3 }
local tbl2 = { two = 2, 4 = "four" }
local tbl3 = concat(tbl1, tbl2)
 -- tbl3 -> { one = 1, three = 3, two = 2, 4 = "four" }
contains (tbl, key)
Check if a table contains a key
If the key is associated to a nil value, it will be considered as not here

Parameters:

  • tbl table The table to search the key in
  • key any The key to search in the table. This cannot be nil

Returns:

    boolean # true if tbl contains the key key

Raises:

error if tbl is not a table
error if key is nil

Usage:

    local tbl = { 1 = "one", "two" = 2 }
if not contains(tbl, "two") then
    print("Table has no entry 'two'")
else
    print("Table has an entry 'two'")
end
find (tbl, value)
Finds a key that is associated to the given value
The first founded key with the value will be returned

Parameters:

  • tbl table The table to search the value in
  • value any The value to search in the table. This cannot be nil

Returns:

    any|nil # The first key found with the given value if any, nil otherwise

Raises:

error if tbl is not a table
error if value is nil

Usage:

    local tbl = { 1 = "one", 2 = "two" }
print(find(tbl, "two")) -- 2
copy (tbl)
Deep copy a table with all its content

Parameters:

  • tbl table The table to copy

Returns:

    table # A new table that is a clone of tbl

Raises:

error if tbl is not a table

Usage:

    local tbl = { one = 1, two = 2 }
local tbl_copy = copy(tbl)
tbl["one"] = 11
print(tbl["one"]) -- 11
print(tbl_copy["one"]) -- 1
allOf (tbl, fn, ...)
Ensure every key/value pair of tbl produce a true return of fn

Parameters:

  • tbl table The tbl to test key/value pairs with fn
  • fn function The function to call with tbl’s key/value pairs.
    This function should return a boolean and take a key of tbl as first argument and a value of tbl as second argument
  • ... any Additional arguments to pass to fn

Returns:

    boolean # true if all call of fn with each of tbl’s key/value pairs returned true, false otherwise

Raises:

error if tbl is not a table
error if fn is not a function
error if fn returned something else than a boolean

Usage:

    local tbl = { one = 1, two = 2 }
if allOf(tbl, function(key, value)
    return type(value) == "number"
end)
    print("All table values are numbers")
else
    print("One or more table value(s) is not a number")
end
anyOf (tbl, fn, ...)
Check if one of the key/value pair of tbl produce a true return of fn

Parameters:

  • tbl table The tbl to test key/value pairs with fn
  • fn function The function to call with tbl’s key/value pairs.
    This function should return a boolean and take a key of tbl as first argument and a value of tbl as second argument
  • ... any Additional arguments to pass to fn

Returns:

    boolean # true if one of the calls of fn with each of tbl’s key/value pairs returned true, false otherwise

Raises:

error if tbl is not a table
error if fn is not a function
error if fn returned something else than a boolean

Usage:

    local tbl = { one = 1, two = 2, hello = "world" }
if anyOf(tbl, function(key, value)
    return type(value) == "string"
end)
    print("One or more of the table value(s) is a string")
else
    print("None of the table value is a string")
end
noneOf (tbl, fn, ...)
Check if all of tbl’s key/value pais produce a false return of fn

Parameters:

  • tbl table The tbl to test key/value pairs with fn
  • fn function The function to call with tbl’s key/value pairs.
    This function should return a boolean and take a key of tbl as first argument and a value of tbl as second argument
  • ... any Additional arguments to pass to fn

Returns:

    boolean # true if none of the calls of fn with each of tbl’s key/value returned true, false otherwise

Raises:

error if tbl is not a table
error if fn is not a function
error if fn returned something else than a boolean

Usage:

    local tbl = { one = 1, two = 2 }
if noneOf(tbl, function(key, value)
    return type(value) == "string"
end)
    print("The table does not contains string values")
end
forEach (tbl, fn, ...)
Execute a function with all key/value pair of a table

Parameters:

  • tbl table The tbl to test key/value pairs with fn
  • fn function The function to call with tbl’s key/value pairs.
    This function should take a key of tbl as first argument and a value of tbl as second argument
  • ... any Additional arguments to pass to fn

Raises:

error if tbl is not a table
error if fn is not a function

Usage:

    local tbl = { one = 1, two = 2 }
forEach(tbl, function(key, value)
    print(key .. ": " .. value)
end)
 -- one: 1
 -- two: 2
generated by LDoc 1.5.0 Last updated 2024-08-17 23:38:16