Merge pull request #1138 from C3pa/master

Implement support for LuaJIT's table.new and table.clear #1118

7 files changed, 65 insertions, 18 deletions

diff --git a/locale/en-us/meta.lua b/locale/en-us/meta.lua
index 8e4a2fb1..9ab6aab8 100644
--- a/locale/en-us/meta.lua
+++ b/locale/en-us/meta.lua
@@ -726,6 +726,19 @@ table.foreachi              =
 'Executes the given f over the numerical indices of table. For each index, f is called with the index and respective value as arguments. Indices are visited in sequential order, from 1 to n, where n is the size of the table. If f returns a non-nil value, then the loop is broken and this value is returned as the result of foreachi.'
 table.getn                  =
 'Returns the number of elements in the table. This function is equivalent to `#list`.'
+table.new                   =
+[[This creates a pre-sized table, just like the C API equivalent `lua_createtable()`. This is useful for big tables if the final table size is known and automatic table resizing is too expensive. `narray` parameter specifies the number of array-like items, and `nhash` parameter specifies the number of hash-like items. The function needs to be required before use.
+```lua
+    require("table.new")
+```
+]]
+table.clear                 =
+[[This clears all keys and values from a table, but preserves the allocated array/hash sizes. This is useful when a table, which is linked from multiple places, needs to be cleared and/or when recycling a table for use by the same context. This avoids managing backlinks, saves an allocation and the overhead of incremental array/hash part growth. The function needs to be required before use.
+```lua
+    require("table.clear").
+```
+Please note this function is meant for very specific situations. In most cases it's better to replace the (usually single) link with a new table and let the GC do its work.
+]]
 
 utf8                        =
 ''
diff --git a/locale/pt-br/meta.lua b/locale/pt-br/meta.lua
index 36b08c70..f21dac60 100644
--- a/locale/pt-br/meta.lua
+++ b/locale/pt-br/meta.lua
@@ -293,7 +293,7 @@ debug.getuservalue['<5.3']  =
 debug.getuservalue['>5.4']  =
 [[
 Retorna o `n`-ésimo valor de usuário associado
-aos dados do usuário `u` e um booleano, 
+aos dados do usuário `u` e um booleano,
 `false`, se nos dados do usuário não existir esse valor.
 ]]
 debug.setcstacklimit        =
@@ -726,6 +726,19 @@ table.foreachi              = -- TODO: need translate!
 'Executes the given f over the numerical indices of table. For each index, f is called with the index and respective value as arguments. Indices are visited in sequential order, from 1 to n, where n is the size of the table. If f returns a non-nil value, then the loop is broken and this value is returned as the result of foreachi.'
 table.getn                  = -- TODO: need translate!
 'Returns the number of elements in the table. This function is equivalent to `#list`.'
+table.new                   = -- TODO: need translate!
+[[This creates a pre-sized table, just like the C API equivalent `lua_createtable()`. This is useful for big tables if the final table size is known and automatic table resizing is too expensive. `narray` parameter specifies the number of array-like items, and `nhash` parameter specifies the number of hash-like items. The function needs to be required before use.
+```lua
+	require("table.new")
+```
+]]
+table.clear                 = -- TODO: need translate!
+[[This clears all keys and values from a table, but preserves the allocated array/hash sizes. This is useful when a table, which is linked from multiple places, needs to be cleared and/or when recycling a table for use by the same context. This avoids managing backlinks, saves an allocation and the overhead of incremental array/hash part growth. The function needs to be required before use.
+```lua
+	require("table.clear").
+```
+Please note this function is meant for very specific situations. In most cases it's better to replace the (usually single) link with a new table and let the GC do its work.
+]]
 
 utf8                        =
 ''
diff --git a/locale/zh-cn/meta.lua b/locale/zh-cn/meta.lua
index a192ff72..a8b69959 100644
--- a/locale/zh-cn/meta.lua
+++ b/locale/zh-cn/meta.lua
@@ -734,6 +734,19 @@ table.foreachi              =
 '遍历数组中的每一个元素，并以索引号index和value执行回调函数。如果回调函数返回一个非nil值则循环终止,并且返回这个值。该函数等同ipair(list),比ipair(list)更慢。不推荐使用'
 table.getn                  =
 '返回表的长度。该函数等价于#list。'
+table.new                   = -- TODO: need translate!
+[[This creates a pre-sized table, just like the C API equivalent `lua_createtable()`. This is useful for big tables if the final table size is known and automatic table resizing is too expensive. `narray` parameter specifies the number of array-like items, and `nhash` parameter specifies the number of hash-like items. The function needs to be required before use.
+```lua
+    require("table.new")
+```
+]]
+table.clear                 = -- TODO: need translate!
+[[This clears all keys and values from a table, but preserves the allocated array/hash sizes. This is useful when a table, which is linked from multiple places, needs to be cleared and/or when recycling a table for use by the same context. This avoids managing backlinks, saves an allocation and the overhead of incremental array/hash part growth. The function needs to be required before use.
+```lua
+    require("table.clear").
+```
+Please note this function is meant for very specific situations. In most cases it's better to replace the (usually single) link with a new table and let the GC do its work.
+]]
 
 utf8                        =
 ''
diff --git a/locale/zh-tw/meta.lua b/locale/zh-tw/meta.lua
index d6ec50d3..61d3f239 100644
--- a/locale/zh-tw/meta.lua
+++ b/locale/zh-tw/meta.lua
@@ -734,6 +734,19 @@ table.foreachi              =
 '走訪表中的每一個元素，並以索引號index和value執行回呼函式。如果回呼函式回傳一個非nil值則循環終止,並且回傳這個值。該函式等同ipair(list),比ipair(list)更慢。不推薦使用'
 table.getn                  =
 '回傳表的長度。該函式等價於#list。'
+table.new                   = -- TODO: need translate!
+[[This creates a pre-sized table, just like the C API equivalent `lua_createtable()`. This is useful for big tables if the final table size is known and automatic table resizing is too expensive. `narray` parameter specifies the number of array-like items, and `nhash` parameter specifies the number of hash-like items. The function needs to be required before use.
+```lua
+    require("table.new")
+```
+]]
+table.clear                 = -- TODO: need translate!
+[[This clears all keys and values from a table, but preserves the allocated array/hash sizes. This is useful when a table, which is linked from multiple places, needs to be cleared and/or when recycling a table for use by the same context. This avoids managing backlinks, saves an allocation and the overhead of incremental array/hash part growth. The function needs to be required before use.
+```lua
+    require("table.clear").
+```
+Please note this function is meant for very specific situations. In most cases it's better to replace the (usually single) link with a new table and let the GC do its work.
+]]
 
 utf8                        =
 ''
diff --git a/meta/3rd/OpenResty/library/table.clear.lua b/meta/3rd/OpenResty/library/table.clear.lua
deleted file mode 100644
index ba6dfa24..00000000
--- a/meta/3rd/OpenResty/library/table.clear.lua
+++ /dev/null
@@ -1,7 +0,0 @@
----@meta
-
---- Clear a table of its contents.
----@param t table
-local function clear(t) end
-
-return clear
\ No newline at end of file
diff --git a/meta/3rd/OpenResty/library/table.new.lua b/meta/3rd/OpenResty/library/table.new.lua
deleted file mode 100644
index 385fa672..00000000
--- a/meta/3rd/OpenResty/library/table.new.lua
+++ /dev/null
@@ -1,10 +0,0 @@
----@meta
-
---- 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
\ No newline at end of file
diff --git a/meta/template/table.lua b/meta/template/table.lua
index a7fe68d2..b0a386c3 100644
--- a/meta/template/table.lua
+++ b/meta/template/table.lua
@@ -92,4 +92,16 @@ function table.foreachi(list, callback) end
 ---@deprecated
 function table.getn(list) end
 
+---@version JIT
+---#DES 'table.new'
+---@param narray integer
+---@param nhash integer
+---@return table
+function table.new(narray, nhash) end
+
+---@version JIT
+---#DES 'table.clear'
+---@param tab table
+function table.clear(tab) end
+
 return table