The sequence-utilities Module
=============================

.. current-library:: collection-extensions
.. current-module:: sequence-utilities

Overview
--------

The sequence-utilities module implements some useful methods on sequences.

- :func:`zip`
- :func:`zip-all`
- :func:`zip-with`


Reference
---------

**TODO**: These docs are just an auto-generated skeleton so
far. https://github.com/dylan-lang/collection-extensions/issues/2

.. function:: alist-copy

   :signature: alist-copy (alist #key key datum cons) => (new-alist)

   :parameter alist: An instance of :drm:`<sequence>`.
   :parameter #key key: An instance of :drm:`<object>`.
   :parameter #key datum: An instance of :drm:`<object>`.
   :parameter #key cons: An instance of :drm:`<object>`.
   :value new-alist: An instance of :drm:`<sequence>`.

.. function:: alist-delete

   :signature: alist-delete (elt alist #key key test) => (#rest results)

   :parameter elt: An instance of :drm:`<object>`.
   :parameter alist: An instance of :drm:`<sequence>`.
   :parameter #key key: An instance of :drm:`<object>`.
   :parameter #key test: An instance of :drm:`<object>`.
   :value #rest results: An instance of :drm:`<object>`.

.. function:: apair

   :signature: apair (key datum aseq #key cons add) => (new-aseq)

   :parameter key: An instance of :drm:`<object>`.
   :parameter datum: An instance of :drm:`<object>`.
   :parameter aseq: An instance of :drm:`<sequence>`.
   :parameter #key cons: An instance of :drm:`<object>`.
   :parameter #key add: An instance of :drm:`<object>`.
   :value new-aseq: An instance of :drm:`<sequence>`.

.. function:: assoc

   :signature: assoc (elt seq #key key test) => (#rest results)

   :parameter elt: An instance of :drm:`<object>`.
   :parameter seq: An instance of :drm:`<sequence>`.
   :parameter #key key: An instance of :drm:`<object>`.
   :parameter #key test: An instance of :drm:`<object>`.
   :value #rest results: An instance of :drm:`<object>`.

.. generic-function:: choose-map

   :signature: choose-map (pred func seq #rest seqs) => (#rest results)

   :parameter pred: An instance of :drm:`<object>`.
   :parameter func: An instance of :drm:`<object>`.
   :parameter seq: An instance of :drm:`<object>`.
   :parameter #rest seqs: An instance of :drm:`<object>`.
   :value #rest results: An instance of :drm:`<object>`.

.. method:: choose-map
   :specializer: <function>, <function>, <sequence>

.. method:: choose-map
   :specializer: <function>, <function>, <list>

.. generic-function:: concatenate-map

   :signature: concatenate-map (func seq #rest seqs) => (#rest results)

   :parameter func: An instance of :drm:`<object>`.
   :parameter seq: An instance of :drm:`<object>`.
   :parameter #rest seqs: An instance of :drm:`<object>`.
   :value #rest results: An instance of :drm:`<object>`.

.. method:: concatenate-map
   :specializer: <function>, <sequence>

.. method:: concatenate-map
   :specializer: <function>, <list>

.. generic-function:: drop
   :open:

   :signature: drop (collection k) => (#rest results)

   :parameter collection: An instance of :drm:`<object>`.
   :parameter k: An instance of :drm:`<integer>`.
   :value #rest results: An instance of :drm:`<object>`.

.. method:: drop
   :specializer: <sequence>, <integer>

.. generic-function:: find

   :signature: find (pred seq #key failure) => (#rest results)

   :parameter pred: An instance of :drm:`<function>`.
   :parameter seq: An instance of :drm:`<sequence>`.
   :parameter #key failure: An instance of :drm:`<object>`.
   :value #rest results: An instance of :drm:`<object>`.

.. generic-function:: find-tail

   :signature: find-tail (pred seq) => (#rest results)

   :parameter pred: An instance of :drm:`<object>`.
   :parameter seq: An instance of :drm:`<object>`.
   :value #rest results: An instance of :drm:`<object>`.

.. method:: find-tail
   :specializer: <function>, <sequence>

.. method:: find-tail
   :specializer: <function>, <pair>

.. method:: find-tail
   :specializer: <function>, <empty-list>

.. function:: foldl

   :signature: foldl (cons nil lst) => (#rest results)

   :parameter cons: An instance of :drm:`<function>`.
   :parameter nil: An instance of :drm:`<object>`.
   :parameter lst: An instance of :drm:`<list>`.
   :value #rest results: An instance of :drm:`<object>`.

.. function:: foldr

   :signature: foldr (cons nil lst) => (#rest results)

   :parameter cons: An instance of :drm:`<function>`.
   :parameter nil: An instance of :drm:`<object>`.
   :parameter lst: An instance of :drm:`<list>`.
   :value #rest results: An instance of :drm:`<object>`.

.. function:: heads

   :signature: heads (lists) => (new-list)

   :parameter lists: An instance of :drm:`<list>`.
   :value new-list: An instance of :drm:`<list>`.

.. generic-function:: index

   :signature: index (elt seq #key test failure) => (index)

   :parameter elt: An instance of :drm:`<object>`.
   :parameter seq: An instance of :drm:`<sequence>`.
   :parameter #key test: An instance of :drm:`<object>`.
   :parameter #key failure: An instance of :drm:`<object>`.
   :value index: An instance of :drm:`<object>`.

.. function:: last-pair

   :signature: last-pair (lst) => (last-pair)

   :parameter lst: An instance of :drm:`<pair>`.
   :value last-pair: An instance of :drm:`<pair>`.

.. function:: list*

   :signature: list* (#rest rest) => (new-list)

   :parameter #rest rest: An instance of :drm:`<object>`.
   :value new-list: An instance of :drm:`<list>`.

.. generic-function:: list?

   :signature: list? (arg) => (#rest results)

   :parameter arg: An instance of :drm:`<object>`.
   :value #rest results: An instance of :drm:`<object>`.

.. method:: list?
   :specializer: <list>

.. method:: list?
   :specializer: <object>

.. generic-function:: null?

   :signature: null? (arg) => (#rest results)

   :parameter arg: An instance of :drm:`<object>`.
   :value #rest results: An instance of :drm:`<object>`.

.. method:: null?
   :specializer: <empty-list>

.. method:: null?
   :specializer: <object>

.. function:: pair-do

   :signature: pair-do (func lst #rest lists) => (false)

   :parameter func: An instance of :drm:`<function>`.
   :parameter lst: An instance of :drm:`<list>`.
   :parameter #rest lists: An instance of :drm:`<object>`.
   :value false: An instance of :drm:`<boolean>`.

.. function:: pair-foldl

   :signature: pair-foldl (cons nil lst) => (#rest results)

   :parameter cons: An instance of :drm:`<function>`.
   :parameter nil: An instance of :drm:`<object>`.
   :parameter lst: An instance of :drm:`<list>`.
   :value #rest results: An instance of :drm:`<object>`.

.. function:: pair-foldr

   :signature: pair-foldr (cons nil lst) => (#rest results)

   :parameter cons: An instance of :drm:`<function>`.
   :parameter nil: An instance of :drm:`<object>`.
   :parameter lst: An instance of :drm:`<list>`.
   :value #rest results: An instance of :drm:`<object>`.

.. generic-function:: pair?

   :signature: pair? (arg) => (#rest results)

   :parameter arg: An instance of :drm:`<object>`.
   :value #rest results: An instance of :drm:`<object>`.

.. method:: pair?
   :specializer: <pair>

.. method:: pair?
   :specializer: <object>

.. function:: partition

   :signature: partition (pred seq) => (winners losers)

   :parameter pred: An instance of :drm:`<function>`.
   :parameter seq: An instance of :drm:`<sequence>`.
   :value winners: An instance of :drm:`<list>`.
   :value losers: An instance of :drm:`<list>`.

.. macro:: pop!

.. generic-function:: precedes?

   :signature: precedes? (elt-1 elt-2 seq #key test not-found) => (precedes?)

   :parameter elt-1: An instance of :drm:`<object>`.
   :parameter elt-2: An instance of :drm:`<object>`.
   :parameter seq: An instance of :drm:`<sequence>`.
   :parameter #key test: An instance of :drm:`<object>`.
   :parameter #key not-found: An instance of :drm:`<object>`.
   :value precedes?: An instance of :drm:`<boolean>`.

.. macro:: push!

.. function:: reduce-l

   :signature: reduce-l (cons nil lst) => (#rest results)

   :parameter cons: An instance of :drm:`<function>`.
   :parameter nil: An instance of :drm:`<object>`.
   :parameter lst: An instance of :drm:`<list>`.
   :value #rest results: An instance of :drm:`<object>`.

.. function:: reduce-r

   :signature: reduce-r (cons nil lst) => (#rest results)

   :parameter cons: An instance of :drm:`<function>`.
   :parameter nil: An instance of :drm:`<object>`.
   :parameter lst: An instance of :drm:`<list>`.
   :value #rest results: An instance of :drm:`<object>`.

.. generic-function:: reverse-append
   :open:

   :signature: reverse-append (reversed-head tail) => (new-sequence)

   :parameter reversed-head: An instance of :drm:`<sequence>`.
   :parameter tail: An instance of :drm:`<sequence>`.
   :value new-sequence: An instance of :drm:`<sequence>`.

.. method:: reverse-append
   :specializer: <sequence>, <sequence>

.. method:: reverse-append
   :specializer: <list>, <list>

.. generic-function:: satisfies

   :signature: satisfies (pred seq #key failure) => (index)

   :parameter pred: An instance of :drm:`<function>`.
   :parameter seq: An instance of :drm:`<sequence>`.
   :parameter #key failure: An instance of :drm:`<object>`.
   :value index: An instance of :drm:`<object>`.

.. function:: tabulate

   :signature: tabulate (length func #key type) => (#rest results)

   :parameter length: An instance of :drm:`<integer>`.
   :parameter func: An instance of :drm:`<function>`.
   :parameter #key type: An instance of :drm:`<object>`.
   :value #rest results: An instance of :drm:`<object>`.

.. function:: tails

   :signature: tails (lists) => (#rest results)

   :parameter lists: An instance of :drm:`<list>`.
   :value #rest results: An instance of :drm:`<object>`.

.. generic-function:: take
   :open:

   :signature: take (collection k) => (#rest results)

   :parameter collection: An instance of :drm:`<object>`.
   :parameter k: An instance of :drm:`<integer>`.
   :value #rest results: An instance of :drm:`<object>`.

.. method:: take
   :specializer: <sequence>, <integer>

.. function:: unfold

   :signature: unfold (pred f g seed) => (new-list)

   :parameter pred: An instance of :drm:`<function>`.
   :parameter f: An instance of :drm:`<function>`.
   :parameter g: An instance of :drm:`<function>`.
   :parameter seed: An instance of :drm:`<object>`.
   :value new-list: An instance of :drm:`<list>`.

.. function:: unfold/tail

   :signature: unfold/tail (pred f g e seed) => (new-list)

   :parameter pred: An instance of :drm:`<function>`.
   :parameter f: An instance of :drm:`<function>`.
   :parameter g: An instance of :drm:`<function>`.
   :parameter e: An instance of :drm:`<function>`.
   :parameter seed: An instance of :drm:`<object>`.
   :value new-list: An instance of :drm:`<list>`.

.. function:: xpair

   :signature: xpair (list elt) => (new-list)

   :parameter list: An instance of :drm:`<list>`.
   :parameter elt: An instance of :drm:`<object>`.
   :value new-list: An instance of :drm:`<list>`.

zip
^^^

.. function:: zip

   The `zip` function combines multiple iterables element-wise into
   tuples, stopping at the shortest iterable.

   :signature:

      zip (*sequence1* *sequence2* #key *key1* *key2*) => (*zipped*)

   :parameter sequence1:

      An instance of :drm:`<sequence>`.

   :parameter sequence2:

      An instance of :drm:`<sequence>`.

   :parameter #key key1:

      An instance of :drm:`<function>`. Default value:
      :drm:`identity`.

   :parameter #key key2:

      An instance of :drm:`<function>`. Default value:
      :drm:`identity`.

   :value zipped:

      An instance of :drm:`<sequence>`.

   :description:

   The `zip` function is often classified as a *high-order function* and
   a *sequence transformation function*.

   The function operates on two sequences (like :drm:`range`,
   `array`, :drm:`list`, `deque` or `string`) and
   transforms them in a :drm:`<sequence>` of pairs, each element from
   one of the sequences.

   If *key1* or *key2* are not provided, they default to the function
   :drm:`identity` returning the object. If provided, this function
   transforms the element before collecting it.

   If the sequences provided have different lengths, func:`zip`
   automatically truncates the output to the length of the shorter
   sequence.


   :example:

   .. code-block:: dylan

     let a = #(1, 2);
     let b = #('a', 'b');

     let zipped = zip(a, b);
     format-out("%=", zipped); // Output: #(#(1, 'a'), #(2, 'b'))

   :example:

   .. code-block:: dylan

     let a = #('a', 'b');
     let b = #(3, 4);

     let zipped = zip(a, b, key2: odd?);
     format-out("%=", zipped); // Output: #(#('a', #t), ('b', #f))

zip-with
^^^^^^^^

.. function:: zip-with


   :signature:

      zip-with (function collection #rest more-collections) ⇒ new-collection

   :parameter function:

      An instance of :drm:`<function>`.

   :parameter collection:

      An instance of :drm:`<collection>`.

   :parameter more-collections:

      An instance of :drm:`<collection>`.

   :value new-collection:

      An instance of :drm:`<collection>`.

   :example:

   .. code-block:: dylan

     let a = #(100, 200, 300);
     let b = #(1, 2, 3);

     let zipped = zip-with(\+, a, b);
     format-out("%=", zipped); // Output: #(101, 202, 303)

   :seealso:

      :drm:`map`

zip-all
^^^^^^^

.. function:: zip-all

   A :func:`zip` function that can take any number of iterables as
   parameters.
   
   :signature:

      zip-all (sequences) => (zipped)

   :parameter sequences:

      An instance of :drm:`<sequence>`.

   :value zipped:

      An instance of :drm:`<sequence>`.

   :example:

   .. code-block:: dylan

     let a = #(1, 2, 3);
     let b = #('a', 'b', 'c');
     let c = #(#t, #f, #t);

     let zipped = zip-all(a, b, c);

     format-out("%=", zipped); // Output: #(#(1, 'a', #t), #(2, 'b', #f), #(3, 'c', #t))