chore: update table.* and tablepool annotations

Author: flrgh

meta/3rd/OpenResty/library/table.clear.lua

@@ -1,3 +1,7 @@
 ---@meta
-function table_clear() end
-return table_clear
+
+--- Clear a table of its contents.
+---@param t table
+local function clear(t) end
+
+return clear

meta/3rd/OpenResty/library/table.clone.lua

@@ -0,0 +1,25 @@
+---@meta
+
+--- Returns a shallow copy of the given Lua table.
+---
+--- This API can be JIT compiled.
+---
+--- Usage:
+---
+--- ```lua
+--- local clone = require "table.clone"
+---
+--- local x = {x=12, y={5, 6, 7}}
+--- local y = clone(x)
+--- ```
+---
+--- **Note:** We observe 7% over-all speedup in the edgelang-fan compiler's
+--- compiling speed whose Lua is generated by the fanlang compiler.
+---
+--- **Note bis:** Deep cloning is planned to be supported by adding `true` as a second argument.
+---
+---@param t table
+---@return table
+local function clone(t) end
+
+return clone

meta/3rd/OpenResty/library/table.isarray.lua

@@ -0,0 +1,23 @@
+---@meta
+
+--- Returns `true` when the given Lua table is a pure array-like Lua table, or
+--- `false` otherwise.
+---
+--- Empty Lua tables are treated as arrays.
+---
+--- This API can be JIT compiled.
+---
+--- Usage:
+---
+--- ```lua
+--- local isarray = require "table.isarray"
+---
+--- print(isarray{"a", true, 3.14})  -- true
+--- print(isarray{dog = 3})  -- false
+--- print(isarray{})  -- true
+--- ```
+---@param t table
+---@return boolean
+local function isarray(t) end
+
+return isarray

meta/3rd/OpenResty/library/table.isempty.lua

@@ -0,0 +1,22 @@
+---@meta
+
+--- Returns `true` when the given Lua table contains neither non-nil array elements nor non-nil key-value pairs, or `false` otherwise.
+---
+--- This API can be JIT compiled.
+--- Usage:
+---
+--- ```lua
+--- local isempty = require "table.isempty"
+---
+--- print(isempty({}))  -- true
+--- print(isempty({nil, dog = nil}))  -- true
+--- print(isempty({"a", "b"}))  -- false
+--- print(isempty({nil, 3}))  -- false
+--- print(isempty({cat = 3}))  -- false
+--- ```
+---
+---@param t table
+---@return boolean
+local function isempty(t) end
+
+return isempty

meta/3rd/OpenResty/library/table.new.lua

@@ -1,3 +1,10 @@
 ---@meta
-function table_new() end
-return table_new
+
+--- Create a new table.
+---
+---@param narr integer number of array-like items
+---@param nrec integer number of hash-like items
+---@return table
+local function new(narr, nrec) end
+
+return new

meta/3rd/OpenResty/library/table.nkeys.lua

@@ -0,0 +1,23 @@
+---@meta
+
+--- Returns the total number of elements in a given Lua table (i.e. from both the
+--- array and hash parts combined).
+---
+--- This API can be JIT compiled.
+---
+--- Usage:
+---
+--- ```lua
+--- local nkeys = require "table.nkeys"
+---
+--- print(nkeys({}))  -- 0
+--- print(nkeys({ "a", nil, "b" }))  -- 2
+--- print(nkeys({ dog = 3, cat = 4, bird = nil }))  -- 2
+--- print(nkeys({ "a", dog = 3, cat = 4 }))  -- 3
+--- ```
+---
+---@param t table
+---@return integer
+local function nkeys(t) end
+
+return nkeys

meta/3rd/OpenResty/library/tablepool.lua

@@ -1,5 +1,29 @@
 ---@meta
-tablepool={}
-function tablepool.release(tag, obj, noclear) end
-function tablepool.fetch(tag, narr, nrec) end
+local tablepool={}
+
+--- Releases the already used Lua table, `tb`, into the table pool named `pool_name`. If the specified table pool does not exist, create it right away.
+---
+--- The caller must *not* continue using the released Lua table, `tb`, after this call. Otherwise random data corruption is expected.
+---
+--- The optional `no_clear` parameter specifies whether to clear the contents in the Lua table `tb` before putting it into the pool. Defaults to `false`, that is, always clearing the Lua table.
+---
+--- If you always initialize all the elements in the Lua table and always use the exactly same number of elements in the Lua table, then you can set this argument to `true` to avoid the overhead of explicit table clearing.
+---
+--- According to the current implementation, for maximum 200 Lua tables can be cached in an individual pool. We may make this configurable in the future. If the specified table pool already exceeds its size limit, then the `tb` table is subject to garbage collection. This behavior is to avoid potential memory leak due to unbalanced `fetch` and `release` method calls.
+---
+---@param pool_name string
+---@param tb        table
+---@param no_clear  boolean
+function tablepool.release(pool_name, tb, no_clear) end
+
+--- Fetches a (free) Lua table from the table pool of the specified name `pool_name`.
+---
+--- If the pool does not exist or the pool is empty, simply create a Lua table whose array part has `narr` elements and whose hash table part has `nrec` elements.
+---
+---@param  pool_name string
+---@param  narr      number size of the array-like part of the table
+---@param  nrec      number size of the hash-like part of the table
+---@return table
+function tablepool.fetch(pool_name, narr, nrec) end
+
 return tablepool