User Tools

Site Tools


lgscript:table_library

Table Library

The table functions accept a table as the first parameter. Tables are not created with a metatable by default, but the table module can be used as a metatable. If you type T=setmetatable({},table), then you have created a table with which you can call these functions as methods.

concat

Create a string from the values in a table.

Returns string The values of the table joined together.
Parameter table A table.
Parameter string (opt.) String to insert between values.
Parameter number (opt.) The first index to join.
Parameter number (opt.) The last index to join.

extend

Insert values into a table from another table.

Returns table The modified table.
Parameter table Destination table.
Parameter table Source table.

Inserts all of the values from the source table into the destination table. Values with integer keys will be added after the existing integer keys of the destination. Indexes that aren’t integers will overwrite the values in the destination.

find

Search for a value in a table.

Returns any The index of the value if found, or nil.
Parameter table The table to search in.
Parameter any A value to search for.

foreach

Run a function using each value in a table.

Returns any Value returned from the callback function.
Parameter table A table.
Parameter function A callback function.

The callback function is called repeatedly with each entry in the table. The parameters to the function are the index and value of the table entry. If the function returns something other than nil, then the foreach function will stop reading the table and immediately return that value.

Using pairs with a for-in loop is preferable to this function.

foreachi

Run a function using each integer index in a table.

Returns any Value returned from the callback function.
Parameter table A table.
Parameter function A callback function.

The callback function is called repeatedly with each integer index in the table. The parameters to the function are the index and value of the table entry. If the function returns something other than nil, then the foreachi function will stop reading the table and immediately return that value.

Using ipairs with a for-in loop is preferable to this function.

getn

Get the value of the # operator.

Returns number The “length” of the table.
Parameter table A table.

Like the # operator, getn returns the value of the “last” integer index in the table. This is not always the largest index, but is one where the next larger index is not used. So the value of the table at table.getn(T)+1 is nil.

keys

Create a table with the keys of another table.

Returns table The keys of the table in a new table.
Parameter table A table.

Extracts the used indexes in a table and fills a new table with the keys as values. The integer keys are included.

maxn

Find the largest index in the table.

Returns number The largest index in the table.
Parameter table A table.

Finds the largest integer index in the table that has a value set. All of the possible integer indexes must be checked, so this can be slow.

merge

Combine two tables with overlapping keys.

Returns table The modified table.
Parameter table Destination table.
Parameter table Source table.

Inserts all of the values from the source table into the destination table. Entries in the source that have the same index as in the destination will be overwritten.

insert

Put values in a table.

Returns table The modified table.
Parameter table Destination table.
Parameter number (opt.) Index where the values will be inserted. Default is at the end.
Parameter any ... Values to insert.

The given values are stored in consecutive integer indexes of the table. If no index is given, then the value is added in the next unused integer index. Passing an index will add the values starting at that index. Existing values will be shifted to higher indexes to make room. If more than one value is being inserted, then the index must be specified.

pack

Create a table with a list of values.

Returns table The table with packed values.
Parameter any ... Values to fill the table with.

The arguments to the function will be assigned to consecutive integer indexes in a new table. The table key n is set to the number of arguments passed to the function. The list of arguments can be reconstructed from the table with table.unpack(T, 1, T.n).

remove

Delete values from a table.

Returns any ... The values removed from the table.
Parameter table The table.
Parameter number (opt.) The first index to remove.
Parameter number (opt.) The last index to remove.

When a value is removed from a table, other values will be shifted down to fill the hole. With no indexes specified, the last used index in the table is removed. If only one index is given, then just that value is removed. If the last index is less than the first index, then nothing is removed.

reverse

Reverse the order of the values in a table.

Parameter table A table.

The order of the values in integer indexes of the table will be reversed.

sort

Change the order of values in a table.

Parameter table A table.
Parameter function (opt.) Comparison function.

Sorts the values in a table. Values are compared using the standard < operator by default. You can pass a function that takes two parameters and returns true if the first is less than the second.

unpack

Get the values in a table.

Returns any ... The values from the table.
Parameter table A table to unpack.
Parameter integer (opt.) The first index to unpack.
Parameter integer (opt.) The last index to unpack.

The values from the table with consecutive integer indexes will be returned.

values

Create a table using the values of another table.

Returns table The values of the table in a new table.
Parameter table A table.

Extracts all the values from a table and creates a new table that uses consecutive integer indexes.

lgscript/table_library.txt · Last modified: 2011/05/19 00:45 by telliamed