1 files changed, 323 insertions, 0 deletions
diff --git a/Data/DefaultContent/Libraries/luafun/doc/reducing.rst b/Data/DefaultContent/Libraries/luafun/doc/reducing.rst
new file mode 100644
index 0000000..f7b89da
--- /dev/null
+++ b/Data/DefaultContent/Libraries/luafun/doc/reducing.rst
@@ -0,0 +1,323 @@
+Reducing
+========
+
+.. module:: fun
+
+The section contains functions to analyze iteration values and recombine
+through use of a given combining operation the results of recursively processing
+its constituent parts, building up a return value
+
+.. contents::
+
+.. note:: An attempt to use infinity iterators with the most function from
+          the module causes an infinite loop.
+
+Folds
+-----
+
+.. function:: foldl(accfun, initval, gen, param, state)
+              iterator:reduce(accfun, initval)
+
+   :param accfun: an accumulating function
+   :type  param: (function(prevval, ...) -> val)
+   :param initval: an initial value that passed to **accfun** on the first
+          iteration
+
+   The function reduces the iterator from left to right using the binary
+   operator **accfun** and the initial value **initval**.
+   Equivalent to::
+
+        local val = initval
+        for _k, ... in gen, param, state do
+            val = accfun(val, ...)
+        end
+        return val
+
+   Examples:
+
+   .. code-block:: lua
+
+    > print(foldl(function(acc, x) return acc + x end, 0, range(5)))
+    15
+
+    > print(foldl(operator.add, 0, range(5)))
+    15
+
+    > print(foldl(function(acc, x, y) return acc + x * y; end, 0,
+        zip(range(1, 5), {4, 3, 2, 1})))
+    20
+
+.. function:: reduce(accfun, initval, gen, param, state)
+              iterator:reduce(accfun, initval)
+
+   An alias to :func:`foldl`.
+
+.. function:: length(gen, param, state)
+              iterator:length()
+
+   :returns: a number of elements in ``gen, param, state`` iterator.
+
+   Return a number of elements in ``gen, param, state`` iterator.
+   This function is equivalent to ``#obj`` for basic array and string iterators.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > print(length({"a", "b", "c", "d", "e"}))
+    5
+
+    > print(length({}))
+    0
+
+    > print(length(range(0)))
+    0
+
+   .. warning:: An attempt to call this function on an infinite iterator will
+                result an infinite loop.
+
+   .. note:: This function has ``O(n)`` complexity for all iterators except
+             basic array and string iterators.
+
+.. function:: totable(gen, param, state)
+
+   :returns: a new table (array) from iterated values.
+
+   The function reduces the iterator from left to right using ``table.insert``.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > local tab = totable("abcdef")
+    > print(type(tab), #tab)
+    table 6
+    > each(print, tab)
+    a
+    b
+    c
+    d
+    e
+    f
+
+.. function:: tomap(gen, param, state)
+
+   :returns: a new table (map) from iterated values.
+
+   The function reduces the iterator from left to right using
+   ``tab[val1] = val2`` expression.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > local tab = tomap(zip(range(1, 7), 'abcdef'))
+    > print(type(tab), #tab)
+    table   6
+    > each(print, iter(tab))
+    a
+    b
+    c
+    d
+    e
+    f
+
+Predicates
+----------
+
+.. function:: is_prefix_of(iterator1, iterator2)
+              iterator1:is_prefix_of(iterator2)
+
+   The function takes two iterators and returns ``true`` if the first iterator
+   is a prefix of the second. 
+
+   Examples:
+
+   .. code-block:: lua
+
+    > print(is_prefix_of({"a"}, {"a", "b", "c"}))
+    true
+
+    > print(is_prefix_of(range(6), range(5)))
+    false
+
+.. function:: is_null(gen, param, state)
+              iterator:is_null()
+
+   :returns: true when `gen, param, state`` iterator is empty or finished.
+   :returns: false otherwise.
+
+   Example::
+
+    > print(is_null({"a", "b", "c", "d", "e"}))
+    false
+
+    > print(is_null({}))
+    true
+
+    > print(is_null(range(0)))
+    true
+
+.. function:: all(predicate, gen, param, state)
+              iterator:all(predicate)
+
+   :param predicate: a predicate
+
+   Returns true if all return values of iterator satisfy the **predicate**.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > print(all(function(x) return x end, {true, true, true, true}))
+    true
+
+    > print(all(function(x) return x end, {true, true, true, false}))
+    false
+
+.. function:: every(predicate, gen, param, state)
+
+   An alias for :func:`all`.
+
+.. function:: any(predicate, gen, param, state)
+              iterator:any(predicate)
+
+   :param predicate: a predicate
+
+   Returns ``true`` if at least one return values of iterator satisfy the
+   **predicate**. The iteration stops on the first such value. Therefore,
+   infinity iterators that have at least one satisfying value might work.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > print(any(function(x) return x end, {false, false, false, false}))
+    false
+
+    > print(any(function(x) return x end, {false, false, false, true}))
+    true
+
+.. function:: some(predicate, gen, param, state)
+
+   An alias for :func:`any`.
+
+Special folds
+-------------
+
+.. function:: sum(gen, param, state)
+              iterator:sum()
+
+   Sum up all iteration values. An optimized alias for::
+
+       foldl(operator.add, 0, gen, param, state)
+
+   For an empty iterator ``0`` is returned.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > print(sum(range(5)))
+    15
+
+.. function:: product(gen, param, state)
+              iterator:product()
+
+   Multiply all iteration values. An optimized alias for::
+
+       foldl(operator.mul, 1, gen, param, state)
+
+   For an empty iterator ``1`` is returned.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > print(product(range(1, 5)))
+    120
+
+.. function:: min(gen, param, state)
+              iterator:min()
+
+   Return a minimum value from the iterator using :func:`operator.min` or ``<``
+   for numbers and other types respectivly. The iterator must be
+   non-null, otherwise an error is raised.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > print(min(range(1, 10, 1)))
+    1
+
+    > print(min({"f", "d", "c", "d", "e"}))
+    c
+
+    > print(min({}))
+    error: min: iterator is empty
+
+.. function:: minimum(gen, param, state)
+
+   An alias for :func:`min`.
+
+.. function:: min_by(cmp, gen, param, state)
+              iterator:min_by(cmp)
+
+   Return a minimum value from the iterator using the **cmp** as a ``<``
+   operator. The iterator must be non-null, otherwise an error is raised.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > function min_cmp(a, b) if -a < -b then return a else return b end end
+    > print(min_by(min_cmp, range(1, 10, 1)))
+    9
+
+.. function:: minimum_by(cmp, gen, param, state)
+
+   An alias for :func:`min_by`.
+
+.. function:: max(gen, param, state)
+              iterator:max()
+
+   Return a maximum value from the iterator using :func:`operator.max` or ``>``
+   for numbers and other types respectivly.
+
+   The iterator must be non-null, otherwise an error is raised.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > print(max(range(1, 10, 1)))
+    9
+
+    > print(max({"f", "d", "c", "d", "e"}))
+    f
+
+    > print(max({}))
+    error: max: iterator is empty
+
+.. function:: maximum(gen, param, state)
+
+   An alias for :func:`max`.
+
+.. function:: max_by(cmp, gen, param, state)
+              iterator:max_by(cmp)
+
+   Return a maximum value from the iterator using the **cmp** as a `>`
+   operator. The iterator must be non-null, otherwise an error is raised.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > function max_cmp(a, b) if -a > -b then return a else return b end end
+    > print(max_by(max_cmp, range(1, 10, 1)))
+    1
+
+.. function:: maximum_by(cmp, gen, param, state)
+
+   An alias for :func:`max_by`.