Tables

The Tables module provides comprehensive table manipulation utilities for FiveM resources with functional programming support, deep operations, array processing, and advanced data structure management

deepCopy

Creates a deep copy of a table with all nested structures, handling circular references safely.

B2Lib.Tables.deepCopy(tbl, options)

Parameters:

tbl (table): The table to copy
options (table, optional): Copy configuration options
- preserveMetatable (boolean): Whether to preserve metatable (default: false)
- maxDepth (number): Maximum recursion depth (default: 100)

Returns: table - The deep copied table

Example:

local original = {name = "John", stats = {health = 100}}
local copy = B2Lib.Tables.deepCopy(original)
copy.stats.health = 80  -- Original remains unchanged

shallowCopy

Creates a shallow copy of a table (only first level).

B2Lib.Tables.shallowCopy(tbl, preserveMetatable)

Parameters:

tbl (table): The table to copy
preserveMetatable (boolean, optional): Whether to preserve metatable

Returns: table - The shallow copied table

merge

Merges multiple tables with deep merging for nested structures.

B2Lib.Tables.merge(...)

Parameters:

... (table): Tables to merge (later tables override earlier ones)

Returns: table - The merged table

Example:

local defaults = {ui = {theme = "dark"}}
local userPrefs = {ui = {size = "large"}}
local config = B2Lib.Tables.merge(defaults, userPrefs)
-- Result: {ui = {theme = "dark", size = "large"}}

equals

Compares two tables for deep equality, handling nested structures.

B2Lib.Tables.equals(tbl1, tbl2, options)

Parameters:

tbl1 (table): First table to compare
tbl2 (table): Second table to compare
options (table, optional): Comparison options
- ignoreMetatable (boolean): Whether to ignore metatable differences (default: false)
- maxDepth (number): Maximum recursion depth (default: 100)

Returns: boolean - True if tables are deeply equal

contains

Checks if a table contains a specific value with optional deep search.

B2Lib.Tables.contains(tbl, value, deep)

Parameters:

tbl (table): The table to search in
value (any): The value to search for
deep (boolean, optional): Whether to search nested tables

Returns: boolean - True if the value is found

hasKey

Checks if a table contains a specific key.

B2Lib.Tables.hasKey(tbl, key)

Parameters:

tbl (table): The table to search in
key (any): The key to search for

Returns: boolean - True if the key exists

size

Gets the number of key-value pairs in a table.

B2Lib.Tables.size(tbl)

Parameters:

tbl (table): The table to count

Returns: number - The number of key-value pairs

isEmpty

Checks if a table is empty or nil.

B2Lib.Tables.isEmpty(tbl)

Parameters:

tbl (table): The table to check

Returns: boolean - True if the table is empty or nil

keys

Gets all keys from a table as an array.

B2Lib.Tables.keys(tbl, sorted)

Parameters:

tbl (table): The table to extract keys from
sorted (boolean, optional): Whether to sort the keys

Returns: table - Array of keys

values

Gets all values from a table as an array.

B2Lib.Tables.values(tbl)

Parameters:

tbl (table): The table to extract values from

Returns: table - Array of values

filter

Filters table elements based on a predicate function.

B2Lib.Tables.filter(tbl, predicate)

Parameters:

tbl (table): The table to filter
predicate (function): Function that returns true for elements to keep

Returns: table - New table with filtered elements

Example:

local players = {{name = "John", level = 10}, {name = "Jane", level = 5}}
local highLevel = B2Lib.Tables.filter(players, function(player)
    return player.level > 8
end)

map

Transforms each element in a table using a mapping function.

B2Lib.Tables.map(tbl, mapper)

Parameters:

tbl (table): The table to transform
mapper (function): Function to transform each element

Returns: table - New table with transformed elements

reduce

Reduces a table to a single value using an accumulator function.

B2Lib.Tables.reduce(tbl, reducer, initialValue)

Parameters:

tbl (table): The table to reduce
reducer (function): Function to combine elements
initialValue (any, optional): Initial accumulator value

Returns: any - The reduced value

find

Finds the first element that matches a predicate function.

B2Lib.Tables.find(tbl, predicate)

Parameters:

tbl (table): The table to search
predicate (function): Function that returns true for the desired element

Returns: any - The first matching element or nil

some

Checks if at least one element matches a predicate function.

B2Lib.Tables.some(tbl, predicate)

Parameters:

tbl (table): The table to check
predicate (function): Function to test elements

Returns: boolean - True if at least one element matches

every

Checks if all elements match a predicate function.

B2Lib.Tables.every(tbl, predicate)

Parameters:

tbl (table): The table to check
predicate (function): Function to test elements

Returns: boolean - True if all elements match

sort

Sorts an array table using an optional comparison function.

B2Lib.Tables.sort(tbl, compareFn)

Parameters:

tbl (table): The array table to sort
compareFn (function, optional): Comparison function

Returns: table - New sorted table

sortBy

Sorts an array table by a key extraction function.

B2Lib.Tables.sortBy(tbl, keyFn)

Parameters:

tbl (table): The array table to sort
keyFn (function): Function to extract sort key from each element

Returns: table - New sorted table

reverse

Reverses the order of elements in an array table.

B2Lib.Tables.reverse(tbl)

Parameters:

tbl (table): The array table to reverse

Returns: table - New reversed table

unique

Removes duplicate values from an array table.

B2Lib.Tables.unique(tbl, keyFn)

Parameters:

tbl (table): The array table to process
keyFn (function, optional): Function to extract comparison key

Returns: table - New table with unique elements

take

Takes the first n elements from an array table.

B2Lib.Tables.take(tbl, count)

Parameters:

tbl (table): The array table to take from
count (number): Number of elements to take

Returns: table - New table with first n elements

skip

Skips the first n elements from an array table.

B2Lib.Tables.skip(tbl, count)

Parameters:

tbl (table): The array table to skip from
count (number): Number of elements to skip

Returns: table - New table without first n elements

chunk

Splits an array table into chunks of specified size.

B2Lib.Tables.chunk(tbl, size)

Parameters:

tbl (table): The array table to chunk
size (number): Size of each chunk

Returns: table - Array of chunks

flatten

Flattens nested array tables to a specified depth.

B2Lib.Tables.flatten(tbl, depth)

Parameters:

tbl (table): The nested array table to flatten
depth (number, optional): Maximum depth to flatten (default: 1)

Returns: table - Flattened array table

groupBy

Groups array elements by a key extraction function.

B2Lib.Tables.groupBy(tbl, keyFn)

Parameters:

tbl (table): The array table to group
keyFn (function): Function to extract grouping key

Returns: table - Table with grouped elements

partition

Partitions an array table into two groups based on a predicate.

B2Lib.Tables.partition(tbl, predicate)

Parameters:

tbl (table): The array table to partition
predicate (function): Function to test elements

Returns: table, table - Two tables (matching, non-matching)

zip

Combines multiple array tables element-wise.

B2Lib.Tables.zip(...)

Parameters:

... (table): Array tables to combine

Returns: table - Array of combined elements

toString

Converts a table to a readable string representation.

B2Lib.Tables.toString(tbl, options)

Parameters:

tbl (table): The table to convert
options (table, optional): Formatting options
- compact (boolean): Whether to use compact formatting
- maxDepth (number): Maximum depth to display

Returns: string - String representation of the table

fromPairs

Creates a table from an array of key-value pairs.

B2Lib.Tables.fromPairs(pairs)

Parameters:

pairs (table): Array of {key, value} pairs

Returns: table - Table created from pairs

toPairs

Converts a table to an array of key-value pairs.

B2Lib.Tables.toPairs(tbl)

Parameters:

tbl (table): The table to convert

Returns: table - Array of {key, value} pairs

pick

Creates a new table with only specified keys.

B2Lib.Tables.pick(tbl, keys)

Parameters:

tbl (table): The source table
keys (table): Array of keys to pick

Returns: table - New table with only picked keys

omit

Creates a new table excluding specified keys.

B2Lib.Tables.omit(tbl, keys)

Parameters:

tbl (table): The source table
keys (table): Array of keys to omit

Returns: table - New table without omitted keys

invert

Inverts a table's keys and values.

B2Lib.Tables.invert(tbl)

Parameters:

tbl (table): The table to invert

Returns: table - New table with inverted key-value pairs

countBy

Counts occurrences of values using a key extraction function.

B2Lib.Tables.countBy(tbl, keyFn)

Parameters:

tbl (table): The array table to count
keyFn (function, optional): Function to extract counting key

Returns: table - Table with counts for each key

Configuration

Configure the tables module in config.lua:

Config.Tables = {
    maxDepth = 100,                 -- Maximum recursion depth for deep operations
    enableCircularDetection = true, -- Enable circular reference detection
    preserveMetatables = false,     -- Default metatable preservation
    enableTypeChecking = true,      -- Enable strict type checking
    maxTableSize = 10000,          -- Maximum table size for operations
    enablePerformanceMode = false,  -- Enable performance optimizations
    cacheResults = true,           -- Cache frequently used results
    enableDebugMode = false        -- Enable debug logging
}

Troubleshooting

Memory Issues

Use shallow copy when deep copy isn't necessary
Set appropriate maxDepth limits for deep operations
Enable performance mode for large tables
Clear cached results periodically

Circular Reference Errors

Enable circular reference detection
Check for self-referencing tables
Use maxDepth limits to prevent infinite recursion
Validate table structure before operations

Performance Problems

Use appropriate functions for the task (filter vs find)
Enable performance mode for large datasets
Cache results of expensive operations
Consider using native Lua operations for simple tasks

Type Errors

Enable type checking for better error messages
Validate input parameters before operations
Check for nil values in tables
Ensure functions receive expected data types

PreviousStrings NextTimers

Last updated 1 month ago