Functional utilities
------------------------

.. module:: pysistence.func
   :synopsis: Common functional utilities

.. function:: flip(func)

   Return a function that is equivalent to *func* except that it has its first two
   arguments reversed.  For instance ``flip(my_function)(a, b)`` is equivalent to
   ``my_function(b, a)``.

.. function:: const(retval)

   Return a function that will always return *retval*.

.. function:: compose(func1, *funcs)

   Create a function that composes *func1* and *funcs* from left to right.
   For example::

       >>> from functools import partial
       >>> from pysistence.func import compose
       >>> rejoin = compose(str.split, partial(str.join, '-'))
       >>> rejoin("This is a string")
       'This-is-a-string'

.. function:: identity(*args)

   If a single argument is given, return it.  Otherwise, return a tuple of the
   arguments given.  Example::

       >>> from pysistence.func import identity
       >>> identity(1)
       1
       >>> identity(1, 2, 3)
       (1, 2, 3)
       >>> identity()
       ()

.. function:: trampoline(func, *args, **kwargs)

   Calls func with *args* and *kwargs*.  If the result is a callable, it will 
   call that function and repeat this process until a non-callable is returned.
   This can be useful to write recursive functions without blowing the stack.
   Example::

       >>> from functools import partial
       >>> from pysistence.func import trampoline
       >>> def count_to_a_million(i):
       ...     i += 1
       ...     if i < 1000000:
       ...             return partial(count_to_a_million, i)
       ...     else:
       ...             return i
       ... 
       >>> trampoline(count_to_a_million, 1)
       1000000