Ordered Table

Lua’s table types which are not numerically-indexed don’t define an order for their keys. Iterating through them using pairs() will provide the entries in an undefined order. A common wy around this to preserve the order of key-value tables is also insert the keys into the table as a list and then iterate over keys of table using ipairs() (and then looking up the value). The OrderedTable provides a set of helper functions to make this more ergonamic.

Example

Below is an example which demonstrates how to use the OrderedTable APIs.

local MyModule = select(2, ...).MyModule
local OrderedTable = MyModule:From("LibTSMUtil"):Include("BaseType.OrderedTable")

local tbl = {}
OrderedTable.Insert(tbl, "b", 2)
OrderedTable.Insert(tbl, "a", 3)

for _, k, v in OrderedTable.Iterator(tbl) do
   print(k, v)
end
-- b   2
-- a   3

OrderedTable.SortByKeys(tbl)

for _, k, v in OrderedTable.Iterator(tbl) do
   print(k, v)
end
-- a   3
-- b   2

API

class BaseType.OrderedTable: LibTSMModule

staticmethod GetByIndex(tbl: OrderedTable.Table<<K>, <V>>, index: number): <K>, <V>

Gets a value from an ordered table by index.

staticmethod Insert( tbl: OrderedTable.Table<<K>, <V>>, key: <K>, value: <V> )

Inserts into an ordered table.

Parameters:

tbl (OrderedTable.Table<<K>, <V>>) – The ordered table
key (<K>) – The key to insert
value (<V>) – The value to insert

staticmethod InsertIfNotSet( tbl: OrderedTable.Table<<K>, <V>>, key: <K>, value: <V> )

Inserts into an ordered table if the key wasn’t previously set.

Parameters:

tbl (OrderedTable.Table<<K>, <V>>) – The ordered table
key (<K>) – The key to insert
value (<V>) – The value to insert

staticmethod Remove(tbl: OrderedTable.Table<<K>, <V>>, key: <K>)

Removes from an ordered table.

Parameters:

tbl (OrderedTable.Table<<K>, <V>>) – The ordered table
key (<K>) – The key to remove

staticmethod SortByKeys(tbl: OrderedTable.Table<<K>, <V>>)

Sorts the ordered table by its keys

Parameters:: tbl (OrderedTable.Table<<K>, <V>>) – The ordered table

staticmethod SortByValues(tbl: OrderedTable.Table<<K>, <V>>)

Sorts the ordered table by its values

Parameters:: tbl (OrderedTable.Table<<K>, <V>>) – The ordered table

staticmethod Iterator(tbl: OrderedTable.Table<<K>, <V>>): ( fun(): number, <K>, <V>, OrderedTable.Table<<K>, <V>> )

Iterates over an ordered table.

Parameters:: tbl (OrderedTable.Table<<K>, <V>>) – The ordered table
Returns:: _1 (fun(): number, <K>, <V>) – Iterator with fields: index, key, value

staticmethod KeyIterator(tbl: OrderedTable.Table<<K>, <V>>): fun(): number, <K>, OrderedTable.Table<<K>, <V>>

Iterates over the keys of an ordered table.

Parameters:: tbl (OrderedTable.Table<<K>, <V>>) – The ordered table
Returns:: _1 (fun(): number, <K>) – Iterator with fields: key

staticmethod ConcatKeys(tbl: OrderedTable.Table<<K>, <V>>, sep: string): string

Concatenate the keys into a string.

Parameters:: sep (string) – The separator string