File Table.lua

Functions

Table:addItems (t, t2) Adds items in one table to another.
Table:addToSet (toSet, fromSet) Add from set to set, or names array to set.
Table:appendArray (t1, t2) Appends one array to another.
Table:appendArrays (t1, ...) Appends one array to another.
Table:arrayOfSortedKeys (t, sortFunc, reverse) Get array of sorted keys.
Table:combineArrays (t1, t2) Like "append", except creates a new array.
Table:convertToArray (tbl, keyName, valueName, sorter) Convert table to array
Table:copy (t) Make a shallow copy of a table.
Table:countItems (t, excl) Count non-nil items in table.
Table:createArrayFromSet (set, sort) Create an array from a set.
Table:createSet (array, b) Create a set from an array ###1 b is unused.
Table:deepCopy (t) Make a deep copy of a table.
Table:findInArray (t1, item) Searches for an item in an array (starting at index 1).
Table:getAnyKeyAndValue (t) Get any key and value.
Table:getTable (a, nameToThrow) Return a value which must be a table or nil.
Table:getValue (t, dotKeys) Get (potentially nested) table value given specified key in dot-notation format.
Table:initVar (t, n, v, overwriteOk) Failsafe way to add a member to a table that may already be closed for write access (strict write-access policy has been set).
Table:is (t, valueTitle) Determine if passed parameter is a table with at least one non-nil element.
Table:isArray (t, valueTitle) Determine if passed parameter represents a table containing values at numeric indexes.
Table:isEmpty (t) Determine if table has no elements.
Table:isEquiv (t1, t2, eqFunc) Determines if two tables (or non-table values) are equivalent.
Table:isEquivalent (t1, t2) Determines if two tables (or non-table values) are equivalent.
Table:isFoundInArray (t1, item) Searches for an item in an array.
Table:isInArray (array, item) Determine if item is in array, if so return index (does not check for redundent items).
Table:isNotEmpty (t) Determine if table has any elements.
Table:md5 (t) Compute md5 over table elements.
Table:mergeArrays (t1, t2) Like "combine", except DOES check for item duplication.
Table:mergeSets (...) Merge two or more sets.
Table:new (t) Constructor for new instance.
Table:newClass (t) Constructor for extending class.
Table:removeFromSet (set, remove) Add from set to set, or names array to set.
Table:replicate (item, count) Create a table by replicating item, count times.
Table:reverseArray (t) Reverse table array order.
Table:reverseInPlace (t) Reverse an array in place.
Table:reverseSort (t, reverseSortFunc, dummy) Sort a homogeneous table in reverse of what you can do with the normal table-sort function, including the stubborn last element.
Table:reverseSortCopy (t, reverseSortFunc, dummy) Creates a table sorted in reverse of what you can do with the normal table-sort function, including the stubborn last element.
Table:setStrict (t, write, read) Set table member access strictness policy.
Table:slice (t, i1, i2) Extract a table slice.
Table:sortReverse (t, func) Sort table in place, reversed.
Table:sortReverseCopy (t, func) Sort table without altering it, and return a sorted copy, reversed.
Table:sortedPairs (t, sortFunc, reverse) Return iterator that feeds k,v pairs back to the calling context sorted according to the specified sort function.


Functions

Table:addItems (t, t2)
Adds items in one table to another.

Parameters:

  • t: a table of key-value pairs to be added to.
  • t2: a table of key-value pairs to add.

Usage:

  • adds all t2 items to t - nothing is returned.
  • Note: values of t2 will overwrite same-key values of t, so make sure thats what you want... 
Table:addToSet (toSet, fromSet)
Add from set to set, or names array to set.

Parameters:

  • toSet:
  • fromSet:
Table:appendArray (t1, t2)
Appends one array to another.

Parameters:

  • t1:
  • t2:

Usage:

    the first array is added to directly, and then returned. 
Table:appendArrays (t1, ...)
Appends one array to another.

Parameters:

  • t1:
  • ...:

Usage:

    the first array is added to directly, and then returned. 
Table:arrayOfSortedKeys (t, sortFunc, reverse)
Get array of sorted keys.

Parameters:

  • t:
  • sortFunc:
  • reverse:
Table:combineArrays (t1, t2)
Like "append", except creates a new array.

Parameters:

  • t1:
  • t2:

Usage:

    Does not check for item duplication. 

Return value:

    new array = combination of two passed arrays.
Table:convertToArray (tbl, keyName, valueName, sorter)
Convert table to array

Parameters:

  • tbl:
  • keyName:
  • valueName:
  • sorter:
Table:copy (t)
Make a shallow copy of a table.

Parameters:

  • t:

Usage:

    Use when it doesn't matter if copy points to same tables/functions as source. 
Table:countItems (t, excl)
Count non-nil items in table.

Parameters:

  • t:
  • excl:

Usage:

    #table-name gives highest assigned item - won't span nil'd items, therefore: this function is for when some have been nil'd out. 
Table:createArrayFromSet (set, sort)
Create an array from a set.

Parameters:

  • set: (table, required) the set.
  • sort: (boolean true, or function, default=don't sort) true for default sort, or function for custom sort.

Usage:

    for when you got a set, but you *need* an array. 
Table:createSet (array, b)
Create a set from an array ###1 b is unused.

Parameters:

  • array:
  • b:
Table:deepCopy (t)
Make a deep copy of a table.

Parameters:

  • t:

Usage:

    All table members will be new copied versions, *except* (@13/Dec/2013 6:22) for functions, which will still be references. 
Table:findInArray (t1, item)
Searches for an item in an array (starting at index 1).

Parameters:

  • t1:
  • item:

Usage:

    very inefficient to call this repeatedly in a loop. 

Return value:

    index or 0 if not found.
Table:getAnyKeyAndValue (t)
Get any key and value.

Parameters:

  • t:
Table:getTable (a, nameToThrow)
Return a value which must be a table or nil.

Parameters:

  • a:
  • nameToThrow:

Usage:

    never throws an error - use when nil is better than a variable of the wrong type. 
Table:getValue (t, dotKeys)
Get (potentially nested) table value given specified key in dot-notation format.

Parameters:

  • t:
  • dotKeys:
Table:initVar (t, n, v, overwriteOk)
Failsafe way to add a member to a table that may already be closed for write access (strict write-access policy has been set).

Parameters:

  • t:
  • n:
  • v:
  • overwriteOk:

Usage:

    Subsequent accesses may be direct without error, even on closed table. 
Table:is (t, valueTitle)
Determine if passed parameter is a table with at least one non-nil element.

Parameters:

  • t:
  • valueTitle:

Usage:

    Note: like str-is method, this function will throw error if non-nil argument isn't a table (e.g. is a string or boolean). 
Table:isArray (t, valueTitle)
Determine if passed parameter represents a table containing values at numeric indexes.

Parameters:

  • t:
  • valueTitle:
Table:isEmpty (t)
Determine if table has no elements.

Parameters:

  • t:

Usage:

    Determine if specified variable includes at least one item in the table, either at a numeric index or as key/value pair. 

Return value:

    boolean
Table:isEquiv (t1, t2, eqFunc)
Determines if two tables (or non-table values) are equivalent.

Parameters:

  • t1:
  • t2:
  • eqFunc:

Return value:

    true iff equivalent members at same indexes, even if order returned by pairs is different.
Table:isEquivalent (t1, t2)
Determines if two tables (or non-table values) are equivalent.

Parameters:

  • t1:
  • t2:

Return value:

    true iff equivalent members at same indexes, even if order returned by pairs is different.
Table:isFoundInArray (t1, item)
Searches for an item in an array.

Parameters:

  • t1:
  • item:

Usage:

    very inefficient to call this repeatedly in a loop. 

Return value:

    boolean
Table:isInArray (array, item)
Determine if item is in array, if so return index (does not check for redundent items).

Parameters:

  • array:
  • item:
Table:isNotEmpty (t)
Determine if table has any elements.

Parameters:

  • t:

Usage:

    Determine if specified variable includes at least one item in the table, either at a numeric index or as key/value pair. 

Return value:

    boolean
Table:md5 (t)
Compute md5 over table elements.

Parameters:

  • t:
Table:mergeArrays (t1, t2)
Like "combine", except DOES check for item duplication.

Parameters:

  • t1:
  • t2:

Usage:

    good for coming up with a new array that includes all items from the passed arrays. 

Return value:

    new array.
Table:mergeSets (...)
Merge two or more sets.

Parameters:

  • ...:

Usage:

    Replaced the above @9/Apr/2014 22:32 (seems to work just fine).
Table:new (t)
Constructor for new instance.

Parameters:

  • t:
Table:newClass (t)
Constructor for extending class.

Parameters:

  • t:
Table:removeFromSet (set, remove)
Add from set to set, or names array to set.

Parameters:

  • set:
  • remove:
Table:replicate (item, count)
Create a table by replicating item, count times.

Parameters:

  • item:
  • count:
Table:reverseArray (t)
Reverse table array order.

Parameters:

  • t:

Usage:

    another way to achieve correct order when the sort function won't give it -
    sort the opposite of what you want, then reverse.

Return value:

    reversed array - the input table remains unaltered.
Table:reverseInPlace (t)
Reverse an array in place.

Parameters:

  • t:
Table:reverseSort (t, reverseSortFunc, dummy)
Sort a homogeneous table in reverse of what you can do with the normal table-sort function, including the stubborn last element.

Parameters:

  • t: the table
  • reverseSortFunc: -- a "reversed sense" sort function.
  • dummy: (same type as a array elements, optional if string or number type elements)

Usage:

  • My experience is that sometimes you want the exact opposite order than what a normal sort is capable of yielding.
    in this case, simply having a unique dummy element (that is guaranteed to be "less" than any of the others) to push through solves the problem.
  • Returns nothing - sorts in place, like reglar table.sort function.
  • throws error if unable to sort properly. 
Table:reverseSortCopy (t, reverseSortFunc, dummy)
Creates a table sorted in reverse of what you can do with the normal table-sort function, including the stubborn last element.

Parameters:

  • t: the table
  • reverseSortFunc: -- a "reversed sense" sort function.
  • dummy: (same type as a array elements, optional if string or number type elements)

Usage:

    My experience is that sometimes you want the exact opposite order than what a normal sort is capable of yielding.
    in this case, simply having a unique dummy element (that is guaranteed to be "less" than any of the others) to push through solves the problem.

Return values:

  1. "Reverse" sorted copy, if possible, otherwise original is returned - original array is always unmodified.
  2. Error message string if unable to sort properly.
Table:setStrict (t, write, read)
Set table member access strictness policy.

Parameters:

  • t:
  • write: (boolean, default false) true => strict write access, false => lax.
  • read: (boolean, default false) true => strict read access, false => lax.

Usage:

  • Do not use for _G - use global-specific set-strict method instead.
  • Useful for closing a table (strict) so accidental assignment or access is caught immediately.
  • Note: one can always use rawset and rawget directly to bypass strictness completely. 
Table:slice (t, i1, i2)
Extract a table slice.

Parameters:

  • t:
  • i1:
  • i2:
Table:sortReverse (t, func)
Sort table in place, reversed.

Parameters:

  • t: - the table
  • func: - a proper sort function.
Table:sortReverseCopy (t, func)
Sort table without altering it, and return a sorted copy, reversed.

Parameters:

  • t: - the table
  • func: - a proper sort function.
Table:sortedPairs (t, sortFunc, reverse)
Return iterator that feeds k,v pairs back to the calling context sorted according to the specified sort function.

Parameters:

  • t:
  • sortFunc:
  • reverse:

Usage:

    sort-func may be nil, in which case default sort order is employed. 

Return value:

    iterator function

Valid XHTML 1.0!