Updated docs

2 files changed, 222 insertions, 40 deletions

diff --git a/doc/index.html b/doc/index.html
index ab377b3..9fc4cf3 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -56,7 +56,7 @@
     <h3>Info:</h3>
     <ul>
         <li><strong>Copyright</strong>: 2012-2017</li>
-        <li><strong>Release</strong>: 1.6.0</li>
+        <li><strong>Release</strong>: 1.6.1</li>
         <li><strong>License</strong>: <a href="http://www.opensource.org/licenses/mit-license.php">MIT</a></li>
         <li><strong>Author</strong>: <a href="http://github.com/Yonaba">Roland Yonaba</a></li>
     </ul>
@@ -65,6 +65,10 @@
 <h2><a href="#Table_functions">Table functions </a></h2>
 <table class="function_list">
 	<tr>
+	<td class="name" nowrap><a href="#clear">clear (t)</a></td>
+	<td class="summary">Clears a table.</td>
+	</tr>
+	<tr>
 	<td class="name" nowrap><a href="#each">each (t, f[, ...])</a></td>
 	<td class="summary">Iterates on key-value pairs, calling <code>f (k, v)</code> at every step.</td>
 	</tr>
@@ -337,7 +341,7 @@
 	</tr>
 	<tr>
 	<td class="name" nowrap><a href="#append">append (array, other)</a></td>
-	<td class="summary">Clones <code>array</code> and appends <code>other</code> values.</td>
+	<td class="summary">Clones <a href="index.html#array">array</a> and appends <code>other</code> values.</td>
 	</tr>
 	<tr>
 	<td class="name" nowrap><a href="#interleave">interleave (...)</a></td>
@@ -345,7 +349,7 @@
 	</tr>
 	<tr>
 	<td class="name" nowrap><a href="#interpose">interpose (value, array)</a></td>
-	<td class="summary">Interposes value in-between consecutive pair of values in <code>array</code>.</td>
+	<td class="summary">Interposes value in-between consecutive pair of values in <a href="index.html#array">array</a>.</td>
 	</tr>
 	<tr>
 	<td class="name" nowrap><a href="#range">range ([from[, to[, step]]])</a></td>
@@ -391,12 +395,16 @@
 	<td class="summary">Creates a constant function which returns the same output on every call.</td>
 	</tr>
 	<tr>
+	<td class="name" nowrap><a href="#memoize">memoize (f[, hash])</a></td>
+	<td class="summary">Memoizes a given function by caching the computed result.</td>
+	</tr>
+	<tr>
 	<td class="name" nowrap><a href="#once">once (f)</a></td>
 	<td class="summary">Returns a version of <code>f</code> that runs only once.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#memoize">memoize (f[, hash])</a></td>
-	<td class="summary">Memoizes a given function by caching the computed result.</td>
+	<td class="name" nowrap><a href="#before">before (f, count)</a></td>
+	<td class="summary">Returns a version of <code>f</code> that will run no more than <a href="index.html#count">count</a> times.</td>
 	</tr>
 	<tr>
 	<td class="name" nowrap><a href="#after">after (f, count)</a></td>
@@ -447,10 +455,14 @@
 	<td class="summary">Generates an unique ID for the current session.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#iterate">iterate (f, x)</a></td>
+	<td class="name" nowrap><a href="#iterator">iterator (f, x)</a></td>
 	<td class="summary">Produces an iterator which repeatedly apply a function <code>f</code> onto an input.</td>
 	</tr>
 	<tr>
+	<td class="name" nowrap><a href="#array">array (...)</a></td>
+	<td class="summary">Iterates an iterator and returns its values in an array.</td>
+	</tr>
+	<tr>
 	<td class="name" nowrap><a href="#flip">flip (f)</a></td>
 	<td class="summary">Creates a function of <code>f</code> with arguments flipped in reverse order.</td>
 	</tr>
@@ -482,6 +494,10 @@
 	<td class="name" nowrap><a href="#curry">curry (f[, n_args])</a></td>
 	<td class="summary">Curries a function.</td>
 	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#time">time (f[, ...])</a></td>
+	<td class="summary">Returns the execution time of <code>f (&hellip;)</code> and its returned values.</td>
+	</tr>
 </table>
 <h2><a href="#Object_functions">Object functions </a></h2>
 <table class="function_list">
@@ -627,6 +643,31 @@
 
     <dl class="function">
     <dt>
+    <a name = "clear"></a>
+    <strong>clear (t)</strong>
+    </dt>
+    <dd>
+    Clears a table.  All its values become nil.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">t</span>
+         a table
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        the given table, cleared.
+    </ol>
+
+
+
+
+</dd>
+    <dt>
     <a name = "each"></a>
     <strong>each (t, f[, ...])</strong>
     </dt>
@@ -2773,8 +2814,8 @@
     <strong>symmetricDifference (array, array2)</strong>
     </dt>
     <dd>
-    Performs a symmetric difference.  Returns values from <code>array</code> not present in <code>array2</code> and also values
- from <code>array2</code> not present in <code>array</code>.
+    Performs a symmetric difference.  Returns values from <a href="index.html#array">array</a> not present in <code>array2</code> and also values
+ from <code>array2</code> not present in <a href="index.html#array">array</a>.
  <br/><em>Aliased as <code>symdiff</code></em>
 
 
@@ -2897,7 +2938,7 @@
     <strong>append (array, other)</strong>
     </dt>
     <dd>
-    Clones <code>array</code> and appends <code>other</code> values.
+    Clones <a href="index.html#array">array</a> and appends <code>other</code> values.
 
 
     <h3>Parameters:</h3>
@@ -2955,7 +2996,7 @@
     <strong>interpose (value, array)</strong>
     </dt>
     <dd>
-    Interposes value in-between consecutive pair of values in <code>array</code>.
+    Interposes value in-between consecutive pair of values in <a href="index.html#array">array</a>.
 
 
     <h3>Parameters:</h3>
@@ -3284,6 +3325,38 @@
 
 </dd>
     <dt>
+    <a name = "memoize"></a>
+    <strong>memoize (f[, hash])</strong>
+    </dt>
+    <dd>
+    Memoizes a given function by caching the computed result.
+ Useful for speeding-up slow-running functions. If a <code>hash</code> function is passed,
+ it will be used to compute hash keys for a set of input values for caching.
+ <br/><em>Aliased as <code>cache</code></em>
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">f</span>
+         a function
+        </li>
+        <li><span class="parameter">hash</span>
+         a hash function, defaults to <a href="index.html#identity">identity</a>
+         (<em>optional</em>)
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        a new function
+    </ol>
+
+
+
+
+</dd>
+    <dt>
     <a name = "once"></a>
     <strong>once (f)</strong>
     </dt>
@@ -3309,20 +3382,19 @@
 
     <h3>See also:</h3>
     <ul>
-         <a href="index.html#after">after</a>
+         <li><a href="index.html#before">before</a></li>
+         <li><a href="index.html#after">after</a></li>
     </ul>
 
 
 </dd>
     <dt>
-    <a name = "memoize"></a>
-    <strong>memoize (f[, hash])</strong>
+    <a name = "before"></a>
+    <strong>before (f, count)</strong>
     </dt>
     <dd>
-    Memoizes a given function by caching the computed result.
- Useful for speeding-up slow-running functions. If a <code>hash</code> function is passed,
- it will be used to compute hash keys for a set of input values for caching.
- <br/><em>Aliased as <code>cache</code></em>
+    Returns a version of <code>f</code> that will run no more than <a href="index.html#count">count</a> times.  Next calls will
+ keep yielding the results of the count-th call.
 
 
     <h3>Parameters:</h3>
@@ -3330,9 +3402,8 @@
         <li><span class="parameter">f</span>
          a function
         </li>
-        <li><span class="parameter">hash</span>
-         a hash function, defaults to <a href="index.html#identity">identity</a>
-         (<em>optional</em>)
+        <li><span class="parameter">count</span>
+         a count
         </li>
     </ul>
 
@@ -3343,6 +3414,11 @@
     </ol>
 
 
+    <h3>See also:</h3>
+    <ul>
+         <li><a href="index.html#once">once</a></li>
+         <li><a href="index.html#after">after</a></li>
+    </ul>
 
 
 </dd>
@@ -3374,7 +3450,8 @@
 
     <h3>See also:</h3>
     <ul>
-         <a href="index.html#once">once</a>
+         <li><a href="index.html#once">once</a></li>
+         <li><a href="index.html#before">before</a></li>
     </ul>
 
 
@@ -3732,8 +3809,8 @@
 
 </dd>
     <dt>
-    <a name = "iterate"></a>
-    <strong>iterate (f, x)</strong>
+    <a name = "iterator"></a>
+    <strong>iterator (f, x)</strong>
     </dt>
     <dd>
     Produces an iterator which repeatedly apply a function <code>f</code> onto an input.<br/>
@@ -3762,6 +3839,31 @@
 
 </dd>
     <dt>
+    <a name = "array"></a>
+    <strong>array (...)</strong>
+    </dt>
+    <dd>
+    Iterates an iterator and returns its values in an array.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">...</span>
+         an iterator (a function, a table and a value)
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        an array of results
+    </ol>
+
+
+
+
+</dd>
+    <dt>
     <a name = "flip"></a>
     <strong>flip (f)</strong>
     </dt>
@@ -4020,6 +4122,35 @@
 
 
 </dd>
+    <dt>
+    <a name = "time"></a>
+    <strong>time (f[, ...])</strong>
+    </dt>
+    <dd>
+    Returns the execution time of <code>f (&hellip;)</code> and its returned values.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">f</span>
+         a function
+        </li>
+        <li><span class="parameter">...</span>
+         optional args to <code>f</code>
+         (<em>optional</em>)
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        the execution time and the results of <code>f (&hellip;)</code>
+    </ol>
+
+
+
+
+</dd>
 </dl>
     <h2 class="section-header "><a name="Object_functions"></a>Object functions </h2>
 
@@ -4944,7 +5075,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2017-04-14 15:33:56 </i>
+<i style="float:right;">Last updated 2017-04-29 09:39:57 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/doc/topics/tutorial.md.html b/doc/topics/tutorial.md.html
index f400ea5..eaa7a2c 100644
--- a/doc/topics/tutorial.md.html
+++ b/doc/topics/tutorial.md.html
@@ -97,6 +97,15 @@ It complements built-in Lua functions, making easier common operations on tables
 
 <h2><a name='table'>Table functions</a></h2>
 
+<h3>clear (t)</h3>
+
+<p>Clears a table. All its values becomes nil. It returns the passed-in table.</p>
+
+<pre>
+<span class="keyword">local</span> t = _.clear({<span class="number">1</span>,<span class="number">2</span>,<span class="string">'hello'</span>,<span class="keyword">true</span>}) <span class="comment">-- =&gt; {}</span>
+</pre>
+
+
 <h3>each (t, f, &hellip;)</h3>
 
 <p><em>Aliases: <code>_.forEach</code></em>.</p>
@@ -537,7 +546,7 @@ _.invoke({a,b,c,d},<span class="string">'call'</span>) <span class="comment">--
 
 <h3>pluck (t, property)</h3>
 
-<p>Fetches all values indxed with specific key in a table of objects.</p>
+<p>Fetches all values indexed with specific key in a table of objects.</p>
 
 <pre>
 <span class="keyword">local</span> peoples = {
@@ -1430,7 +1439,7 @@ _.identity(<span class="number">1</span>)<span class="comment">-- =&gt; 1
 
 <h3>constant (value)</h3>
 
-<p>Creates a constant function. This function will constinuously yield the same output.</p>
+<p>Creates a constant function. This function will continuously yield the same output.</p>
 
 <pre>
 <span class="keyword">local</span> pi = _.constant(<span class="global">math</span>.pi)
@@ -1440,6 +1449,22 @@ pi(<span class="number">1</span>) <span class="comment">-- =&gt; 3.1415926535898
 </pre>
 
 
+<h3>memoize (f, hash)</h3>
+
+<p><em>Aliases: <code>_.cache</code></em>.</p>
+
+<p>Memoizes a slow-running function. It caches the result for a specific input, so that the next time the function is called with the same input, it will lookup the result in its cache, instead of running again the function body.</p>
+
+<pre>
+<span class="keyword">local</span> <span class="keyword">function</span> fibonacci(n)
+  <span class="keyword">return</span> n &lt; <span class="number">2</span> <span class="keyword">and</span> n <span class="keyword">or</span> fibonacci(n-<span class="number">1</span>)+fibonacci(n-<span class="number">2</span>)
+<span class="keyword">end</span>
+<span class="keyword">local</span> mem_fibonacci = _.memoize(fibonacci)
+fibonacci(<span class="number">20</span>) <span class="comment">-- =&gt; 6765 (but takes some time)
+</span>mem_fibonacci(<span class="number">20</span>) <span class="comment">-- =&gt; 6765 (takes less time)</span>
+</pre>
+
+
 <h3>once (f)</h3>
 
 <p>Produces a function that runs only once. Successive calls to this function will still yield the same input.</p>
@@ -1454,19 +1479,18 @@ sq(<span class="number">1</span>) <span class="comment">-- =&gt; 1
 </pre>
 
 
-<h3>memoize (f, hash)</h3>
-
-<p><em>Aliases: <code>_.cache</code></em>.</p>
+<h3>before (f, count)</h3>
 
-<p>Memoizes a slow-running function. It caches the result for a specific input, so that the next time the function is called with the same input, it will lookup the result in its cache, instead of running again the function body.</p>
+<p>Returns a version of <code>f</code> that will run no more than <a href="../index.html#count">count</a> times. Next calls will keep yielding the results of the (n-th)-1 call.</p>
 
 <pre>
-<span class="keyword">local</span> <span class="keyword">function</span> fibonacci(n)
-  <span class="keyword">return</span> n &lt; <span class="number">2</span> <span class="keyword">and</span> n <span class="keyword">or</span> fibonacci(n-<span class="number">1</span>)+fibonacci(n-<span class="number">2</span>)
-<span class="keyword">end</span>
-<span class="keyword">local</span> mem_fibonacci = _.memoize(fibonacci)
-fibonacci(<span class="number">20</span>) <span class="comment">-- =&gt; 6765 (but takes some time)
-</span>mem_fibonacci(<span class="number">20</span>) <span class="comment">-- =&gt; 6765 (takes less time)</span>
+<span class="keyword">local</span> <span class="keyword">function</span> greet(someone) <span class="keyword">return</span> <span class="string">'hello '</span>..someone <span class="keyword">end</span>
+<span class="keyword">local</span> greetOnly3people = _.before(greet, <span class="number">3</span>)
+greetOnly3people(<span class="string">'John'</span>) <span class="comment">-- =&gt; 'hello John'
+</span>greetOnly3people(<span class="string">'Moe'</span>) <span class="comment">-- =&gt; 'hello Moe'
+</span>greetOnly3people(<span class="string">'James'</span>) <span class="comment">-- =&gt; 'hello James'
+</span>greetOnly3people(<span class="string">'Joseph'</span>) <span class="comment">-- =&gt; 'hello James'
+</span>greetOnly3people(<span class="string">'Allan'</span>) <span class="comment">-- =&gt; 'hello James'</span>
 </pre>
 
 
@@ -1654,6 +1678,17 @@ iter_po2() <span class="comment">-- =&gt; 2
 </pre>
 
 
+<h3>array (&hellip;)</h3>
+
+<p>Iterates a given iterator function and returns its values packed in an array.</p>
+
+<pre>
+<span class="keyword">local</span> text = <span class="string">'letters'</span>
+<span class="keyword">local</span> chars = <span class="global">string</span>.gmatch(text, <span class="string">'.'</span>)
+<span class="keyword">local</span> letters = _.array(chars) <span class="comment">-- =&gt; {'l','e','t','t','e','r','s'}</span>
+</pre>
+
+
 <h3>flip (f)</h3>
 
 <p>Creates a function of <code>f</code> with arguments flipped in reverse order.</p>
@@ -1819,8 +1854,8 @@ concat_right(<span class="string">'b'</span>,<span class="string">'c'</span>,<sp
 <pre>
 <span class="keyword">local</span> <span class="keyword">function</span> sumOf3args(x,y,z) <span class="keyword">return</span> x + y + z <span class="keyword">end</span>
 <span class="keyword">local</span> curried_sumOf3args = _.curry(sumOf3args, <span class="number">3</span>)
-sumOf3args(<span class="number">1</span>)(<span class="number">2</span>)(<span class="number">3</span>)) <span class="comment">-- =&gt; 6
-</span>sumOf3args(<span class="number">0</span>)(<span class="number">6</span>)(<span class="number">9</span>)) <span class="comment">-- =&gt; 15</span>
+sumOf3args(<span class="number">1</span>)(<span class="number">2</span>)(<span class="number">3</span>) <span class="comment">-- =&gt; 6
+</span>sumOf3args(<span class="number">0</span>)(<span class="number">6</span>)(<span class="number">9</span>) <span class="comment">-- =&gt; 15</span>
 </pre>
 
 
@@ -1835,6 +1870,22 @@ curried_product(<span class="number">5</span>)(<span class="number">4</span>) <s
 </pre>
 
 
+<h3>time (f, &hellip;)</h3>
+
+<p>Returns the execution time of <code>f (&hellip;)</code> in seconds and its results.</p>
+
+<pre>
+<span class="keyword">local</span> <span class="keyword">function</span> wait_count(n)
+    <span class="keyword">local</span> i = <span class="number">0</span>
+    <span class="keyword">while</span> i &lt; n <span class="keyword">do</span> i = i + <span class="number">1</span> <span class="keyword">end</span>
+    <span class="keyword">return</span> i
+<span class="keyword">end</span>
+
+<span class="keyword">local</span> time, i = _.time(wait_count, <span class="number">1e6</span>) <span class="comment">-- =&gt; 0.002 1000000
+</span><span class="keyword">local</span> time, i = _.time(wait_count, <span class="number">1e7</span>) <span class="comment">-- =&gt; 0.018 10000000</span>
+</pre>
+
+
 <p><strong><a href="#TOC">[⬆]</a></strong></p>
 
 <p><a name="_a_name__object__Object_functions__a_"></a></p>
@@ -2197,7 +2248,7 @@ _.isInteger(<span class="global">math</span>.pi) <span class="comment">-- =&gt;
 <p><em>Method chaining</em> (also known as <em>name parameter idiom</em>), is a technique for invoking consecutively method calls in object-oriented style.
 Each method returns an object, and methods calls are chained together.
 Moses offers chaining for your perusal. <br/>
-Let&rsquo;s use chaining to get the count of evey single word in some lyrics (case won&rsquo;t matter here).</p>
+Let&rsquo;s use chaining to get the count of every single word in some lyrics (case will not matter here).</p>
 
 <pre>
 <span class="keyword">local</span> lyrics = {
@@ -2291,7 +2342,7 @@ _.import(context, <span class="keyword">true</span>)
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2017-04-14 15:33:56 </i>
+<i style="float:right;">Last updated 2017-04-29 09:39:57 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>