Module utils.table

Table utilities.

There are two ways to call these functions. Either as function, or as chainable methods. The latter can make your code shorter and easier to read.

E.g., instead of:

table.concat(
  table.sort(
    utils.table.map(
      utils.table.keys(words), string.lower
    )
  ),
  " "
)

you can do:

local List = utils.table.List

List(words)
  :keys()
  :map(string.lower)
  :sort()
  :concat(" ")

Functions

List([t]) “Spices us” a table to support chainable methods.
count(t) Count the number of elements.
filter(t, predicate) Filters values.
find(t, predicate) Finds a value.
imap(t, fn) Maps over a sequence.
iterate(t) Iterates over a sequence values.
keys(t) Returns the keys of a table.
makeset(t) Converts a table to a set.
map(t, fn) Maps over a table.
sub(t, first[, last]) Extracts a part of a table.


Functions

List([t])
“Spices us” a table to support chainable methods.

The methods that will be available are the functions mentioned on this page plus the following from standard Lua: insert, remove, sort, concat.

Argument t may be a table, an iterator function, or nothing (which is the same as an empty table).

For efficiency this function does not create a new table but operates in-place: the table’s metatable gets set.

(You may call the unmeta method if you wish to turn it back into a plain table. This simply calls setmetatable(t, nil) for you. But there shouldn’t be a real reason to do that.)

The uppercase L letter in the function name is just a convention meant to make it look like a constructor.

If you'll be using this function more than once, consider aliasing it to prevent visual clutter:

local List = utils.table.List
count(t)
Count the number of elements.

Useful for non-sequences only (use #t otherwise!).

filter(t, predicate)
Filters values.

Returns a new table with only the values that satisfied function predicate. The table t is assumed to be a sequence.

find(t, predicate)
Finds a value.

Returns the first element that satisfy function predicate. The table t is assumed to be a sequence.

imap(t, fn)
Maps over a sequence.

Returns a new table with the results of applying fn to the elements t[1], …, t[#t].

iterate(t)
Iterates over a sequence values.

This is simply an alternative to ipairs in which the keys aren’t returned.

keys(t)
Returns the keys of a table.
makeset(t)
Converts a table to a set.

Returns a new table whose keys are the values of the original table. The new values are all true.

map(t, fn)
Maps over a table.

Returns a new table with the keys preserved and the values the result of applying fn to the original values.

Use imap if your table is a sequence; that is, when the values are keyed from 1 to #t.

Use map if your table may contain arbitrary keys, not necessarily numbers, which you want preserved.

For the sake of documenting your code, use imap whenever it'd work (even when map too would have done the job). Use map only when the table isn’t a sequence.

sub(t, first[, last])
Extracts a part of a table.

Behaves just like Lua’s string.sub except that it operates on a sequence. Negative indexes count from the end of the sequence.

generated by LDoc 1.4.3 Last updated 2016-08-23 17:29:40