1 files changed, 246 insertions, 0 deletions
diff --git a/Data/BuiltIn/Libraries/luafun/doc/slicing.rst b/Data/BuiltIn/Libraries/luafun/doc/slicing.rst
new file mode 100644
index 0000000..1af642f
--- /dev/null
+++ b/Data/BuiltIn/Libraries/luafun/doc/slicing.rst
@@ -0,0 +1,246 @@
+Slicing
+=======
+
+.. module:: fun
+
+This section contains functions to make subsequences from iterators.
+
+Basic
+-----
+
+.. function:: nth(n, gen, param, state)
+              iterator:nth(n)
+
+   :param uint n: a sequential number (indexed starting from ``1``,
+                  like Lua tables)
+   :returns: **n**-th element of ``gen, param, state`` iterator
+
+   This function returns the **n**-th element of ``gen, param, state``
+   iterator. If the iterator does not have **n** items then ``nil`` is returned.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > print(nth(2, range(5)))
+    2
+
+    > print(nth(10, range(5)))
+    nil
+
+    > print(nth(2, {"a", "b", "c", "d", "e"}))
+    b
+
+    > print(nth(2, enumerate({"a", "b", "c", "d", "e"})))
+    2 b
+
+   This function is optimized for basic array and string iterators and has
+   ``O(1)`` complexity for these cases.
+
+.. function:: head(gen, param, state)
+              iterator:head()
+
+   :returns: a first element of ``gen, param, state`` iterator
+
+   Extract the first element of ``gen, param, state`` iterator.
+   If the iterator is empty then an error is raised.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > print(head({"a", "b", "c", "d", "e"}))
+    a
+    > print(head({}))
+    error: head: iterator is empty
+    > print(head(range(0)))
+    error: head: iterator is empty
+    > print(head(enumerate({"a", "b"})))
+    1 a
+
+.. function:: car(gen, param, state)
+
+   An alias for :func:`head`.
+
+.. function:: tail(gen, param, state)
+              iterator:tail()
+
+   :returns: ``gen, param, state`` iterator without a first element
+
+   Return a copy of ``gen, param, state`` iterator without its first element.
+   If the iterator is empty then an empty iterator is returned.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > each(print, tail({"a", "b", "c", "d", "e"}))
+    b
+    c
+    d
+    e
+    > each(print, tail({}))
+    > each(print, tail(range(0)))
+    > each(print, tail(enumerate({"a", "b", "c"})))
+    2 b
+    3 c
+
+.. function:: cdr(gen, param, state)
+
+   An alias for :func:`tail`.
+
+Subsequences
+------------
+
+.. function:: take_n(n, gen, param, state)
+              iterator:take_n(n)
+
+   :param n: a number of elements to take
+   :type  n: uint
+   :returns: an iterator on the subsequence of first **n** elements
+
+   Examples:
+
+   .. code-block:: lua
+
+    > each(print, take_n(5, range(10)))
+    1
+    2
+    3
+    4
+    5
+
+    > each(print, take_n(5, enumerate(duplicate('x'))))
+    1 x
+    2 x
+    3 x
+    4 x
+    5 x
+
+.. function:: take_while(predicate, gen, param, state)
+              iterator:take_while(predicate)
+
+   :type predicate: function(...) -> bool
+   :returns: an iterator on the longest prefix of ``gen, param, state``
+             elements that satisfy **predicate**.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > each(print, take_while(function(x) return x < 5 end, range(10)))
+    1
+    2
+    3
+    4
+
+    > each(print, take_while(function(i, a) return i ~=a end,
+        enumerate({5, 3, 4, 4, 2})))
+    1       5
+    2       3
+    3       4
+
+   .. seealso:: :func:`filter`
+
+.. function:: take(n_or_predicate, gen, param, state)
+              iterator:take(n_or_predicate)
+
+   An alias for :func:`take_n` and :func:`take_while` that autodetects
+   required function based on **n_or_predicate** type.
+
+.. function:: drop_n(n, gen, param, state)
+              iterator:drop_n(n)
+
+   :param n: the number of elements to drop
+   :type  n: uint
+   :returns: ``gen, param, state`` iterator after skipping first **n**
+             elements
+
+   Examples:
+
+   .. code-block:: lua
+
+    > each(print, drop_n(2, range(5)))
+    3
+    4
+    5
+
+    > each(print, drop_n(2, enumerate({'a', 'b', 'c', 'd', 'e'})))
+    3       c
+    4       d
+    5       e
+
+.. function:: drop_while(predicate, gen, param, state)
+              iterator:drop_while(predicate)
+
+   :type predicate: function(...) -> bool
+   :returns: ``gen, param, state`` after skipping the longest prefix
+             of  elements that satisfy **predicate**.
+
+   Examples:
+
+   .. code-block:: lua
+
+    > each(print, drop_while(function(x) return x < 5 end, range(10)))
+    5
+    6
+    7
+    8
+    9
+    10
+
+   .. seealso:: :func:`filter`
+
+.. function:: drop(n_or_predicate, gen, param, state)
+              iterator:drop(n_or_predicate)
+
+   An alias for :func:`drop_n` and :func:`drop_while` that autodetects
+   required function based on **n_or_predicate** type.
+
+
+.. function:: span(n_or_predicate, gen, param, state)
+              iterator:span(n_or_predicate)
+
+   :type n_or_predicate: function(...) -> bool or uint
+   :returns: iterator, iterator
+
+   Return an iterator pair where the first operates on the longest prefix
+   (possibly empty) of ``gen, param, state`` iterator of elements that
+   satisfy **predicate** and second operates the remainder of
+   ``gen, param, state`` iterator. 
+   Equivalent to:
+
+   .. code-block:: lua
+
+       return take(n_or_predicate, gen, param, state),
+              drop(n_or_predicate, gen, param, state);
+
+   Examples:
+
+   .. code-block:: lua
+
+    > each(print, zip(span(function(x) return x < 5 end, range(10))))
+    1       5
+    2       6
+    3       7
+    4       8
+
+    > each(print, zip(span(5, range(10))))
+    1       6
+    2       7
+    3       8
+    4       9
+    5       10
+
+   .. note:: ``gen, param, state`` must be pure functional to work properly
+             with the function.
+
+   .. seealso:: :func:`partition`
+
+.. function:: split(n_or_predicate, gen, param, state)
+
+    An alias for :func:`span`.
+
+.. function:: split_at(n, gen, param, state)
+
+    An alias for :func:`span`.