Table Library

Overview

The table library included with Shine extends the table library with extra useful functions.

PrintTable

PrintTable( Table[, Indent ])

Prints the contents of the table to the console, including all sub table's contents too.

RandomPairs

RandomPairs( Table[, Descending ])

Iterates through the given table's keys randomly, so that every time you call it, the order of iteration will be different.

SortedPairs

SortedPairs( Table[, Descending ])

Iterates through the given table in alphabetical A - Z order based on the keys. The table should only contain string keys. Descending = true reverses the order to Z - A.

table.AsSet

table.AsSet( Array )

Takes the elements of the given array structure, and returns a table whose keys are those elements.

local Array = { 1, 2, 3, 4, 5 }
PrintTable( table.AsSet( Array ) )

--[[
Output:
{
  [ 1 ] = true,
  [ 2 ] = true,
  [ 3 ] = true,
  [ 4 ] = true,
  [ 5 ] = true
}
]]

table.Average

table.Average( Array )

Returns the average value in the given array. The array should contain elements that are able to be added together and divided by the number of elements. For example:

local Primes = { 2, 3, 5, 7 }

Print( table.Average( Primes ) )

--[[
Output:
> 4.25
]]

table.Build

table.Build( Table, ... )

Builds a chain of sub-tables along the given keys.

local Table = {}
table.Build( Table, "FirstChild", "SecondChild", "ThirdChild" )
PrintTable( Table )

--[[
Output:
{
  FirstChild = {
    SecondChild = {
      ThirdChild = {}
    }
  }
}
]]

table.ChooseRandom

table.ChooseRandom( Array )

Chooses a random key - value pair from the given array, with every key having an equal chance of being chosen. For example:

local Value, Key = table.ChooseRandom{ 1, 2, 3, 4 }

table.Copy

table.Copy( Table[, LookupTable ])

Returns a deep copy of the given table, where the main table and any sub-tables are all copied. Will only copy a sub-table once however. For example:

local CookieData = {
    MilkChocolateChip = "Nice.",
    WhiteChocolateChip = "Best."
}
local Table = { 
    Cake = "Great",
    CookieData = CookieData
}

local Copy = table.Copy( Table )

Print( tostring( Copy.CookieData == CookieData ) )
--> false

table.Count

table.Count( Table )

Returns the number of keys in the given table. Useful for tables that aren't indexed by numbers, as the # operator would return 0.

table.Empty

table.Empty( Table )

Empties the given table, removing everything from it. It does not return the table, it alters the table passed to it directly.

table.FindByField

table.FindByField( Array, Field, Value )

Searches the given array for a value that has a field matching the given value.

local Table = {
    { Cake = true },
    { Cake = false }
}
local Result = table.FindByField( Table, "Cake", true )
PrintTable( Result )

--[[
Output:
{
  Cake = true
}
]]

table.FixArray

table.FixArray( Array )

Restores the given array, moving elements down wherever there are holes so that it is one continuous sequence of keys. For example:

local BadArray = { 1, nil, 3, 4, nil, nil, 7 }

PrintTable( BadArray )

--[[
Output:
> 1 = 1
> 3 = 3
> 4 = 4
> 7 = 7
]]

table.FixArray( BadArray )

PrintTable( BadArray )

--[[
Output:
> 1 = 1
> 2 = 3
> 3 = 4
> 4 = 7
]]

table.HasValue

table.HasValue( Table, Value )

Returns true if the given array-like table contains at least one entry for the given value.

table.InsertUnique

table.InsertUnique( Table, Value )

Inserts the given value if and only if it does not currently exist in the table.

table.MergeSort

table.MergeSort( Table[, Comparator] )

Sorts the table similarly to table.sort, but does so using a stable merge sort. This preserves the order of elements considered equal.

local Data = { 6, 5, 4, 3, 2, 1 }
-- Sort in ascending order (calling without the comparator would achieve the same result).
table.MergeSort( Data, function( A, B )
    return A == B and 0 or ( A < B and -1 or 1 )
end )

table.QuickCopy

table.QuickCopy( Table )

Returns a copy of the given table, taking only the array part, and copying sub-tables by reference.

table.QuickShuffle

table.QuickShuffle( Table )

Performs an inline randomisation of the given table's values, assuming that the array structure has no gaps.

table.Reverse

table.Reverse( Array )

Returns a new table that contains all elements of the passed in array in reverse order.

local Reversed = table.Reverse( { 1, 2, 3 } )
PrintTable( Reversed )

--[[
Output:
{
   1 = 3,
   2 = 2,
   3 = 1
}
]]

table.ShallowMerge

table.ShallowMerge( Source, Destination[, UseRawGet] )

Copies all values in the Source table that are missing from the Destination table into the Destination table and returns the Destination table. Does not recurse, so any table values are just passed by reference. If UseRawGet is true, then keys will be merged across regardless of the existence of any inherited values under matching keys.

PrintTable( table.ShallowMerge( {
    Cake = true,
    MoreCake = true
}, {
    Cake = false
} )

--[[
Output:
{
    Cake = false,
    MoreCake = true
}
]]

table.Shuffle

table.Shuffle( Array )

Shuffles the elements of the given array. This edits the given array directly.

table.ToString

table.ToString( Table )

Returns a string that represents the given table's contents. This string looks the same as the output of PrintTable.