Pular para o conteúdo principal
Versão: v0.10.0

API de tabelas

Os utilitários de tabelas estão disponíveis em ptool.tbl e p.tbl.

Essas APIs foram projetadas para tabelas de lista densas, com chaves inteiras contíguas começando em 1.

ptool.tbl.map​

v0.6.0 - Introduzido.

ptool.tbl.map(list, fn) transforma cada item de uma tabela de lista e retorna uma nova lista.

  • list (table, obrigatório): Uma tabela de lista densa.
  • fn (function, obrigatório): Um callback que recebe (value, index) e deve retornar um valor diferente de nil.
  • Retorna: table.

Comportamento:

  • fn é chamado uma vez para cada item, em ordem.
  • Se fn retornar nil, a chamada falha em vez de criar buracos no resultado.
  • A tabela de entrada não é modificada.
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 - Introduzido.

ptool.tbl.filter(list, fn) mantém os itens cujo resultado do callback seja truthy e os retorna em uma nova lista densa.

  • list (table, obrigatório): Uma tabela de lista densa.
  • fn (function, obrigatório): Um callback que recebe (value, index).
  • Retorna: table.

Comportamento:

  • nil e false removem o item atual.
  • Qualquer outro valor Lua mantém o item atual.
  • A tabela retornada é reindexada a partir de 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 - Introduzido.

ptool.tbl.any(list, fn) retorna true quando o callback produz um resultado truthy para pelo menos um item.

  • list (table, obrigatório): Uma tabela de lista densa.
  • fn (function, obrigatório): Um callback que recebe (value, index).
  • Retorna: boolean.

Comportamento:

  • nil e false são tratados como falsy. Todos os outros valores Lua são tratados como truthy.
  • A iteração para assim que um resultado truthy é encontrado.
  • Listas vazias retornam 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 - Introduzido.

ptool.tbl.all(list, fn) retorna true somente quando o callback produz um resultado truthy para cada item.

  • list (table, obrigatório): Uma tabela de lista densa.
  • fn (function, obrigatório): Um callback que recebe (value, index).
  • Retorna: boolean.

Comportamento:

  • nil e false são tratados como falsy. Todos os outros valores Lua são tratados como truthy.
  • A iteração para assim que um resultado falsy é encontrado.
  • Listas vazias retornam 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 - Introduzido.

ptool.tbl.find(list, fn) retorna o primeiro valor original da lista cujo resultado do callback é truthy.

  • list (table, obrigatório): Uma tabela de lista densa.
  • fn (function, obrigatório): Um callback que recebe (value, index).
  • Retorna: any | nil.

Comportamento:

  • nil e false são tratados como falsy. Todos os outros valores Lua são tratados como truthy.
  • A iteração para na primeira correspondência.
  • Listas vazias e casos sem correspondência retornam 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 - Introduzido.

ptool.tbl.find_index(list, fn) retorna o índice baseado em 1 do primeiro item cujo resultado do callback é truthy.

  • list (table, obrigatório): Uma tabela de lista densa.
  • fn (function, obrigatório): Um callback que recebe (value, index).
  • Retorna: integer | nil.

Comportamento:

  • nil e false são tratados como falsy. Todos os outros valores Lua são tratados como truthy.
  • A iteração para na primeira correspondência.
  • Listas vazias e casos sem correspondência retornam 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 - Introduzido.

ptool.tbl.count(list, fn) conta quantos itens produzem um resultado truthy no callback.

  • list (table, obrigatório): Uma tabela de lista densa.
  • fn (function, obrigatório): Um callback que recebe (value, index).
  • Retorna: integer.

Comportamento:

  • nil e false são tratados como falsy. Todos os outros valores Lua são tratados como truthy.
  • Listas vazias retornam 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 - Introduzido.

ptool.tbl.includes(list, value) retorna true quando a lista contém o valor fornecido.

  • list (table, obrigatório): Uma tabela de lista densa.
  • value (any, obrigatório): O valor a ser procurado.
  • Retorna: boolean.

Comportamento:

  • A lista é percorrida da esquerda para a direita.
  • A igualdade usa a semântica normal de == do Lua.
  • Listas vazias retornam false.
local has_blue = p.tbl.includes({ "red", "blue", "green" }, "blue")

print(has_blue) -- true

ptool.tbl.reduce​

v0.10.0 - Introduzido.

ptool.tbl.reduce(list, initial, fn) reduz uma lista a um único valor.

  • list (table, obrigatório): Uma tabela de lista densa.
  • initial (any, obrigatório): O valor inicial explícito do acumulador.
  • fn (function, obrigatório): Um callback que recebe (acc, value, index) e deve retornar um valor diferente de nil.
  • Retorna: any.

Comportamento:

  • initial é sempre obrigatório, mesmo para listas não vazias.
  • fn é chamado uma vez para cada item, em ordem.
  • Cada resultado do callback se torna o próximo valor do acumulador.
  • Se fn retornar nil, a chamada gera um erro em vez de perder o estado do acumulador.
  • Listas vazias retornam initial sem alterações.
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 - Introduzido.

ptool.tbl.flat_map(list, fn) mapeia cada item para uma tabela de lista densa e então concatena essas listas retornadas em uma nova lista densa.

  • list (table, obrigatório): Uma tabela de lista densa.
  • fn (function, obrigatório): Um callback que recebe (value, index) e deve retornar uma tabela de lista densa.
  • Retorna: table.

Comportamento:

  • fn é chamado uma vez para cada item, em ordem.
  • Cada resultado do callback deve ser uma tabela de lista densa.
  • Retornar um valor que não seja tabela ou uma lista não densa gera um erro.
  • Listas vazias retornam uma lista vazia.
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 - Introduzido.

ptool.tbl.concat(...) concatena uma ou mais tabelas de lista densas em uma nova lista.

  • ... (table, obrigatório): Uma ou mais tabelas de lista densas.
  • Retorna: table.

Comportamento:

  • Os argumentos são anexados da esquerda para a direita.
  • Listas vazias são permitidas.
  • As tabelas de entrada não são modificadas.
local out = p.tbl.concat({ 1, 2 }, { 3 }, {})

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

ptool.tbl.join​

v0.6.0 - Introduzido.

ptool.tbl.join(...) é um alias de ptool.tbl.concat(...).

  • ... (table, obrigatório): Uma ou mais tabelas de lista densas.
  • Retorna: table.
local out = p.tbl.join({ "x" }, { "y", "z" })

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

Regras de lista​

ptool.tbl atualmente suporta apenas tabelas de lista densas.

  • As chaves devem ser inteiras.
  • As chaves devem começar em 1.
  • As chaves devem ser contíguas, sem buracos.
  • Tabelas esparsas e tabelas no estilo dicionário geram erro.