Skip to main content
Version: v0.10.0

Table API

Table helpers are available under ptool.tbl and p.tbl.

These APIs are designed for dense list tables with contiguous integer keys starting at 1.

ptool.tbl.map​

v0.6.0 - Introduced.

ptool.tbl.map(list, fn) transforms each item in a list table and returns a new list.

  • list (table, required): A dense list table.
  • fn (function, required): A callback that receives (value, index) and must return a non-nil value.
  • Returns: table.

Behavior:

  • fn is called once for each item in order.
  • If fn returns nil, the call raises an error instead of creating holes in the result.
  • The input table is not modified.
local out = p.tbl.map({ 10, 20, 30 }, function(value, index)
  return value + index
end)

print(ptool.inspect(out)) -- { 11, 22, 33 }

ptool.tbl.filter​

v0.6.0 - Introduced.

ptool.tbl.filter(list, fn) keeps items whose callback result is truthy and returns them in a new dense list.

  • list (table, required): A dense list table.
  • fn (function, required): A callback that receives (value, index).
  • Returns: table.

Behavior:

  • nil and false remove the current item.
  • Any other Lua value keeps the current item.
  • The returned table is reindexed from 1.
local out = p.tbl.filter({ "a", "bb", "ccc" }, function(value)
  return #value >= 2
end)

print(ptool.inspect(out)) -- { "bb", "ccc" }

ptool.tbl.any​

v0.10.0 - Introduced.

ptool.tbl.any(list, fn) returns true when the callback produces a truthy result for at least one item.

  • list (table, required): A dense list table.
  • fn (function, required): A callback that receives (value, index).
  • Returns: boolean.

Behavior:

  • nil and false are treated as falsy. All other Lua values are treated as truthy.
  • Iteration stops as soon as a truthy result is found.
  • Empty lists return false.
local has_even = p.tbl.any({ 1, 3, 4, 5 }, function(value)
  return value % 2 == 0
end)

print(has_even) -- true

ptool.tbl.all​

v0.10.0 - Introduced.

ptool.tbl.all(list, fn) returns true only when the callback produces a truthy result for every item.

  • list (table, required): A dense list table.
  • fn (function, required): A callback that receives (value, index).
  • Returns: boolean.

Behavior:

  • nil and false are treated as falsy. All other Lua values are treated as truthy.
  • Iteration stops as soon as a falsy result is found.
  • Empty lists return true.
local all_short = p.tbl.all({ "a", "bb", "ccc" }, function(value)
  return #value <= 3
end)

print(all_short) -- true

ptool.tbl.find​

v0.10.0 - Introduced.

ptool.tbl.find(list, fn) returns the first original list value whose callback result is truthy.

  • list (table, required): A dense list table.
  • fn (function, required): A callback that receives (value, index).
  • Returns: any | nil.

Behavior:

  • nil and false are treated as falsy. All other Lua values are treated as truthy.
  • Iteration stops at the first match.
  • Empty lists and no-match cases return nil.
local found = p.tbl.find({ 10, 15, 20 }, function(value)
  return value > 12
end)

print(found) -- 15

ptool.tbl.find_index​

v0.10.0 - Introduced.

ptool.tbl.find_index(list, fn) returns the 1-based index of the first item whose callback result is truthy.

  • list (table, required): A dense list table.
  • fn (function, required): A callback that receives (value, index).
  • Returns: integer | nil.

Behavior:

  • nil and false are treated as falsy. All other Lua values are treated as truthy.
  • Iteration stops at the first match.
  • Empty lists and no-match cases return nil.
local index = p.tbl.find_index({ "cat", "dog", "eel" }, function(value)
  return value == "dog"
end)

print(index) -- 2

ptool.tbl.count​

v0.10.0 - Introduced.

ptool.tbl.count(list, fn) counts how many items produce a truthy callback result.

  • list (table, required): A dense list table.
  • fn (function, required): A callback that receives (value, index).
  • Returns: integer.

Behavior:

  • nil and false are treated as falsy. All other Lua values are treated as truthy.
  • Empty lists return 0.
local total = p.tbl.count({ 1, 2, 3, 4, 5 }, function(value)
  return value % 2 == 1
end)

print(total) -- 3

ptool.tbl.includes​

v0.10.0 - Introduced.

ptool.tbl.includes(list, value) returns true when the list contains the given value.

  • list (table, required): A dense list table.
  • value (any, required): The value to search for.
  • Returns: boolean.

Behavior:

  • The list is scanned from left to right.
  • Equality uses normal Lua == semantics.
  • Empty lists return false.
local has_blue = p.tbl.includes({ "red", "blue", "green" }, "blue")

print(has_blue) -- true

ptool.tbl.reduce​

v0.10.0 - Introduced.

ptool.tbl.reduce(list, initial, fn) folds a list into a single value.

  • list (table, required): A dense list table.
  • initial (any, required): The explicit initial accumulator value.
  • fn (function, required): A callback that receives (acc, value, index) and must return a non-nil value.
  • Returns: any.

Behavior:

  • initial is always required, even for non-empty lists.
  • fn is called once for each item in order.
  • Each callback result becomes the next accumulator value.
  • If fn returns nil, the call raises an error instead of losing the accumulator state.
  • Empty lists return initial unchanged.
local total = p.tbl.reduce({ 5, 10, 15 }, 0, function(acc, value)
  return acc + value
end)

print(total) -- 30

ptool.tbl.flat_map​

v0.10.0 - Introduced.

ptool.tbl.flat_map(list, fn) maps each item to a dense list table and then concatenates those returned lists into one new dense list.

  • list (table, required): A dense list table.
  • fn (function, required): A callback that receives (value, index) and must return a dense list table.
  • Returns: table.

Behavior:

  • fn is called once for each item in order.
  • Each callback result must be a dense list table.
  • Returning a non-table or a non-dense list raises an error.
  • Empty lists return an empty list.
local out = p.tbl.flat_map({ 1, 2, 3 }, function(value)
  return { value, value * 10 }
end)

print(ptool.inspect(out)) -- { 1, 10, 2, 20, 3, 30 }

ptool.tbl.concat​

v0.6.0 - Introduced.

ptool.tbl.concat(...) concatenates one or more dense list tables into a new list.

  • ... (table, required): One or more dense list tables.
  • Returns: table.

Behavior:

  • Arguments are appended from left to right.
  • Empty lists are allowed.
  • The input tables are not modified.
local out = p.tbl.concat({ 1, 2 }, { 3 }, {})

print(ptool.inspect(out)) -- { 1, 2, 3 }

ptool.tbl.join​

v0.6.0 - Introduced.

ptool.tbl.join(...) is an alias of ptool.tbl.concat(...).

  • ... (table, required): One or more dense list tables.
  • Returns: table.
local out = p.tbl.join({ "x" }, { "y", "z" })

print(ptool.inspect(out)) -- { "x", "y", "z" }

List Rules​

ptool.tbl currently supports only dense list tables.

  • Keys must be integers.
  • Keys must start at 1.
  • Keys must be contiguous without gaps.
  • Sparse tables and dictionary-style tables raise errors.