From 4593fb5e29adc09cd53beaba8777f5656434c08d Mon Sep 17 00:00:00 2001
From: Mike Pall <mike>
Date: Mon, 25 Nov 2013 15:18:31 +0100
Subject: Add table.clear().

---
 doc/extensions.html | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

(limited to 'doc')

diff --git a/doc/extensions.html b/doc/extensions.html
index 48f4220c..3443f201 100644
--- a/doc/extensions.html
+++ b/doc/extensions.html
@@ -217,6 +217,22 @@ tables if the final table size is known and automatic table resizing is
 too expensive.
 </p>
 
+<h3 id="table_clear"><tt>table.clear(tab)</tt> clears a table</h3>
+<p>
+An extra library function <tt>table.clear()</tt> can be made available
+via <tt>require("table.clear")</tt>. 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.
+</p>
+<p>
+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.
+</p>
+
 <h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
 <p>
 LuaJIT uses a Tausworthe PRNG with period 2^223 to implement
-- 
cgit v1.2.3-55-g6feb