Skip to main content

TableUtil

A collection of helpful table utility functions. Many of these functions are carried over from JavaScript or Python that are not present in Lua.

Tables that only work specifically with arrays or dictionaries are marked as such in the documentation.

Immutability

All functions (except SwapRemove, SwapRemoveFirstValue, and Lock) treat tables as immutable and will return copies of the given table(s) with the operations performed on the copies.

Functions​

Copy​

</>
TableUtil.Copy(
tbl: table,--

Table to copy

deep: boolean?--

Whether or not to perform a deep copy

) → table

Creates a copy of the given table. By default, a shallow copy is performed. For deep copies, a second boolean argument must be passed to the function.

No cyclical references

Deep copies are not protected against cyclical references. Passing a table with cyclical references and the deep parameter set to true will result in a stack-overflow.

Sync​

</>
TableUtil.Sync(
srcTbl: table,--

Source table

templateTbl: table--

Template table

) → table

Synchronizes the srcTbl based on the templateTbl. This will make sure that srcTbl has all of the same keys as templateTbl, including removing keys in srcTbl that are not present in templateTbl. This is a deep operation, so any nested tables will be synchronized as well. 

local template = {kills = 0, deaths = 0, xp = 0}
local data = {kills = 10, experience = 12}
data = TableUtil.Sync(data, template)
print(data) --> {kills = 10, deaths = 0, xp = 0}
Data Loss Warning

This is a two-way sync, so the source table will have data removed that isn't found in the template table. This can be problematic if used for player data, where there might be dynamic data added that isn't in the template.

For player data, use TableUtil.Reconcile instead.

Reconcile​

</>
TableUtil.Reconcile(
source: table,
template: table
) → table

Performs a one-way sync on the source table against the template table. Any keys found in template that are not found in source will be added to source. This is useful for syncing player data against data template tables to ensure players have all the necessary keys, while maintaining existing keys that may no longer be in the template.

This is a deep operation, so nested tables will also be properly reconciled. 

local template = {kills = 0, deaths = 0, xp = 0}
local data = {kills = 10, abc = 20}
local correctedData = TableUtil.Reconcile(data, template)

print(correctedData) --> {kills = 10, deaths = 0, xp = 0, abc = 20}

SwapRemove​

</>
TableUtil.SwapRemove(
tbl: table,--

Array

i: number--

Index

) → ()

Removes index i in the table by swapping the value at i with the last value in the array, and then trimming off the last value from the array.

This allows removal of the value at i in O(1) time, but does not preserve array ordering. If a value needs to be removed from an array, but ordering of the array does not matter, using SwapRemove is always preferred over table.remove.

In the following example, we remove "B" at index 2. SwapRemove does this by moving the last value "E" over top of "B", and then trimming off "E" at the end of the array: 

local t = {"A", "B", "C", "D", "E"}
TableUtil.SwapRemove(t, 2) -- Remove "B"
print(t) --> {"A", "E", "C", "D"}
Arrays only

This function works on arrays, but not dictionaries.

SwapRemoveFirstValue​

</>
TableUtil.SwapRemoveFirstValue(
tbl: table,--

Array

v: any--

Value to find

) → number?

Performs table.find(tbl, v) to find the index of the given value, and then performs TableUtil.SwapRemove on that index. 

local t = {"A", "B", "C", "D", "E"}
TableUtil.SwapRemoveFirstValue(t, "C")
print(t) --> {"A", "B", "E", "D"}
Arrays only

This function works on arrays, but not dictionaries.

Map​

</>
TableUtil.Map(
tbl: table,
predicate: (
value: any,
key: any,
tbl: table
) → newValue: any
) → table

Performs a map operation against the given table, which can be used to map new values based on the old values at given keys/indices.

For example:

local t = {A = 10, B = 20, C = 30}
local t2 = TableUtil.Map(t, function(value)
	return value * 2
end)
print(t2) --> {A = 20, B = 40, C = 60}

Filter​

</>
TableUtil.Filter(
tbl: table,
predicate: (
value: any,
key: any,
tbl: table
) → keep: boolean
) → table

Performs a filter operation against the given table, which can be used to filter out unwanted values from the table.

For example:

local t = {A = 10, B = 20, C = 30}
local t2 = TableUtil.Filter(t, function(value, key)
	return value > 15
end)
print(t2) --> {B = 40, C = 60}

Reduce​

</>
TableUtil.Reduce(
tbl: table,
predicate: (
accumulator: any,
value: any,
index: any,
tbl: table
) → result: any
) → table

Performs a reduce operation against the given table, which can be used to reduce the table into a single value. This could be used to sum up a table or transform all the values into a compound value of any kind.

For example:

local t = {10, 20, 30, 40}
local result = TableUtil.Reduce(t, function(accum, value)
	return accum + value
end)
print(result) --> 100

Assign​

</>
TableUtil.Assign(
target: table,
...: table
) → table

Copies all values of the given tables into the target table.

local t = {A = 10}
local t2 = {B = 20}
local t3 = {C = 30, D = 40}
local newT = TableUtil.Assign(t, t2, t3)
print(newT) --> {A = 10, B = 20, C = 30, D = 40}

Extend​

</>
TableUtil.Extend(
target: table,
extension: table
) → table

Extends the target array with the extension array.

local t = {10, 20, 30}
local t2 = {30, 40, 50}
local tNew = TableUtil.Extend(t, t2)
print(tNew) --> {10, 20, 30, 30, 40, 50}
Arrays only

This function works on arrays, but not dictionaries.

Reverse​

</>
TableUtil.Reverse(tbl: table) → table

Reverses the array.

local t = {1, 5, 10}
local tReverse = TableUtil.Reverse(t)
print(tReverse) --> {10, 5, 1}
Arrays only

This function works on arrays, but not dictionaries.

Shuffle​

</>
TableUtil.Shuffle(
tbl: table,
rngOverride: Random?
) → table

Shuffles the table.

local t = {1, 2, 3, 4, 5, 6, 7, 8, 9}
local shuffled = TableUtil.Shuffle(t)
print(shuffled) --> e.g. {9, 4, 6, 7, 3, 1, 5, 8, 2}
Arrays only

This function works on arrays, but not dictionaries.

Sample​

</>
TableUtil.Sample(
tbl: table,
sampleSize: number,
rngOverride: Random?
) → table

Returns a random sample of the table.

local t = {1, 2, 3, 4, 5, 6, 7, 8, 9}
local sample = TableUtil.Sample(t, 3)
print(sample) --> e.g. {6, 2, 5}
Arrays only

This function works on arrays, but not dictionaries.

Flat​

</>
TableUtil.Flat(
tbl: table,
depth: number?
) → table

Returns a new table where all sub-arrays have been bubbled up to the top. The depth at which the scan is performed is dictated by the depth parameter, which is set to 1 by default. 

local t = {{10, 20}, {90, 100}, {30, 15}}
local flat = TableUtil.Flat(t)
print(flat) --> {10, 20, 90, 100, 30, 15}
Arrays only

This function works on arrays, but not dictionaries.

FlatMap​

</>
TableUtil.FlatMap(
tbl: table,
predicate: (
key: any,
value: any,
tbl: table
) → newValue: any
) → table

Calls TableUtil.Map on the given table and predicate, and then calls TableUtil.Flat on the result from the map operation. 

local t = {10, 20, 30}
local result = TableUtil.FlatMap(t, function(value)
	return {value, value * 2}
end)
print(result) --> {10, 20, 20, 40, 30, 60}
Arrays only

This function works on arrays, but not dictionaries.

Keys​

</>
TableUtil.Keys(tbl: table) → table

Returns an array with all the keys in the table.

local t = {A = 10, B = 20, C = 30}
local keys = TableUtil.Keys(t)
print(keys) --> {"A", "B", "C"}
Ordering

The ordering of the keys is never guaranteed. If order is imperative, call table.sort on the resulting keys array. 

local keys = TableUtil.Keys(t)
table.sort(keys)

Values​

</>
TableUtil.Values(tbl: table) → table

Returns an array with all the values in the table.

local t = {A = 10, B = 20, C = 30}
local values = TableUtil.Values(t)
print(values) --> {10, 20, 30}
Ordering

The ordering of the values is never guaranteed. If order is imperative, call table.sort on the resulting values array. 

local values = TableUtil.Values(t)
table.sort(values)

Find​

</>
TableUtil.Find(
tbl: table,
callback: (
value: any,
index: any,
tbl: table
) → boolean
) → (
value: any?,
key: any?
)

Performs a linear scan across the table and calls callback on each item in the array. Returns the value and key of the first pair in which the callback returns true. 

local t = {
	{Name = "Bob", Age = 20};
	{Name = "Jill", Age = 30};
	{Name = "Ann", Age = 25};
}

-- Find first person who has a name starting with J:
local firstPersonWithJ = TableUtil.Find(t, function(person)
	return person.Name:sub(1, 1):lower() == "j"
end)

print(firstPersonWithJ) --> {Name = "Jill", Age = 30}
Dictionary Ordering

While Find can also be used with dictionaries, dictionary ordering is never guaranteed, and thus the result could be different if there are more than one possible matches given the data and callback function.

Every​

</>
TableUtil.Every(
tbl: table,
callback: (
value: any,
index: any,
tbl: table
) → boolean
) → boolean

Returns true if the callback also returns true for every item in the table. 

local t = {10, 20, 40, 50, 60}

local allAboveZero = TableUtil.Every(t, function(value)
	return value > 0
end)

print("All above zero:", allAboveZero) --> All above zero: true

Some​

</>
TableUtil.Some(
tbl: table,
callback: (
value: any,
index: any,
tbl: table
) → boolean
) → boolean

Returns true if the callback also returns true for at least one of the items in the table.

local t = {10, 20, 40, 50, 60}

local someBelowTwenty = TableUtil.Some(t, function(value)
	return value < 20
end)

print("Some below twenty:", someBelowTwenty) --> Some below twenty: true

Truncate​

</>
TableUtil.Truncate(
tbl: table,
length: number
) → table

Returns a new table truncated to the length of length. Any length equal or greater than the current length will simply return a shallow copy of the table. 

local t = {10, 20, 30, 40, 50, 60, 70, 80}
local tTruncated = TableUtil.Truncate(t, 3)
print(tTruncated) --> {10, 20, 30}

Zip​

</>
TableUtil.Zip(...: table) → (
iter: (
t: table,
k: any
) → (
key: any?,
values: table?
),
tbl: table,
startIndex: any?
)

Returns an iterator that can scan through multiple tables at the same time side-by-side, matching against shared keys/indices. 

local t1 = {10, 20, 30, 40, 50}
local t2 = {60, 70, 80, 90, 100}

for key,values in TableUtil.Zip(t1, t2) do
	print(key, values)
end

--[[
	Outputs:
	1 {10, 60}
	2 {20, 70}
	3 {30, 80}
	4 {40, 90}
	5 {50, 100}
--]]

Lock​

</>
TableUtil.Lock(tbl: table) → table

Locks the table using table.freeze, as well as any nested tables within the given table. This will lock the whole deep structure of the table, disallowing any further modifications. 

local tbl = {xyz = {abc = 32}}
tbl.xyz.abc = 28 -- Works fine
TableUtil.Lock(tbl)
tbl.xyz.abc = 64 -- Will throw an error (cannot modify readonly table)

IsEmpty​

</>
TableUtil.IsEmpty(tbl: table) → boolean

Returns true if the given table is empty. This is simply performed by checking if next(tbl) is nil and works for both arrays and dictionaries. This is useful when needing to check if a table is empty but not knowing if it is an array or dictionary. 

TableUtil.IsEmpty({}) -- true
TableUtil.IsEmpty({"abc"}) -- false
TableUtil.IsEmpty({abc = 32}) -- false

EncodeJSON​

</>
TableUtil.EncodeJSON(value: any) → string

DecodeJSON​

</>
TableUtil.DecodeJSON(value: any) → string
Show raw api
{
    "functions": [
        {
            "name": "Copy",
            "desc": "Creates a copy of the given table. By default, a shallow copy is\nperformed. For deep copies, a second boolean argument must be\npassed to the function.\n\n:::caution No cyclical references\nDeep copies are _not_ protected against cyclical references. Passing\na table with cyclical references _and_ the `deep` parameter set to\n`true` will result in a stack-overflow.\n:::",
            "params": [
                {
                    "name": "tbl",
                    "desc": "Table to copy",
                    "lua_type": "table"
                },
                {
                    "name": "deep",
                    "desc": "Whether or not to perform a deep copy",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 42,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Sync",
            "desc": "Synchronizes the `srcTbl` based on the `templateTbl`. This will make\nsure that `srcTbl` has all of the same keys as `templateTbl`, including\nremoving keys in `srcTbl` that are not present in `templateTbl`. This\nis a _deep_ operation, so any nested tables will be synchronized as\nwell.\n\n```lua\nlocal template = {kills = 0, deaths = 0, xp = 0}\nlocal data = {kills = 10, experience = 12}\ndata = TableUtil.Sync(data, template)\nprint(data) --> {kills = 10, deaths = 0, xp = 0}\n```\n\n:::caution Data Loss Warning\nThis is a two-way sync, so the source table will have data\n_removed_ that isn't found in the template table. This can\nbe problematic if used for player data, where there might\nbe dynamic data added that isn't in the template.\n\nFor player data, use `TableUtil.Reconcile` instead.\n:::",
            "params": [
                {
                    "name": "srcTbl",
                    "desc": "Source table",
                    "lua_type": "table"
                },
                {
                    "name": "templateTbl",
                    "desc": "Template table",
                    "lua_type": "table"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 87,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Reconcile",
            "desc": "Performs a one-way sync on the `source` table against the\n`template` table. Any keys found in `template` that are\nnot found in `source` will be added to `source`. This is\nuseful for syncing player data against data template tables\nto ensure players have all the necessary keys, while\nmaintaining existing keys that may no longer be in the\ntemplate.\n\nThis is a deep operation, so nested tables will also be\nproperly reconciled.\n\n```lua\nlocal template = {kills = 0, deaths = 0, xp = 0}\nlocal data = {kills = 10, abc = 20}\nlocal correctedData = TableUtil.Reconcile(data, template)\n\nprint(correctedData) --> {kills = 10, deaths = 0, xp = 0, abc = 20}\n```",
            "params": [
                {
                    "name": "source",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "template",
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 159,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "SwapRemove",
            "desc": "Removes index `i` in the table by swapping the value at `i` with\nthe last value in the array, and then trimming off the last\nvalue from the array.\n\nThis allows removal of the value at `i` in `O(1)` time, but does\nnot preserve array ordering. If a value needs to be removed from\nan array, but ordering of the array does not matter, using\n`SwapRemove` is always preferred over `table.remove`.\n\nIn the following example, we remove \"B\" at index 2. SwapRemove does\nthis by moving the last value \"E\" over top of \"B\", and then trimming\noff \"E\" at the end of the array:\n```lua\nlocal t = {\"A\", \"B\", \"C\", \"D\", \"E\"}\nTableUtil.SwapRemove(t, 2) -- Remove \"B\"\nprint(t) --> {\"A\", \"E\", \"C\", \"D\"}\n```\n\n:::note Arrays only\nThis function works on arrays, but not dictionaries.\n:::",
            "params": [
                {
                    "name": "tbl",
                    "desc": "Array",
                    "lua_type": "table"
                },
                {
                    "name": "i",
                    "desc": "Index",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 213,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "SwapRemoveFirstValue",
            "desc": "Performs `table.find(tbl, v)` to find the index of the given\nvalue, and then performs `TableUtil.SwapRemove` on that index.\n\n```lua\nlocal t = {\"A\", \"B\", \"C\", \"D\", \"E\"}\nTableUtil.SwapRemoveFirstValue(t, \"C\")\nprint(t) --> {\"A\", \"B\", \"E\", \"D\"}\n```\n\n:::note Arrays only\nThis function works on arrays, but not dictionaries.\n:::",
            "params": [
                {
                    "name": "tbl",
                    "desc": "Array",
                    "lua_type": "table"
                },
                {
                    "name": "v",
                    "desc": "Value to find",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 239,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Map",
            "desc": "Performs a map operation against the given table, which can be used to\nmap new values based on the old values at given keys/indices.\n\nFor example:\n\n```lua\nlocal t = {A = 10, B = 20, C = 30}\nlocal t2 = TableUtil.Map(t, function(value)\n\treturn value * 2\nend)\nprint(t2) --> {A = 20, B = 40, C = 60}\n```",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "predicate",
                    "desc": "",
                    "lua_type": "(value: any, key: any, tbl: table) -> newValue: any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 267,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Filter",
            "desc": "Performs a filter operation against the given table, which can be used to\nfilter out unwanted values from the table.\n\nFor example:\n\n```lua\nlocal t = {A = 10, B = 20, C = 30}\nlocal t2 = TableUtil.Filter(t, function(value, key)\n\treturn value > 15\nend)\nprint(t2) --> {B = 40, C = 60}\n```",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "predicate",
                    "desc": "",
                    "lua_type": "(value: any, key: any, tbl: table) -> keep: boolean"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 297,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Reduce",
            "desc": "Performs a reduce operation against the given table, which can be used to\nreduce the table into a single value. This could be used to sum up a table\nor transform all the values into a compound value of any kind.\n\nFor example:\n\n```lua\nlocal t = {10, 20, 30, 40}\nlocal result = TableUtil.Reduce(t, function(accum, value)\n\treturn accum + value\nend)\nprint(result) --> 100\n```",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "predicate",
                    "desc": "",
                    "lua_type": "(accumulator: any, value: any, index: any, tbl: table) -> result: any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 340,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Assign",
            "desc": "Copies all values of the given tables into the `target` table.\n\n```lua\nlocal t = {A = 10}\nlocal t2 = {B = 20}\nlocal t3 = {C = 30, D = 40}\nlocal newT = TableUtil.Assign(t, t2, t3)\nprint(newT) --> {A = 10, B = 20, C = 30, D = 40}\n```",
            "params": [
                {
                    "name": "target",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 383,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Extend",
            "desc": "Extends the target array with the extension array.\n\n```lua\nlocal t = {10, 20, 30}\nlocal t2 = {30, 40, 50}\nlocal tNew = TableUtil.Extend(t, t2)\nprint(tNew) --> {10, 20, 30, 30, 40, 50}\n```\n\n:::note Arrays only\nThis function works on arrays, but not dictionaries.\n:::",
            "params": [
                {
                    "name": "target",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "extension",
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 413,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Reverse",
            "desc": "Reverses the array.\n\n```lua\nlocal t = {1, 5, 10}\nlocal tReverse = TableUtil.Reverse(t)\nprint(tReverse) --> {10, 5, 1}\n```\n\n:::note Arrays only\nThis function works on arrays, but not dictionaries.\n:::",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 439,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Shuffle",
            "desc": "Shuffles the table.\n\n```lua\nlocal t = {1, 2, 3, 4, 5, 6, 7, 8, 9}\nlocal shuffled = TableUtil.Shuffle(t)\nprint(shuffled) --> e.g. {9, 4, 6, 7, 3, 1, 5, 8, 2}\n```\n\n:::note Arrays only\nThis function works on arrays, but not dictionaries.\n:::",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "rngOverride",
                    "desc": "",
                    "lua_type": "Random?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 467,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Sample",
            "desc": "Returns a random sample of the table.\n\n```lua\nlocal t = {1, 2, 3, 4, 5, 6, 7, 8, 9}\nlocal sample = TableUtil.Sample(t, 3)\nprint(sample) --> e.g. {6, 2, 5}\n```\n\n:::note Arrays only\nThis function works on arrays, but not dictionaries.\n:::",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "sampleSize",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "rngOverride",
                    "desc": "",
                    "lua_type": "Random?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 498,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Flat",
            "desc": "Returns a new table where all sub-arrays have been\nbubbled up to the top. The depth at which the scan\nis performed is dictated by the `depth` parameter,\nwhich is set to `1` by default.\n\n```lua\nlocal t = {{10, 20}, {90, 100}, {30, 15}}\nlocal flat = TableUtil.Flat(t)\nprint(flat) --> {10, 20, 90, 100, 30, 15}\n```\n\n:::note Arrays only\nThis function works on arrays, but not dictionaries.\n:::",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "depth",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 547,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "FlatMap",
            "desc": "Calls `TableUtil.Map` on the given table and predicate, and then\ncalls `TableUtil.Flat` on the result from the map operation.\n\n```lua\nlocal t = {10, 20, 30}\nlocal result = TableUtil.FlatMap(t, function(value)\n\treturn {value, value * 2}\nend)\nprint(result) --> {10, 20, 20, 40, 30, 60}\n```\n\n:::note Arrays only\nThis function works on arrays, but not dictionaries.\n:::",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "predicate",
                    "desc": "",
                    "lua_type": "(key: any, value: any, tbl: table) -> newValue: any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 585,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Keys",
            "desc": "Returns an array with all the keys in the table.\n\n```lua\nlocal t = {A = 10, B = 20, C = 30}\nlocal keys = TableUtil.Keys(t)\nprint(keys) --> {\"A\", \"B\", \"C\"}\n```\n\n:::caution Ordering\nThe ordering of the keys is never guaranteed. If order is imperative, call\n`table.sort` on the resulting `keys` array.\n```lua\nlocal keys = TableUtil.Keys(t)\ntable.sort(keys)\n```\n:::",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 612,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Values",
            "desc": "Returns an array with all the values in the table.\n\n```lua\nlocal t = {A = 10, B = 20, C = 30}\nlocal values = TableUtil.Values(t)\nprint(values) --> {10, 20, 30}\n```\n\n:::caution Ordering\nThe ordering of the values is never guaranteed. If order is imperative, call\n`table.sort` on the resulting `values` array.\n```lua\nlocal values = TableUtil.Values(t)\ntable.sort(values)\n```\n:::",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 643,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Find",
            "desc": "Performs a linear scan across the table and calls `callback` on\neach item in the array. Returns the value and key of the first\npair in which the callback returns `true`.\n\n```lua\nlocal t = {\n\t{Name = \"Bob\", Age = 20};\n\t{Name = \"Jill\", Age = 30};\n\t{Name = \"Ann\", Age = 25};\n}\n\n-- Find first person who has a name starting with J:\nlocal firstPersonWithJ = TableUtil.Find(t, function(person)\n\treturn person.Name:sub(1, 1):lower() == \"j\"\nend)\n\nprint(firstPersonWithJ) --> {Name = \"Jill\", Age = 30}\n```\n\n:::caution Dictionary Ordering\nWhile `Find` can also be used with dictionaries, dictionary ordering is never\nguaranteed, and thus the result could be different if there are more\nthan one possible matches given the data and callback function.\n:::",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "(value: any, index: any, tbl: table) -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "(value: any?, key: any?)"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 683,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Every",
            "desc": "Returns `true` if the `callback` also returns `true` for _every_\nitem in the table.\n\n```lua\nlocal t = {10, 20, 40, 50, 60}\n\nlocal allAboveZero = TableUtil.Every(t, function(value)\n\treturn value > 0\nend)\n\nprint(\"All above zero:\", allAboveZero) --> All above zero: true\n```",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "(value: any, index: any, tbl: table) -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 712,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Some",
            "desc": "Returns `true` if the `callback` also returns `true` for _at least\none_ of the items in the table.\n\n```lua\nlocal t = {10, 20, 40, 50, 60}\n\nlocal someBelowTwenty = TableUtil.Some(t, function(value)\n\treturn value < 20\nend)\n\nprint(\"Some below twenty:\", someBelowTwenty) --> Some below twenty: true\n```",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "(value: any, index: any, tbl: table) -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 741,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Truncate",
            "desc": "Returns a new table truncated to the length of `length`. Any length\nequal or greater than the current length will simply return a\nshallow copy of the table.\n\n```lua\nlocal t = {10, 20, 30, 40, 50, 60, 70, 80}\nlocal tTruncated = TableUtil.Truncate(t, 3)\nprint(tTruncated) --> {10, 20, 30}\n```",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                },
                {
                    "name": "length",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 767,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Zip",
            "desc": "Returns an iterator that can scan through multiple tables at the same time side-by-side, matching\nagainst shared keys/indices.\n\n```lua\nlocal t1 = {10, 20, 30, 40, 50}\nlocal t2 = {60, 70, 80, 90, 100}\n\nfor key,values in TableUtil.Zip(t1, t2) do\n\tprint(key, values)\nend\n\n--[[\n\tOutputs:\n\t1 {10, 60}\n\t2 {20, 70}\n\t3 {30, 80}\n\t4 {40, 90}\n\t5 {50, 100}\n--]]\n```",
            "params": [
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "(iter: (t: table, k: any) -> (key: any?, values: table?), tbl: table, startIndex: any?)"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 800,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "Lock",
            "desc": "Locks the table using `table.freeze`, as well as any\nnested tables within the given table. This will lock\nthe whole deep structure of the table, disallowing any\nfurther modifications.\n\n```lua\nlocal tbl = {xyz = {abc = 32}}\ntbl.xyz.abc = 28 -- Works fine\nTableUtil.Lock(tbl)\ntbl.xyz.abc = 64 -- Will throw an error (cannot modify readonly table)\n```",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 853,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "IsEmpty",
            "desc": "Returns `true` if the given table is empty. This is\nsimply performed by checking if `next(tbl)` is `nil`\nand works for both arrays and dictionaries. This is\nuseful when needing to check if a table is empty but\nnot knowing if it is an array or dictionary.\n\n```lua\nTableUtil.IsEmpty({}) -- true\nTableUtil.IsEmpty({\"abc\"}) -- false\nTableUtil.IsEmpty({abc = 32}) -- false\n```",
            "params": [
                {
                    "name": "tbl",
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 883,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "EncodeJSON",
            "desc": "Proxy for [`HttpService:JSONEncode`](https://developer.roblox.com/en-us/api-reference/function/HttpService/JSONEncode).",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 895,
                "path": "modules/table-util/init.luau"
            }
        },
        {
            "name": "DecodeJSON",
            "desc": "Proxy for [`HttpService:JSONDecode`](https://developer.roblox.com/en-us/api-reference/function/HttpService/JSONDecode).",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 907,
                "path": "modules/table-util/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "TableUtil",
    "desc": "A collection of helpful table utility functions. Many of these functions are carried over from JavaScript or\nPython that are not present in Lua.\n\nTables that only work specifically with arrays or dictionaries are marked as such in the documentation.\n\n:::info Immutability\nAll functions (_except_ `SwapRemove`, `SwapRemoveFirstValue`, and `Lock`) treat tables as immutable and will return\ncopies of the given table(s) with the operations performed on the copies.\n:::",
    "source": {
        "line": 20,
        "path": "modules/table-util/init.luau"
    }
}