Table
ESX.Table reference for ESX Legacy - SizeOf, Find, Filter, Map, Clone, Concat, Join, TableContains, Sort, ToArray and more, with return values and pitfalls.
ESX.Table collects small helpers for working with Lua tables: searching, filtering, mapping, copying and joining. They exist on client and server. In 1.16 they are implemented in esx_lib (xLib.table) and mapped onto ESX.Table.
Overview
| Resource | es_extended (implemented in esx_lib) |
| Side | Shared |
| Mapping | es_extended/shared/compat.lua |
"Array" below means a table with keys 1..n. Functions marked array only look at that part and ignore other keys.
Size and lookup
ESX.Table.SizeOf
ESX.Table.SizeOf(t)Returns: number of keys, counted with pairs. Use it for tables with string keys.
print(ESX.Table.SizeOf({ police = 4, ambulance = 2 })) -- 2ESX.Table.Set
ESX.Table.Set(t)Array. Returns: a set { [value] = true } for fast membership checks.
local allowed = ESX.Table.Set({ 'police', 'sheriff', 'ambulance' })
if allowed[ESX.PlayerData.job.name] then
OpenEmergencyMenu()
endESX.Table.IndexOf
ESX.Table.IndexOf(t, value)Array. Returns: first index of value, or -1.
ESX.Table.LastIndexOf
ESX.Table.LastIndexOf(t, value)Array. Returns: last index of value, or -1.
ESX.Table.Find
ESX.Table.Find(t, cb)Array. Returns: the first element for which cb(element) is truthy, or nil.
local bread = ESX.Table.Find(ESX.PlayerData.inventory, function(item)
return item.name == 'bread'
end)ESX.Table.FindIndex
ESX.Table.FindIndex(t, cb)Array. Returns: index of the first match, or -1.
ESX.Table.TableContains
ESX.Table.TableContains(tab, val)| Name | Type | Description |
|---|---|---|
tab | table | Table to search (all values, not only the array part). |
val | any | table | Value, or a table of values. With a table, returns true if any of them is in tab. |
Returns: boolean
local emergencyJobs = { 'police', 'ambulance' }
print(ESX.Table.TableContains(emergencyJobs, ESX.PlayerData.job.name))Transform
ESX.Table.Filter
ESX.Table.Filter(tbl, filter)| Name | Type | Description |
|---|---|---|
tbl | table | Table to filter. |
filter | function | function(value, key). Return true to keep the entry. |
Returns: a new table with the kept entries under their original keys.
local stacks = ESX.Table.Filter(ESX.PlayerData.inventory, function(item)
return item.count > 0
end)
local list = ESX.Table.ToArray(stacks) -- re-index to 1..nESX.Table.Map
ESX.Table.Map(t, cb)Array. Returns: a new array with cb(element, index) for each element.
local names = ESX.Table.Map(ESX.PlayerData.inventory, function(item)
return item.label
end)ESX.Table.Reverse
ESX.Table.Reverse(t)Array. Returns: a new array in reverse order.
ESX.Table.Clone
ESX.Table.Clone(t)Returns: a deep copy, including nested tables and the metatable. Non-table values are returned as they are.
local defaults = { hunger = 100, thirst = 100 }
local status = ESX.Table.Clone(defaults)
status.hunger = 50 -- defaults.hunger stays 100ESX.Table.Concat
ESX.Table.Concat(t1, t2)Returns: a deep copy of t1 with the array elements of t2 appended. Neither input is changed.
ESX.Table.Join
ESX.Table.Join(t, sep)Array. Joins elements into a string.
| Name | Type | Description |
|---|---|---|
t | table | Array of strings or numbers. |
sep | string? | Separator. Default ,. |
Returns: string
print(ESX.Table.Join({ 'bread', 'water', 'phone' }, ', ')) -- bread, water, phoneESX.Table.ToArray
ESX.Table.ToArray(t)Returns: a new array with all values of t (order follows pairs and is not guaranteed).
ESX.Table.Sort
ESX.Table.Sort(t, order)Returns an iterator over t sorted by key. It does not sort t in place.
| Name | Type | Description |
|---|---|---|
t | table | Table to iterate. |
order | function? | function(t, keyA, keyB) returning true if keyA comes first. Default: sort keys ascending. |
Returns: iterator function yielding key, value.
local salaries = { police = 300, ambulance = 250, mechanic = 200 }
for job, salary in ESX.Table.Sort(salaries, function(t, a, b) return t[a] > t[b] end) do
print(job, salary)
endESX.Table.Wipe
ESX.Table.Wipe(t)Removes every key from t in place, keeping the same table reference.
The ESX.Table functions run inside es_extended. When you call them from another resource, your table is copied on the way in. Functions that return a new value work as expected, but ESX.Table.Wipe only clears that copy. Use table.wipe(t) or xLib.table.wipe(t) in your own resource instead.
Debugging
ESX.DumpTable(t) prints tables in readable form. It is documented on Shared functions.
Related
Frequently asked questions
Independent documentation
Last updated on
Math
ESX.Math reference for ESX Legacy - Round, GroupDigits, Trim, Random and GetHeadingFromCoords, with exact behavior, examples and common pitfalls.
Timeout
ESX.SetTimeout and ESX.ClearTimeout run code after a delay in ESX Legacy and let you cancel it, on both client and server. Includes examples and pitfalls.