Manual:Table Functions

Table Functions

table.complement

table.complement (set1, set2)

Returns a table that is the relative complement of the first table with respect to the second table. Returns a complement of key/value pairs.

Parameters

• table1:
• table2:

Example

local t1 = {key = 1,1,2,3}
t2 = {key = 2,1,1,1}
comp = table.complement(t1,t2)
display(comp)

This prints the following:

  key = 1,
  [2] = 2,
  [3] = 3

Returns

A table containing all the key/value pairs from table1 that do not match the key/value pairs from table2.

table.concat

table.concat(table, delimiter, startingindex, endingindex)

Joins a table into a string. Each item must be something which can be transformed into a string.

Returns the joined string.

See also: string.split

Parameters

• table:

The table to concatenate into a string. Passed as a table.

• delimiter:

Optional string to use to separate each element in the joined string. Passed as a string.

• startingindex:

Optional parameter to specify which index to begin the joining at. Passed as an integer.

• endingindex:

Optional parameter to specify the last index to join. Passed as an integer.

Examples

--This shows a basic concat with none of the optional arguments
testTable = {1,2,"hi","blah",}
testString = table.concat(testTable)
--testString would be equal to "12hiblah"

--This example shows the concat using the optional delimiter
testString = table.concat(testTable, ", ")
--testString would be equal to "1, 2, hi, blah"

--This example shows the concat using the delimiter and the optional starting index
testString = table.concat(testTable, ", ", 2)
--testString would be equal to "2, hi, blah"

--And finally, one which uses all of the arguments
testString = table.concat(testTable, ", ", 2, 3)
--testString would be equal to "2, hi"

table.contains

table.contains (t, value)

Determines if a table contains a value as a key or as a value (recursive).

Returns true or false

Parameters

• t:

The table in which you are checking for the presence of the value.

• value:

The value you are checking for within the table.

Example

local test_table = { "value1", "value2", "value3", "value4" }
if table.contains(test_table, "value1") then 
   echo("Got value 1!")
else
   echo("Don't have it. Sorry!")
end

This example would always echo the first one, unless you remove value1 from the table.

table.deepcopy

table.deepcopy (table)

Returns a complete copy of the table.

Parameters

• table:

The table which you'd like to get a copy of.

Example

local test_table = { "value1", "value2", "value3", "value4" }

-- by just doing:
local newtable = test_table
-- you're linking newtable to test_table. Any change in test_table will be reflected in newtable.

-- however, by doing:
local newtable = table.deepcopy(test_table)
-- the two tables are completely separate now.

table.insert

table.insert(table, [pos,] value)

Inserts element value at position pos in table, shifting up other elements to open space, if necessary. The default value for pos is n+1, where n is the length of the table, so that a call table.insert(t,x) inserts x at the end of table t.

See also: table.remove

Parameters

• table:

The table in which you are inserting the value

• pos:

Optional argument, determining where the value will be inserted.

• value:

The variable that you are inserting into the table. Can be a regular variable, or even a table or function*.

table.index_of

table.index_of(table, value)

Returns the index (location) of an item in an indexed table, or nil if it's not found.

Parameters

• table:

The table in which you are inserting the value

• value:

The variable that you are searching for in the table.

Examples

-- will return 1, because 'hi' is the first item in the list
table.index_of({"hi", "bye", "greetings"}, "hi")

-- will return 3, because 'greetings' is third in the list
table.index_of({"hi", "bye", "greetings"}, "greetings")

-- you can also use this in combination with table.remove(), which requires the location of the item to delete
local words = {"hi", "bye", "greetings"}
table.remove(words, table.index_of(words, "greetings"))

-- however that won't work if the word isn't present, table.remove(mytable, nil (from table.index_of)) will give an error
-- so if you're unsure, confirm with table.contains first
local words = {"hi", "bye", "greetings"}
if table.contains(words, "greetings") then
  table.remove(words, table.index_of(words, "greetings"))
end

table.is_empty

table.is_empty(table)

Check if a table is devoid of any values.

Parameters

• table:

The table you are checking for values.

table.load

table.load(location, table)

Load a table from an external file into mudlet.

See also: table.save

Parameters

• location:

Where you are loading the table from. Can be anywhere on your computer.

• table:

The table that you are loading into - it must exist already.

Example:

-- This will load the table mytable from the lua file mytable present in your Mudlet Home Directory.
mytable = mytable or {}
table.load(getMudletHomeDir().."/mytable.lua", mytable) -- using / is OK on Windows too.
-- You can load a table from anywhere on your computer, but it's preferable to have them consolidated somewhere connected to Mudlet.

table.maxn

table.maxn(table)

Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices. (To do its job this function does a linear traversal of the whole table.)

table.n_union

table.n_union (table1, table2)

Returns a numerically indexed table that is the union of the provided tables (that is - merges two indexed lists together). This is a union of unique values. The order and keys of the input tables are not preserved.

Parameters

• table1: the first table as an indexed list.
• table2: the second table as an indexed list.

Example

display(table.n_union({"bob", "mary"}, {"august", "justinian"}))

{
  "bob",
  "mary",
  "august",
  "justinian"
}

table.n_complement

Returns a table that is the relative complement of the first table with respect to the second table. Returns a complement of values.

table.n_intersection

table.n_intersection(...)

Returns a numerically indexed table that is the intersection of the provided tables. This is an intersection of unique values. The order and keys of the input tables are not preserved.

table.pickle

table.pickle( t, file, tables, lookup )

Internal function used by table.save() for serializing data.

table.remove

table.remove(table, value_position)

Remove a value from an indexed table, by the values position in the table.

See also: table.insert

Parameters

• table

The indexed table you are removing the value from.

• value_position

The indexed number for the value you are removing.

Example

testTable = { "hi", "bye", "cry", "why" }
table.remove(testTable, 1) -- will remove hi from the table
-- new testTable after the remove
testTable = { "bye", "cry", "why" }
-- original position of hi was 1, after the remove, position 1 has become bye
-- any values under the removed value are moved up, 5 becomes 4, 4 becomes 3, etc

Note: To remove a value from a key-value table, it's best to simply change the value to nil.

testTable = { test = "testing", go = "boom", frown = "glow" }
table.remove(testTable, test) -- this will error
testTable.test = nil -- won't error
testTable["test"] = nil -- won't error

table.save

table.save(location, table)

Save a table into an external file in location.

See also: table.load

Parameters

• location:

Where you want the table file to be saved. Can be anywhere on your computer.

• table:

The table that you are saving to the file.

Example:

-- Saves the table mytable to the lua file mytable in your Mudlet Home Directory
table.save(getMudletHomeDir().."/mytable.lua", mytable)

table.sort

table.sort(Table [, comp])

Sorts table elements in a given order, in-place, from Table[1] to Table[n], where n is the length of the table.

If comp is given, then it must be a function that receives two table elements, and returns true when the first is less than the second (so that not comp(a[i+1],a[i]) will be true after the sort). If comp is not given, then the standard Lua operator < is used instead.

The sort algorithm is not stable; that is, elements considered equal by the given order may have their relative positions changed by the sort.

table.size

table.size (t)

Returns the size of a key-value table (this function has to iterate through all of the table to count all elements).

Returns a number.

Parameters

• t:

The table you are checking the size of.

Note: For index based tables you can get the size with the # operator: This is the standard Lua way of getting the size of index tables i.e. ipairs() type of tables with numerical indices. To get the size of tables that use user defined keys instead of automatic indices (pairs() type) you need to use the function table.size() referenced above.

local test_table = { "value1", "value2", "value3", "value4" }
myTableSize = #test_table
-- This would return 4.
local myTable = { 1 = "hello", "key2" = "bye", "key3" = "time to go" }
table.size(myTable)
-- This would return 3.

table.unpickle

table.unpickle( t, tables, tcopy, pickled )

Internal function used by table.load() for deserialization.

table.union

table.union(...)

Returns a table that is the union of the provided tables. This is a union of key/value pairs. If two or more tables contain different values associated with the same key, that key in the returned table will contain a subtable containing all relevant values. See table.n_union() for a union of values. Note that the resulting table may not be reliably traversable with ipairs() due to the fact that it preserves keys. If there is a gap in numerical indices, ipairs() will cease traversal.

Examples

tableA = {
   [1] = 123,
   [2] = 456,
   ["test"] = "test",
}
---
tableB = {
   [1] = 23,
   [3] = 7,
   ["test2"] = function() return true end,
}
---
tableC = {
   [5] = "c",
}
---
table.union(tableA, tableB, tableC)
-- will return the following:
{
   [1] = {
      123,
      23,
   },
   [2] = 456,
   [3] = 7,
   [5] = "c",
   ["test"] = "test",
   ["test2"] = function() return true end,
}