/******************************************************************************
 * Licensed under Apache License Version 2.0 - see LICENSE
 *****************************************************************************/

/******************************************************************************
 * Multi-purpose docstrings
 *
 * __reduce__
 * __setstate__
 * __length_hint__
 *****************************************************************************/

PyDoc_STRVAR(PYIU_reduce_doc,
    "__reduce__(/)\n"
    "--\n\n"
    "Return a `tuple` containing the state information for pickling.\n"
);

PyDoc_STRVAR(PYIU_setstate_doc,
    "__setstate__(state, /)\n"
    "--\n\n"
    "Set state for unpickling. "
    "The `state` argument must be `tuple`-like.\n"
);

#if PY_MAJOR_VERSION > 3 || (PY_MAJOR_VERSION == 3 && PY_MINOR_VERSION >= 4)
PyDoc_STRVAR(PYIU_lenhint_doc,
    "__length_hint__(/)\n"
    "--\n\n"
    "Return an *estimate* for the length of the iterator or zero.\n"
);
#endif

/* Names for pre-defined instances. */
PyDoc_STRVAR(PyIU_returnTrue_name, "return_True");
PyDoc_STRVAR(PyIU_returnFalse_name, "return_False");
PyDoc_STRVAR(PyIU_returnNone_name, "return_None");
PyDoc_STRVAR(PyIU_ReduceFirst_name, "first");
PyDoc_STRVAR(PyIU_ReduceSecond_name, "second");
PyDoc_STRVAR(PyIU_ReduceThird_name, "third");
PyDoc_STRVAR(PyIU_ReduceLast_name, "last");
PyDoc_STRVAR(PyIU_Placeholder_name, "Placeholder");

/* Name and docstring of C-module. */
PyDoc_STRVAR(PyIU_module_name, "_iteration_utilities");
PyDoc_STRVAR(PyIU_module_doc,
             "This is the C extension module used by iteration_utilities.");

/* Properties */
PyDoc_STRVAR(itemidxkey_prop_item_doc,
    "(any type) The `item` to sort.");
PyDoc_STRVAR(itemidxkey_prop_idx_doc,
    "(:py:class:`int`) The original position of the `item`.");
PyDoc_STRVAR(itemidxkey_prop_key_doc,
    "(any type) The result of a key function applied to the `item`.");

PyDoc_STRVAR(seen_prop_seenset_doc,
    "(:py:class:`set`) The (hashable) seen values (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(seen_prop_seenlist_doc,
    "(:py:class:`list` or None) The (unhashable) seen values (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(accumulate_prop_func_doc,
    "(callable or None) The function used for accumulation (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(accumulate_prop_current_doc,
    "(any type) The current accumulated total (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(applyfunc_prop_func_doc,
    "(callable) The function used (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(applyfunc_prop_current_doc,
    "(any type) The current value for the function (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(chained_prop_funcs_doc,
    "(:py:class:`tuple`) The functions to be used (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(chained_prop_all_doc,
    "(:py:class:`bool`) Apply functions on each other (``False``) or "
     "seperate (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(clamp_prop_low_doc,
    "(any type) The lower bound for `clamp` (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(clamp_prop_high_doc,
    "(any type) The upper bound for `clamp` (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(clamp_prop_inclusive_doc,
    "(:py:class:`bool`) Are the bounds inclusive (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(clamp_prop_remove_doc,
    "(:py:class:`bool`) Remove the outliers or clamp them to nearest bound "
     "(readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(complement_prop_func_doc,
    "(callable) The function that is complemented (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(constant_prop_item_doc,
    "(any type) The value that is returned each time the instance is called "
     "(readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(deepflatten_prop_types_doc,
    "(:py:class:`type` or :py:class:`tuple` thereof) The types to flatten or "
     "None if `deepflatten` attempts to flatten every type (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(deepflatten_prop_ignore_doc,
    "(:py:class:`type` or :py:class:`tuple` thereof) The types that are not "
     "flattened (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(deepflatten_prop_depth_doc,
    "(:py:class:`int`) Up to this depth the iterable is flattened (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(deepflatten_prop_currentdepth_doc,
    "(:py:class:`int`) The current depth inside the iterable (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(duplicates_prop_seen_doc,
    "(:py:class:`~iteration_utilities.Seen`) Already seen values (readonly).");
PyDoc_STRVAR(duplicates_prop_key_doc,
    "(callable or `None`) The key function (readonly).");

PyDoc_STRVAR(flip_prop_func_doc,
    "(callable) The function with flipped arguments (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(grouper_prop_fillvalue_doc,
    "(any type) The fillvalue if the last group does not contain enough "
    "items (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(grouper_prop_times_doc,
    "(:py:class:`int`) The size of each group (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(grouper_prop_truncate_doc,
    "(:py:class:`int`) ``True`` if an incomplete last group is discarded "
     "(readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(intersperse_prop_fillvalue_doc,
    "(any type) The interspersed fillvalue (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(iterexcept_prop_func_doc,
    "(any type) The function that is called by `iter_except` (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(iterexcept_prop_exception_doc,
    "(any type) The exception that ends `iter_except` (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(iterexcept_prop_first_doc,
    "(any type) The function that is called once (as setup) by `iter_except` "
     "(readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(merge_prop_key_doc,
    "(callable or None) The key function used by merge (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(merge_prop_reverse_doc,
    "(:py:class:`bool`) Indicates if merged by ``>`` instead of ``<`` "
     "(readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(nth_prop_n_doc,
    "(:py:class:`int`) The index to get (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(packed_prop_func_doc,
    "(callable) The function with packed arguments (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(partial_prop_func_doc,
    "(callable) Function object to use in future partial calls (readonly).");
PyDoc_STRVAR(partial_prop_args_doc,
    "(:py:class:`tuple`) arguments for future partial calls (readonly).");
PyDoc_STRVAR(partial_prop_keywords_doc,
    "(:py:class:`dict`) keyword arguments for future partial calls (readonly).");
PyDoc_STRVAR(partial_prop_nplaceholders_doc,
    "(:py:class:`int`) Number of placeholders in the args (readonly).");
PyDoc_STRVAR(partial_prop___dict___doc,
    "");

PyDoc_STRVAR(replicate_prop_times_doc,
    "(:py:class:`int`) The number of times each item is replicated (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(replicate_prop_timescurrent_doc,
    "(:py:class:`int`) A counter indicating how often the current item was "
     "already replicated (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(replicate_prop_current_doc,
    "(any type) The item that is currently replicated (readonly).\n"
    "\n"
    "Only avaiable if an item has been replicated.\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(sideeffects_prop_func_doc,
    "(callable) The function that is called by `sideeffects` (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(sideeffects_prop_times_doc,
    "(:py:class:`int`) A counter indicating after how many items the `func` "
     "is called (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(sideeffects_prop_count_doc,
    "(:py:class:`int`) The current count for the next `func` call (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(split_prop_key_doc,
    "(callable or any type) The function or value by which to split (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(split_prop_maxsplit_doc,
    "(:py:class:`int`) The number of maximum splits (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(split_prop_keep_doc,
    "(:py:class:`bool`) Keep the delimiter (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(split_prop_keepbefore_doc,
    "(:py:class:`bool`) Keep the delimiter as last item of the last group "
     "(readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(split_prop_keepafter_doc,
    "(:py:class:`bool`) Keep the delimiter as first item of the next group "
     "(readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(split_prop_eq_doc,
    "(:py:class:`bool`) Instead of calling :py:attr:`key` compare the items "
     "with it (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(starfilter_prop_pred_doc,
    "(callable) The function by which to filter (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(successive_prop_times_doc,
    "(:py:class:`int`) The number of successive items (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(tabulate_prop_func_doc,
    "(callable) The function to tabulate (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(tabulate_prop_current_doc,
    "(any type) The current value to tabulate (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");

PyDoc_STRVAR(uniqueever_prop_seen_doc,
    "(:py:class:`~iteration_utilities.Seen`) Already seen values (readonly).");
PyDoc_STRVAR(uniqueever_prop_key_doc,
    "(callable or None) The key function (readonly).");

PyDoc_STRVAR(uniquejust_prop_key_doc,
    "(callable or None) The key function (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");
PyDoc_STRVAR(uniquejust_prop_lastseen_doc,
    "(any type) The last seen item (readonly).\n"
    "\n"
    ".. versionadded:: 0.6");


PyDoc_STRVAR(PyIU_TupleToList_and_InsertItemAtIndex_doc,
    "_parse_args(tup, item, pos, /)\n"
    "--\n\n"
    "Converts the `tup` to a new `tuple` and inserts `item` at `pos`.\n"
    "\n"
    ".. warning::\n"
    "   This function is especially made for internal use, **DO NOT USE THIS \n"
    "   FUNCTION** anywhere else.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "tup : tuple\n"
    "    The tuple to convert.\n"
    "    \n"
    "    .. warning::\n"
    "       This function will encounter a segmentation fault if `tup` is not\n"
    "       a tuple.\n"
    "\n"
    "item : any type\n"
    "    The item to insert.\n"
    "\n"
    "pos : int\n"
    "    The position where to insert the `item`. \n"
    "    \n"
    "    .. warning::\n"
    "       No bounds checking - If `pos` is not carefully chosen the function \n"
    "       will segfault!\n"
    "\n"
    "Returns\n"
    "-------\n"
    "lst : tuple\n"
    "    The converted `tup` with `item` inserted.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "This is equivelant to:\n"
    "\n"
    ".. code::\n"
    "\n"
    "    def _parse_args(args, item, pos):\n"
    "        return tuple(args[:pos]) + (item, ) + tuple(args[pos:])\n"
);

PyDoc_STRVAR(PyIU_RemoveFromDictWhereValueIs_doc,
    "_parse_kwargs(dct, item, /)\n"
    "--\n\n"
    "Removes every key from the `dct` where the ``dct[key] is item``.\n"
    "\n"
    ".. warning::\n"
    "   This function is especially made for internal use, **DO NOT USE THIS \n"
    "   FUNCTION** anywhere else.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "dct : dict\n"
    "    The dictionary from which to remove the keys.\n"
    "\n"
    "item : any type\n"
    "    The item to check for.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "nothing. This function works in-place.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "This is equivelant to:\n"
    "\n"
    ".. code::\n"
    "\n"
    "    def _parse_kwargs(dct, item):\n"
    "        keys_to_remove = [key for key in dct if dct[key] is item]\n"
    "        for key in keys_to_remove:\n"
    "            del dct[key]\n"
);

PyDoc_STRVAR(PyIU_IsNone_doc,
    "is_None(value, /)\n"
    "--\n\n"
    "Returns ``True`` if `value` is ``None``, otherwise ``False``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "value : any type \n"
    "    The value to test for ``None``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "is_none : :py:class:`bool`\n"
    "    ``True`` if `value` is ``None`` otherwise it returns ``False``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function is equivalent to ``lambda x: x is None`` but significantly\n"
    "faster::\n"
    "\n"
    "    >>> from iteration_utilities import is_None\n"
    "    >>> is_None(None)\n"
    "    True\n"
    "    >>> is_None(False)\n"
    "    False\n"
    "\n"
    "This can be used for example to remove all ``None`` from an iterable::\n"
    "\n"
    "    >>> import sys\n"
    "    >>> import itertools\n"
    "    >>> filterfalse = itertools.ifilterfalse if sys.version_info.major == 2 else itertools.filterfalse\n"
    "    >>> list(filterfalse(is_None, [1, None, 3, 4, 5, None, 7]))\n"
    "    [1, 3, 4, 5, 7]\n"
);

PyDoc_STRVAR(PyIU_IsNotNone_doc,
    "is_not_None(value, /)\n"
    "--\n\n"
    "Returns ``False`` if `value` is ``None``, otherwise ``True``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "value : any type \n"
    "    The value to test for ``None``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "is_not_none : :py:class:`bool`\n"
    "    ``False`` if `value` is ``None`` otherwise it returns ``True``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function is equivalent to ``lambda x: x is not None`` but significantly\n"
    "faster::\n"
    "\n"
    "    >>> from iteration_utilities import is_not_None\n"
    "    >>> is_not_None(None)\n"
    "    False\n"
    "    >>> is_not_None(False)\n"
    "    True\n"
);

PyDoc_STRVAR(PyIU_IsEven_doc,
    "is_even(value, /)\n"
    "--\n\n"
    "Returns ``True`` if `value` is even, otherwise ``False``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "value : any type \n"
    "    The value to test if even.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "is_even : :py:class:`bool`\n"
    "    ``True`` if `value` is even otherwise it returns ``False``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function is equivalent to ``lambda x: not x % 2`` but significantly\n"
    "faster::\n"
    "\n"
    "    >>> from iteration_utilities import is_even\n"
    "    >>> is_even(0)\n"
    "    True\n"
    "    >>> is_even(1)\n"
    "    False\n"
    "    >>> is_even(2)\n"
    "    True\n"
);

PyDoc_STRVAR(PyIU_IsOdd_doc,
    "is_odd(value, /)\n"
    "--\n\n"
    "Returns ``True`` if `value` is odd, otherwise ``False``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "value : any type \n"
    "    The value to test if odd.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "is_odd : :py:class:`bool`\n"
    "    ``True`` if `value` is odd otherwise it returns ``False``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function is equivalent to ``lambda x: bool(x % 2)`` but significantly\n"
    "faster::\n"
    "\n"
    "    >>> from iteration_utilities import is_odd\n"
    "    >>> is_odd(0)\n"
    "    False\n"
    "    >>> is_odd(1)\n"
    "    True\n"
    "    >>> is_odd(2)\n"
    "    False\n"
);

PyDoc_STRVAR(PyIU_IsIterable_doc,
    "is_iterable(value, /)\n"
    "--\n\n"
    "Returns ``True`` if `value` is iterable, otherwise ``False``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "value : any type \n"
    "    The value to test if iterable.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "is_iterable : :py:class:`bool`\n"
    "    ``True`` if `value` is iterable otherwise it returns ``False``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "A few simple examples::\n"
    "\n"
    "    >>> from iteration_utilities import is_iterable\n"
    "    >>> is_iterable(0)\n"
    "    False\n"
    "    >>> is_iterable('abc')\n"
    "    True\n"
    "    >>> is_iterable([1,2,3])\n"
    "    True\n"
);

PyDoc_STRVAR(itemidxkey_doc,
    "ItemIdxKey(item, idx, /, key)\n"
    "--\n\n"
    "Helper class that makes it easier and faster to compare two values for\n"
    "*stable* sorting algorithms supporting key functions.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "item : any type\n"
    "    The original `item`.\n"
    "\n"
    "idx : :py:class:`int`\n"
    "    The position (index) of the `item`.\n"
    "\n"
    "key : any type, optional\n"
    "    If given (even as ``None``) this should be the `item` processed by the \n"
    "    `key` function. If it is set then comparisons will compare the `key` \n"
    "    instead of the `item`.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "Comparisons involving :py:class:`~iteration_utilities.ItemIdxKey` have some \n"
    "limitations:\n"
    "\n"
    "- Both have to be :py:class:`~iteration_utilities.ItemIdxKey` instances.\n"
    "- If the first operand has no :py:attr:`.key` then the :py:attr:`.item` are \n"
    "  compared.\n"
    "- The :py:attr:`.idx` must be different.\n"
    "- only :py:meth:`< <.__lt__>` and :py:meth:`> <.__gt__>` are supported!\n"
    "\n"
    "The implementation is rougly like:\n"
    "\n"
    ".. code::\n"
    "\n"
    "   _notgiven = object()\n"
    "   \n"
    "   class ItemIdxKey(object):\n"
    "       def __init__(self, item, idx, key=_notgiven):\n"
    "           self.item = item\n"
    "           self.idx = idx\n"
    "           self.key = key\n"
    "   \n"
    "       def __lt__(self, other):\n"
    "           if type(other) != ItemIdxKey:\n"
    "               raise TypeError()\n"
    "           if self.key is _notgiven:\n"
    "               item1, item2 = self.item, other.item\n"
    "           else:\n"
    "               item1, item2 = self.key, other.key\n"
    "           if self.idx < other.idx:\n"
    "               return item1 <= item2\n"
    "           else:\n"
    "               return item1 < item2\n"
    "   \n"
    "       def __gt__(self, other):\n"
    "           if type(other) != ItemIdxKey:\n"
    "               raise TypeError()\n"
    "           if self.key is _notgiven:\n"
    "               item1, item2 = self.item, other.item\n"
    "           else:\n"
    "               item1, item2 = self.key, other.key\n"
    "           if self.idx < other.idx:\n"
    "               return item1 >= item2\n"
    "           else:\n"
    "               return item1 > item2\n"
    "\n"
    ".. note::\n"
    "   The actual C makes the initialization and comparisons several times faster\n"
    "   than the above illustrated Python class! But it's only slightly faster\n"
    "   than comparing :py:class:`tuple` or :py:class:`list`. If you do not plan \n"
    "   to support `reverse` or `key` then there is no need to use this class!\n"
    "\n"
    ".. warning::\n"
    "   You should **never** insert a :py:class:`~iteration_utilities.ItemIdxKey` \n"
    "   instance as :py:attr:`.item` or :py:attr:`.key` in another\n"
    "   :py:class:`~iteration_utilities.ItemIdxKey` instance. This would yield \n"
    "   wrong results and breaks your computer! (the latter might not be true.)\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Stability is one of the distinct features of sorting algorithms. This class\n"
    "aids in supporting those algorithms which allow `reverse` and `key`.\n"
    "This means that comparisons require absolute lesser (or greater if `reverse`)\n"
    "if the :py:attr:`.idx` is bigger but only require lesser or equal (or greater or equal)\n"
    "if the :py:attr:`.idx` is smaller. This class implements exactly these conditions::\n"
    "\n"
    "    >>> # Use < for normal sorting.\n"
    "    >>> ItemIdxKey(10, 2) < ItemIdxKey(10, 3)\n"
    "    True\n"
    "    >>> # and > for reverse sorting.\n"
    "    >>> ItemIdxKey(10, 2) > ItemIdxKey(10, 3)\n"
    "    True\n"
    "\n"
    "The result may seem surprising but if the :py:attr:`.item` (or :py:attr:`.key`) is equal then\n"
    "in either normal or `reverse` sorting the one with the smaller :py:attr:`.idx` should\n"
    "come first! If the :py:attr:`.item` (or :py:attr:`.key`) differ they take precedence.\n"
    "\n"
    "    >>> ItemIdxKey(10, 2) < ItemIdxKey(11, 3)\n"
    "    True\n"
    "    >>> ItemIdxKey(10, 2) > ItemIdxKey(11, 3)\n"
    "    False\n"
    "\n"
    "But it compares the :py:attr:`.key` instead of the :py:attr:`.item` if it's given::\n"
    "\n"
    "    >>> ItemIdxKey(0, 2, 20) < ItemIdxKey(10, 3, 19)\n"
    "    False\n"
    "    >>> ItemIdxKey(0, 2, 20) > ItemIdxKey(10, 3, 19)\n"
    "    True\n"
    "\n"
    "This allows to sort based on :py:attr:`.item` or :py:attr:`.key` but always \n"
    "to access the :py:attr:`.item` for the value that should be sorted.\n"
);

PyDoc_STRVAR(PyIU_MathSquare_doc,
    "square(value, /)\n"
    "--\n\n"
    "Returns the squared `value`.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "value : any type\n"
    "    The value to be squared. The type of the `value` must support ``pow``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "square : any type\n"
    "    Returns ``value**2``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "It is not possible to apply :py:func:`functools.partial` to :py:func:`pow` \n"
    "so that one has a one-argument square function and is significantly faster \n"
    "than ``lambda x: x**2``::\n"
    "\n"
    "    >>> from iteration_utilities import square\n"
    "    >>> square(1)\n"
    "    1\n"
    "    >>> square(2.0)\n"
    "    4.0\n"
);

PyDoc_STRVAR(PyIU_MathDouble_doc,
    "double(value, /)\n"
    "--\n\n"
    "Returns the doubled `value`.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "value : any type\n"
    "    The value to be doubled..\n"
    "\n"
    "Returns\n"
    "-------\n"
    "doubled : any type\n"
    "    Returns ``value*2``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function is equivalent to ``lambda x: x*2`` and for numerical arguments\n"
    "to ``functools.partial(operator.mul, 2)`` but faster::\n"
    "\n"
    "    >>> from iteration_utilities import double\n"
    "    >>> double(1)\n"
    "    2\n"
    "    >>> double(2.0)\n"
    "    4.0\n"
);

PyDoc_STRVAR(PyIU_MathReciprocal_doc,
    "reciprocal(value, /)\n"
    "--\n\n"
    "Returns ``1 / value``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "value : any type\n"
    "    The value for the computation.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "reciprocal  : any type\n"
    "    Returns ``1 / value``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This is equivalent to ``lambda x: 1 / x`` (or ``lambda x: 1. / x`` Python2)\n"
    "or ``functools.partial(operator.truediv, 1)`` but faster::\n"
    "\n"
    "    >>> from iteration_utilities import reciprocal \n"
    "    >>> reciprocal(1)\n"
    "    1.0\n"
    "    >>> reciprocal(2)\n"
    "    0.5\n"
    "    >>> reciprocal(4)\n"
    "    0.25\n"
);

PyDoc_STRVAR(PyIU_MathRadd_doc,
    "radd(op1, op2, /)\n"
    "--\n\n"
    "Returns ``op2 + op1``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "op1, op2 : any type\n"
    "    The values to be added.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "radd : any type\n"
    "    Returns ``op2 + op1``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Equivalent to ``lambda x, y: y + x``::\n"
    "\n"
    "    >>> from iteration_utilities import radd\n"
    "    >>> radd(2, 2)\n"
    "    4\n"
);

PyDoc_STRVAR(PyIU_MathRsub_doc,
    "rsub(op1, op2, /)\n"
    "--\n\n"
    "Returns ``op2 - op1``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "op1, op2 : any type\n"
    "    The values to be subtracted.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "rsub : any type\n"
    "    Returns ``op2 - op1``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Equivalent to ``lambda x, y: y - x``::\n"
    "\n"
    "    >>> from iteration_utilities import rsub\n"
    "    >>> rsub(2, 5)\n"
    "    3\n"
);

PyDoc_STRVAR(PyIU_MathRmul_doc,
    "rmul(op1, op2, /)\n"
    "--\n\n"
    "Returns ``op2 * op1``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "op1, op2 : any type\n"
    "    The values to be multiplied.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "rmul : any type\n"
    "    Returns ``op2 * op1``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Equivalent to ``lambda x, y: y * x``::\n"
    "\n"
    "    >>> from iteration_utilities import rmul\n"
    "    >>> rmul(2, 2)\n"
    "    4\n"
);

PyDoc_STRVAR(PyIU_MathRdiv_doc,
    "rdiv(op1, op2, /)\n"
    "--\n\n"
    "Returns ``op2 / op1``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "op1, op2 : any type\n"
    "    The values to be divided.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "rdiv : any type\n"
    "    Returns ``op2 / op1``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Equivalent to ``lambda x, y: y / x``::\n"
    "\n"
    "    >>> from iteration_utilities import rdiv\n"
    "    >>> rdiv(10, 1)\n"
    "    0.1\n"
);

PyDoc_STRVAR(PyIU_MathRfdiv_doc,
    "rfdiv(op1, op2, /)\n"
    "--\n\n"
    "Returns ``op2 // op1``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "op1, op2 : any type\n"
    "    The values to be floor divided.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "rfdiv : any type\n"
    "    Returns ``op2 // op1``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Equivalent to ``lambda x, y: y // x``::\n"
    "\n"
    "    >>> from iteration_utilities import rfdiv\n"
    "    >>> rfdiv(10, 22)\n"
    "    2\n"
);

PyDoc_STRVAR(PyIU_MathRpow_doc,
    "rpow(op1, op2, /)\n"
    "--\n\n"
    "Returns ``op2 ** op1``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "op1, op2 : any type\n"
    "    The values for the operation.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "rpow : any type\n"
    "    Returns ``op2 ** op1``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Equivalent to ``lambda x, y: y ** x``::\n"
    "\n"
    "    >>> from iteration_utilities import rpow\n"
    "    >>> rpow(3, 2)\n"
    "    8\n"
);

PyDoc_STRVAR(PyIU_MathRmod_doc,
    "rmod(op1, op2, /)\n"
    "--\n\n"
    "Returns ``op2 % op1``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "op1, op2 : any type\n"
    "    Get the remainder of these two operands.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "rmod : any type\n"
    "    Returns ``op2 % op1``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Equivalent to ``lambda x, y: y % x``::\n"
    "\n"
    "    >>> from iteration_utilities import rmod\n"
    "    >>> rmod(2, 5)\n"
    "    1\n"
);

PyDoc_STRVAR(PyIU_ReturnIdentity_doc,
    "return_identity(obj, /)\n"
    "--\n\n"
    "Always return the argument.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "obj : any type \n"
    "    The `obj` to return.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "identity : any type\n"
    "    The argument itself.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function is equivalent to ``lambda x: x`` but significantly faster::\n"
    "\n"
    "    >>> from iteration_utilities import return_identity\n"
    "    >>> return_identity(1)\n"
    "    1\n"
    "    >>> return_identity('abc')\n"
    "    'abc'\n"
);

PyDoc_STRVAR(PyIU_ReturnCalled_doc,
    "return_called(func, /)\n"
    "--\n\n"
    "Return the result of ``func()``.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "func : callable \n"
    "    The function to be called.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "result : any type\n"
    "    The result of ``func()``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function is equivalent to ``lambda x: x()`` but significantly\n"
    "faster::\n"
    "\n"
    "    >>> from iteration_utilities import return_called\n"
    "    >>> return_called(int)\n"
    "    0\n"
);

PyDoc_STRVAR(PyIU_ReturnFirstArg_doc,
    "return_first_arg(*args, **kwargs)\n"
    "--\n\n"
    "Always return the first positional argument given to the function.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "args, kwargs \n"
    "    any number of positional or keyword parameter.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "first_positional_argument : any type\n"
    "    Always returns the first positional argument given to the function.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function is equivalent to ``lambda *args, **kwargs: args[0]`` but\n"
    "significantly faster::\n"
    "\n"
    "    >>> from iteration_utilities import return_first_arg\n"
    "    >>> return_first_arg(1, 2, 3, 4, a=100)\n"
    "    1\n"
);

PyDoc_STRVAR(seen_doc,
    "Seen(seenset=None, seenlist=None)\n"
    "--\n\n"
    "Helper class which adds the items after each :py:meth:`.contains_add` check.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "seenset : :py:class:`set` or None, optional\n"
    "    A :py:class:`set` containing initial values.\n"
    "\n"
    "seenlist : :py:class:`list` or None, optional\n"
    "    A :py:class:`list` containing only unhashable initial values.\n"
    "    \n"
    "    .. note::\n"
    "        The `seenlist` should not contain hashable values (these will \n"
    "        be ignored for all practical purposes)!\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This class adds each item after :py:meth:`.contains_add` call but also \n"
    "supports normal :py:meth:`in <.__contains__>` operations::\n"
    "\n"
    "    >>> from iteration_utilities import Seen\n"
    "    >>> x = Seen()\n"
    "    >>> # normal \"in\" operations do not add the element to the instance\n"
    "    >>> 1 in x\n"
    "    False\n"
    "    >>> 1 in x\n"
    "    False\n"
    "    \n"
    "    >>> # \"contains_add\" checks if the item is contained but also adds it\n"
    "    >>> x.contains_add(2)\n"
    "    False\n"
    "    >>> x.contains_add(2)\n"
    "    True\n"
    "    >>> x  # doctest: +SKIP\n"
    "    iteration_utilities.Seen({2})\n"
    "    \n"
    "    >>> x.contains_add([1, 2])\n"
    "    False\n"
    "    >>> [1, 2] in x\n"
    "    True\n"
    "    >>> x  # doctest: +SKIP\n"
    "    iteration_utilities.Seen({2}, unhashable=[[1, 2]])\n"
    "\n"
    "This class does only support :py:meth:`in <.__contains__>`, \n"
    ":py:meth:`== <.__eq__>`, :py:meth:`\\!= <.__ne__>` and \n"
    ":py:meth:`len <.__len__>`.\n"
    "It is mostly included because it unified the code in \n"
    ":py:func:`~iteration_utilities.duplicates`,\n"
    ":py:func:`~iteration_utilities.unique_everseen`, and \n"
    ":py:func:`~iteration_utilities.all_distinct` and might be useful in other \n"
    "applications.\n"
);

PyDoc_STRVAR(seen_containsadd_doc,
    "contains_add(o, /)\n"
    "--\n\n"
    "Check if `o` is already contained in `self` and return the result.\n"
    "But also adds `o` to `self` if it's not contained.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "o : any type\n"
    "    The object to check if it's contained in `self` and added to\n"
    "    `self` if not.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "contained : :py:class:`bool`\n"
    "    ``True`` if `o` is contained in `self` otherwise ``False``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "A simple example::\n"
    "\n"
    "    >>> from iteration_utilities import Seen\n"
    "    >>> x = Seen()\n"
    "    >>> 10 in x\n"
    "    False\n"
    "    >>> x.contains_add(10)\n"
    "    False\n"
    "    >>> 10 in x\n"
    "    True\n"
    "    >>> x.contains_add(10)\n"
    "    True\n"
    "    >>> x  #doctest: +SKIP\n"
    "    iteration_utilities.Seen({10})\n"
);

PyDoc_STRVAR(accumulate_doc,
    "accumulate(iterable, func=None, start=None)\n"
    "--\n\n"
    "Make an iterator that returns accumulated sums, or accumulated\n"
    "results of other binary functions (specified via the optional `func`\n"
    "argument). Copied and modified from [0]_.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    The `iterable` to accumulate.\n"
    "\n"
    "func : callable or None, optional\n"
    "    The function with which to accumulate. Should be a function of two\n"
    "    arguments.\n"
    "    If ``None`` defaults to :py:func:`operator.add`.\n"
    "\n"
    "start : any type, optional\n"
    "    If given (even as ``None``) this value is inserted before the `iterable`.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "accumulated : generator\n"
    "    The accumulated results as generator.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "Elements of the input `iterable` may be any type that can be\n"
    "accepted as arguments to `func`. (For example, with the default\n"
    "operation of addition, elements may be any addable type including\n"
    "Decimal or Fraction.) If the input `iterable` is empty, the output\n"
    "iterable will also be empty.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "There are a number of uses for the `func` argument. It can be set to\n"
    ":py:func:`min` for a running minimum, :py:func:`max` for a running\n"
    "maximum, or :py:func:`operator.mul` for a running product. Amortization\n"
    "tables can be built by accumulating interest and applying payments.\n"
    "First-order recurrence relations can be modeled by supplying the\n"
    "initial value in the `iterable` and using only the accumulated total in\n"
    "`func` argument::\n"
    "\n"
    "    >>> from iteration_utilities import accumulate\n"
    "    >>> from itertools import repeat\n"
    "    >>> import operator\n"
    "\n"
    "    >>> data = [3, 4, 6, 2, 1, 9, 0, 7, 5, 8]\n"
    "    >>> list(accumulate(data))                   # running sum\n"
    "    [3, 7, 13, 15, 16, 25, 25, 32, 37, 45]\n"
    "    >>> list(accumulate(data, operator.add))     # running sum (explicit)\n"
    "    [3, 7, 13, 15, 16, 25, 25, 32, 37, 45]\n"
    "    >>> list(accumulate(data, operator.mul))     # running product\n"
    "    [3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]\n"
    "    >>> list(accumulate(data, max))              # running maximum\n"
    "    [3, 4, 6, 6, 6, 9, 9, 9, 9, 9]\n"
    "\n"
    "Amortize a 5% loan of 1000 (start value) with 4 annual payments of 90::\n"
    "\n"
    "    >>> cashflows = [-90, -90, -90, -90]\n"
    "    >>> list(accumulate(cashflows, lambda bal, pmt: bal*1.05 + pmt, 1000))\n"
    "    [960.0, 918.0, 873.9000000000001, 827.5950000000001]\n"
    "\n"
    "Chaotic recurrence relation [1]_::\n"
    "\n"
    "    >>> logistic_map = lambda x, _:  r * x * (1 - x)\n"
    "    >>> r = 3.8\n"
    "    >>> x0 = 0.4\n"
    "    >>> inputs = repeat(x0, 36)     # only the initial value is used\n"
    "    >>> [format(x, '.2f') for x in accumulate(inputs, logistic_map)]\n"
    "    ['0.40', '0.91', '0.30', '0.81', '0.60', '0.92', '0.29', '0.79', "
    "'0.63', '0.88', '0.39', '0.90', '0.33', '0.84', '0.52', '0.95', '0.18', "
    "'0.57', '0.93', '0.25', '0.71', '0.79', '0.63', '0.88', '0.39', '0.91', "
    "'0.32', '0.83', '0.54', '0.95', '0.20', '0.60', '0.91', '0.30', '0.80', '0.60']\n"
    "\n"
    "References\n"
    "----------\n"
    ".. [0] https://docs.python.org/3/library/itertools.html#itertools.accumulate\n"
    ".. [1] https://en.wikipedia.org/wiki/Logistic_map\n"
);

PyDoc_STRVAR(PyIU_AllDistinct_doc,
    "all_distinct(iterable, /)\n"
    "--\n\n"
    "Checks if all items in the `iterable` are distinct.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    `Iterable` containing the elements.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "distinct : :py:class:`bool`\n"
    "    ``True`` if no two values are equal and ``False`` if there is at least\n"
    "    one duplicate in `iterable`.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "The items in the `iterable` should implement equality.\n"
    "\n"
    "If the items are hashable the function is much faster.\n"
    "\n"
    "Examples\n"
    "--------\n"
    ">>> from iteration_utilities import all_distinct\n"
    ">>> all_distinct('AAAABBBCCDAABBB')\n"
    "False\n"
    "\n"
    ">>> all_distinct('abcd')\n"
    "True\n"
);

PyDoc_STRVAR(PyIU_AllEqual_doc,
    "all_equal(iterable, /)\n"
    "--\n\n"
    "Checks if all the elements are equal to each other.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    Any `iterable` to test.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "all_equal : :py:class:`bool`\n"
    "    ``True`` if all elements in `iterable` are equal or ``False`` if not.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "If the input is empty the function returns ``True``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    ">>> from iteration_utilities import all_equal\n"
    ">>> all_equal([1,1,1,1,1,1,1,1,1])\n"
    "True\n"
    "\n"
    ">>> all_equal([1,1,1,1,1,1,1,2,1])\n"
    "False\n"
);

PyDoc_STRVAR(PyIU_AllIsinstance_doc,
    "all_isinstance(iterable, types)\n"
    "--\n\n"
    "Like :py:func:`isinstance` but for `iterables`.\n"
    "\n"
    "Checks if all items in `iterable` are instances of `types`.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    Each item of the `iterable` is tested with ``isinstance(item, types)``.\n"
    "\n"
    "types : :py:class:`type` or :py:class:`tuple` of types\n"
    "    Test for this type if it's a single class or test if the item is of any\n"
    "    of the types (if types is a :py:class:`tuple`).\n"
    "\n"
    "Returns\n"
    "-------\n"
    "all : :py:class:`bool`\n"
    "    ``True`` if all elements in `iterable` are instances of `types`,\n"
    "    ``False`` if not.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function is equivalent (but faster) than\n"
    "``all(isinstance(item, types) for item in iterable)``::\n"
    "\n"
    "    >>> from iteration_utilities import all_isinstance\n"
    "    >>> all_isinstance(range(100), int)\n"
    "    True\n"
    "\n"
    "    >>> all_isinstance([1, 2, 3.2], (int, float))\n"
    "    True\n"
    "\n"
    ".. warning::\n"
    "    This function returns ``True`` if the `iterable` is empty.\n"
);

PyDoc_STRVAR(PyIU_Monotone_doc,
    "all_monotone(iterable, decreasing=False, strict=False)\n"
    "--\n\n"
    "Checks if the elements in `iterable` are (strictly) monotonic \n"
    "increasing or decreasing.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    Any `iterable` to test.\n"
    "\n"
    "decreasing : :py:class:`bool`, optional\n"
    "    If ``False`` check if the values are monotonic increasing, otherwise\n"
    "    check for monotone decreasing.\n"
    "    Default is ``False``.\n"
    "\n"
    "strict : :py:class:`bool`, optional\n"
    "    If ``True`` check if the elements are strictly greater or smaller\n"
    "    (``>`` or ``<``) than their predecessor. Otherwise use ``>=`` and ``<=``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "monotonic : :py:class:`bool`\n"
    "    ``True`` if all elements in `iterable` are monotonic or ``False`` if not.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "If the input is empty the function returns ``True``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This is roughly equivalent to\n"
    "``all(itertools.starmap(operator.lt, iteration_utilities.successive(iterable, 2)))``\n"
    "with the appropriate operator depending on `decreasing` and `strict`::\n"
    "\n"
    "    >>> from iteration_utilities import all_monotone\n"
    "    >>> all_monotone([1,1,1,1,1,1,1,1,1])\n"
    "    True\n"
    "    >>> all_monotone([1,1,1,1,1,1,1,1,1], strict=True)\n"
    "    False\n"
    "    >>> all_monotone([2,1,1,1,1,1,1,1,0], decreasing=True)\n"
    "    True\n"
    "    >>> all_monotone([2,1,1,1,1,1,1,1,0], decreasing=True, strict=True)\n"
    "    False\n"
);

PyDoc_STRVAR(PyIU_AnyIsinstance_doc,
    "any_isinstance(iterable, types)\n"
    "--\n\n"
    "Like :py:func:`isinstance` but for `iterables`.\n"
    "\n"
    "Checks if any item in `iterable` is an instance of `types`.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    Each item of the `iterable` is tested with ``isinstance(item, types)``.\n"
    "\n"
    "types : :py:class:`type` or :py:class:`tuple` of types\n"
    "    Test for this type if it's a single class or test if the item is of any\n"
    "    of the types (if types is a :py:class:`tuple`).\n"
    "\n"
    "Returns\n"
    "-------\n"
    "any : :py:class:`bool`\n"
    "    ``True`` if any elements in `iterable` is an instance of `types`,\n"
    "    ``False`` if not.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function is equivalent (but faster) than\n"
    "``any(isinstance(item, types) for item in iterable)``\n"
    "\n"
    "    >>> from iteration_utilities import any_isinstance\n"
    "    >>> all_isinstance(range(100), int)\n"
    "    True\n"
    "\n"
    "    >>> any_isinstance([1, 2, 3.2], float)\n"
    "    True\n"
);

PyDoc_STRVAR(applyfunc_doc,
    "applyfunc(func, initial)\n"
    "--\n\n"
    "Successivly apply `func` on `value`.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "func : callable\n"
    "    The function to apply. The `value` is given as first argument to the \n"
    "    `func`, no other arguments will be passed during the function call.\n"
    "\n"
    "initial : any type\n"
    "    The `initial` `value` for the function.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "results : generator\n"
    "    The result of the successivly applied `func`.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "The first element is the initial `value` and the next elements are\n"
    "the result of ``func(value)``, then ``func(func(value))``, ...::\n"
    "\n"
    "    >>> from iteration_utilities import applyfunc, getitem\n"
    "    >>> import math\n"
    "    >>> list(getitem(applyfunc(math.sqrt, 10), stop=4))\n"
    "    [3.1622776601683795, 1.7782794100389228, 1.333521432163324, 1.1547819846894583]\n"
    "\n"
    ".. warning::\n"
    "    This will return an infinitly long generator so do **not** try to do\n"
    "    something like ``list(applyfunc())``!\n"
);

PyDoc_STRVAR(PyIU_Argmin_doc,
    "argmin(iterable, /, key, default)\n"
    "--\n\n"
    "Find index of the minimum.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    The `iterable` for which to calculate the index of the minimum.\n"
    "\n"
    "    .. note::\n"
    "        Instead of one `iterable` it is also possible to pass the values (at\n"
    "        least 2) as positional arguments.\n"
    "\n"
    "key : callable, optional\n"
    "    If not given then compare the values, otherwise compare ``key(item)``.\n"
    "\n"
    "default : :py:class:`int`, optional\n"
    "    If given an empty `iterable` will return `default` instead of raising a \n"
    "    ``ValueError``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "argmin : :py:class:`int`\n"
    "    The index of the minimum or default if the `iterable` was empty.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This is equivalent (but faster) than \n"
    "``min(enumerate(iterable), key=operator.itemgetter(1))[0]``::\n"
    "\n"
    "    >>> from iteration_utilities import argmin\n"
    "    >>> argmin(3,2,1,2,3)\n"
    "    2\n"
    "\n"
    "It allows a `key` function::\n"
    "\n"
    "    >>> argmin([3, -3, 0], key=abs)\n"
    "    2\n"
    "\n"
    "And a `default`::\n"
    "\n"
    "    >>> argmin([], default=10)\n"
    "    10\n"
);

PyDoc_STRVAR(PyIU_Argmax_doc,
    "argmax(iterable, /, key=None, default=None)\n"
    "--\n\n"
    "Find index of the maximum.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    The `iterable` for which to calculate the index of the maximum.\n"
    "\n"
    "    .. note::\n"
    "        Instead of one `iterable` it is also possible to pass the values (at\n"
    "        least 2) as positional arguments.\n"
    "\n"
    "key : callable, optional\n"
    "    If not given then compare the values, otherwise compare ``key(item)``.\n"
    "\n"
    "default : :py:class:`int`, optional\n"
    "    If not given raise ``ValueError`` if the `iterable` is empty otherwise\n"
    "    return ``default``\n"
    "\n"
    "Returns\n"
    "-------\n"
    "argmax : :py:class:`int`\n"
    "    The index of the maximum or default if the `iterable` was empty.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This is equivalent (but faster) than \n"
    "``max(enumerate(iterable), key=operator.itemgetter(1))[0]``::\n"
    "\n"
    "    >>> from iteration_utilities import argmax\n"
    "    >>> argmax(3,2,1,2,3)\n"
    "    0\n"
    "\n"
    "It allows a `key` function::\n"
    "\n"
    "    >>> argmax([0, -3, 3, 0], key=abs)\n"
    "    1\n"
    "\n"
    "And a `default`::\n"
    "\n"
    "    >>> argmax([], default=10)\n"
    "    10\n"
);

PyDoc_STRVAR(chained_doc,
    "chained(*funcs, /, reverse=False, all=False)\n"
    "--\n\n"
    "Chained function calls.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "funcs\n"
    "    Any number of callables.\n"
    "\n"
    "reverse : :py:class:`bool`, optional\n"
    "    If ``True`` apply the the `funcs` in reversed order.\n"
    "    Default is ``False``.\n"
    "\n"
    "all : :py:class:`bool`, optional\n"
    "    If ``True`` apply each of the `funcs` seperatly and return a tuple\n"
    "    containing the individual results when calling the instance.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "chained_func : callable\n"
    "    The chained `funcs`.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "`chained` simple calls all `funcs` on the result of the previous one::\n"
    "\n"
    "    >>> from iteration_utilities import chained\n"
    "    >>> double = lambda x: x*2\n"
    "    >>> increment = lambda x: x+1\n"
    "    >>> double_then_increment = chained(double, increment)\n"
    "    >>> double_then_increment(10)\n"
    "    21\n"
    "\n"
    "Or apply them in reversed order::\n"
    "\n"
    "    >>> increment_then_double = chained(double, increment, reverse=True)\n"
    "    >>> increment_then_double(10)\n"
    "    22\n"
    "\n"
    "Or apply all of them on the input::\n"
    "\n"
    "    >>> double_and_increment = chained(double, increment, all=True)\n"
    "    >>> double_and_increment(10)\n"
    "    (20, 11)\n"
);

PyDoc_STRVAR(clamp_doc,
    "clamp(iterable, low=None, high=None, inclusive=False, remove=True)\n"
    "--\n\n"
    "Remove values which are not between `low` and `high`.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    Clamp the values from this `iterable`.\n"
    "\n"
    "low : any type, optional\n"
    "    The lower bound for clamp. If not given or ``None`` there is no lower \n"
    "    bound.\n"
    "\n"
    "high : any type, optional\n"
    "    The upper bound for clamp. If not given or ``None`` there is no upper \n"
    "    bound.\n"
    "\n"
    "inclusive : :py:class:`bool`, optional\n"
    "    If ``True`` also remove values that are equal to `low` and `high`.\n"
    "    Default is ``False``.\n"
    "\n"
    "remove : :py:class:`bool`, optional\n"
    "    If ``True`` remove the items outside the range given by ``low`` and\n"
    "    ``high``, otherwise replace them with ``low`` if they are lower or\n"
    "    ``high`` if they are higher.\n"
    "    Default is ``True``.\n"
    "\n"
    "    .. versionadded:: 0.2\n"
    "\n"
    "Returns\n"
    "-------\n"
    "clamped : generator\n"
    "    A generator containing the values of `iterable` which are between `low`\n"
    "    and `high`.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function is equivalent to a generator expression like:\n"
    "``(item for item in iterable if low <= item <= high)`` or\n"
    "``(item for item in iterable if low < item < high)`` if `inclusive=True`.\n"
    "Or a similar `filter`: ``filter(lambda item: low <= item <= high, iterable)``\n"
    "But it also allows for either ``low`` or ``high`` to be ignored and is faster.\n"
    "Some simple examples::\n"
    "\n"
    "    >>> from iteration_utilities import clamp\n"
    "    >>> list(clamp(range(5), low=2))\n"
    "    [2, 3, 4]\n"
    "    >>> list(clamp(range(5), high=2))\n"
    "    [0, 1, 2]\n"
    "    >>> list(clamp(range(1000), low=2, high=8, inclusive=True))\n"
    "    [3, 4, 5, 6, 7]\n"
    "\n"
    "If ``remove=False`` the function will replace values instead::\n"
    "\n"
    "    >>> list(clamp(range(10), low=4, high=8, remove=False))\n"
    "    [4, 4, 4, 4, 4, 5, 6, 7, 8, 8]\n"
);

PyDoc_STRVAR(complement_doc,
    "complement(func)\n"
    "--\n\n"
    "Invert a predicate function. There is a homonymous function in the `toolz` \n"
    "package ([0]_) but significantly modified.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "func : callable\n"
    "    The function to complement.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "complemented_func : callable\n"
    "    The complement to `func`.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "`complement` is equivalent to ``lambda x: not x()`` but significantly faster::\n"
    "\n"
    "    >>> from iteration_utilities import complement\n"
    "    >>> from iteration_utilities import is_None\n"
    "    >>> is_not_None = complement(is_None)\n"
    "    >>> list(filter(is_not_None, [1,2,None,3,4,None]))\n"
    "    [1, 2, 3, 4]\n"
    "\n"
    ".. note::\n"
    "    The example code could also be done with :py:func:`itertools.filterfalse` \n"
    "    or :py:func:`iteration_utilities.is_not_None`.\n"
    "\n"
    "References\n"
    "----------\n"
    ".. [0] https://toolz.readthedocs.io/en/latest/index.html\n"
);

PyDoc_STRVAR(constant_doc,
    "constant(item, /)\n"
    "--\n\n"
    "Class that always returns a constant value when called.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "item : any type\n"
    "    The item that should be returned when called.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Creating :py:class:`~iteration_utilities.constant` instances::\n"
    "\n"
    "    >>> from iteration_utilities import constant\n"
    "    >>> five = constant(5)\n"
    "    >>> five()\n"
    "    5\n"
    "    >>> ten = constant(10)\n"
    "    >>> # Any parameters are ignored\n"
    "    >>> ten(5, give_me=100)\n"
    "    10\n"
    "\n"
    "There are already three predefined instances:\n"
    "\n"
    "- :py:func:`~iteration_utilities.return_True`: equivalent to ``constant(True)``.\n"
    "- :py:func:`~iteration_utilities.return_False`: equivalent to ``constant(False)``.\n"
    "- :py:func:`~iteration_utilities.return_None`: equivalent to ``constant(None)``.\n"
    "\n"
    "For example::\n"
    "\n"
    "    >>> from iteration_utilities import return_True, return_False, return_None\n"
    "    >>> return_True()\n"
    "    True\n"
    "    >>> return_False()\n"
    "    False\n"
    "    >>> return_None()\n"
    "    >>> return_None() is None\n"
    "    True\n"
);

PyDoc_STRVAR(PyIU_Count_doc,
    "count_items(iterable, pred=None, eq=False)\n"
    "--\n\n"
    "Count how many times the predicate is true.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    Any `iterable` to count in.\n"
    "\n"
    "pred : callable, any type, None, optional\n"
    "    Predicate to test. Depending on the `eq` parameter this parameter has\n"
    "    different meanings:\n"
    "    \n"
    "    - ``eq=True`` : Each item will be counted if ``item == pred``, the `pred`\n"
    "      must not be omitted in this case.\n"
    "    - ``eq=False`` : If ``pred`` is not given or ``None`` then each item in\n"
    "      the iterable is counted.\n"
    "      If ``pred`` is given and not ``None`` then each item satisifying\n"
    "      ``if pred(item)`` is counted.\n"
    "\n"
    "    Default is ``None``.\n"
    "\n"
    "eq : :py:class:`bool`, optional\n"
    "    If ``True`` compare each item in the `iterable` to `pred` instead of\n"
    "    calling ``pred(item)``.\n"
    "    Default is ``False``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "number : number\n"
    "    The numer of times the predicate is ``True``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "To count how many elements are within an `iterable`::\n"
    "\n"
    "    >>> from iteration_utilities import count_items\n"
    "    >>> count_items([0, 0, '', {}, [], 2])\n"
    "    6\n"
    "\n"
    "To count the number of truthy values::\n"
    "\n"
    "    >>> count_items([0, 0, '', {}, [], 2], pred=bool)\n"
    "    1\n"
    "\n"
    "To count the number of values satisfying a condition::\n"
    "\n"
    "    >>> def smaller5(val): return val < 5\n"
    "    >>> count_items([1, 2, 3, 4, 5, 6, 6, 7], smaller5)\n"
    "    4\n"
    "\n"
    "To count the number of values equal to another value::\n"
    "\n"
    "    >>> count_items([1, 2, 3, 4, 5, 6, 6, 7], 6, True)\n"
    "    2\n"
);

PyDoc_STRVAR(deepflatten_doc,
    "deepflatten(iterable, depth=-1, types=None, ignore=None)\n"
    "--\n\n"
    "Flatten an `iterable` with given `depth`.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    Any `iterable` to flatten.\n"
    "\n"
    "depth : :py:class:`int` or None, optional\n"
    "    Flatten `depth` levels of nesting or all if ``depth=-1``.\n"
    "    Default is ``-1``.\n"
    "\n"
    "    .. note::\n"
    "       If the `depth` is known this significantly speeds up the function!\n"
    "\n"
    "types : type, tuple of types, optional\n"
    "    Which types should be flattened. If not given it flattens all items if\n"
    "    ``iter(item)`` does not throw a ``TypeError``.\n"
    "\n"
    "    .. note::\n"
    "       If the `types` are known this significantly speeds up the function\n"
    "       but only *if* the `depth` is unknown.\n"
    "\n"
    "ignore : type, iterable of types or None, optional\n"
    "    The types which should not be flattened. If not given all `types` are\n"
    "    flattened.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "flattened_iterable : generator\n"
    "    The `iterable` with the `depth` level of nesting flattened.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "To flatten a given depth::\n"
    "\n"
    "    >>> from iteration_utilities import deepflatten, EQ_PY2\n"
    "    >>> list(deepflatten([1, [1,2], [[1,2]], [[[1,2]]]], depth=1))\n"
    "    [1, 1, 2, [1, 2], [[1, 2]]]\n"
    "\n"
    "To completly flatten it::\n"
    "\n"
    "    >>> list(deepflatten([1, [1,2], [[1,2]], [[[1,2]]]]))\n"
    "    [1, 1, 2, 1, 2, 1, 2]\n"
    "\n"
    "To ignore for example dictionaries::\n"
    "\n"
    "    >>> # Only the keys of a dictionary will be kept with deepflatten.\n"
    "    >>> list(deepflatten([1, 2, [1,2],  {1: 10, 2: 10}]))\n"
    "    [1, 2, 1, 2, 1, 2]\n"
    "    >>> list(deepflatten([1, 2, [1,2],  {1: 10, 2: 10}], ignore=dict))\n"
    "    [1, 2, 1, 2, {1: 10, 2: 10}]\n"
    "\n"
    "In this case we could have also chosen only to flatten the lists::\n"
    "\n"
    "    >>> list(deepflatten([1, 2, [1,2],  {1: 10, 2: 10}], types=list))\n"
    "    [1, 2, 1, 2, {1: 10, 2: 10}]\n"
    "\n"
    ".. warning::\n"
    "    If the iterable contains recursive iterable objects (i.e. `UserString`)\n"
    "    one either needs to set ``ignore`` or a `depth` that is not ``None``.\n"
    "    Otherwise this will raise an ``RecursionError`` (or ``RuntimeError`` on\n"
    "    older Python versions) because each item in a ``UserString`` is itself a\n"
    "    ``UserString``, even if it has a length of 1! The builtin strings \n"
    "    (``str``, ``bytes``, ``unicode``) are special cased, but only the exact\n"
    "    types because subtypes might implement custom not-recusive ``__iter__``\n"
    "    methods. This means that these won't run into the infinite recursion,\n"
    "    but subclasses might.\n"
    "\n"
    "See for example::\n"
    "\n"
    "    >>> if EQ_PY2:\n"
    "    ...     from UserString import UserString\n"
    "    ... else:\n"
    "    ...     from collections import UserString\n"
    "    >>> list(deepflatten([1, 2, [1,2], UserString('abc')], depth=1))\n"
    "    [1, 2, 1, 2, 'a', 'b', 'c']\n"
    "    >>> list(deepflatten([1, 2, [1,2], UserString('abc')], ignore=UserString))\n"
    "    [1, 2, 1, 2, 'abc']\n"
    "\n"
    "For Python2 you should ignore ``basestring`` instead of ``str``.\n"
    "\n"
    "This function is roughly (it's missing some of the complicated details of\n"
    "the actual function) equivalent to this python function:\n"
    "\n"
    ".. code::\n"
    "\n"
    "    def deepflatten(iterable, depth=None, types=None, ignore=None):\n"
    "        if depth is None:\n"
    "            depth = float('inf')\n"
    "        if depth == -1:\n"
    "            yield iterable\n"
    "        else:\n"
    "            for x in iterable:\n"
    "                if ignore is not None and isinstance(x, ignore):\n"
    "                    yield x\n"
    "                if types is None:\n"
    "                    try:\n"
    "                        iter(x)\n"
    "                    except TypeError:\n"
    "                        yield x\n"
    "                    else:\n"
    "                        for item in deepflatten(x, depth - 1, types, ignore):\n"
    "                            yield item\n"
    "                elif not isinstance(x, types):\n"
    "                    yield x\n"
    "                else:\n"
    "                    for item in deepflatten(x, depth - 1, types, ignore):\n"
    "                        yield item\n"
);

PyDoc_STRVAR(PyIU_DotProduct_doc,
    "dotproduct(vec1, vec2)\n"
    "--\n\n"
    "Dot product (matrix multiplication) of two vectors.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "vec1, vec2 : iterable\n"
    "    Any `iterables` to calculate the dot product. Positional-only parameter.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "dotproduct : number\n"
    "    The dot product - the sum of the element-wise multiplication.\n"
    "\n"
    "Examples\n"
    "--------\n"
    ">>> from iteration_utilities import dotproduct\n"
    ">>> dotproduct([1,2,3,4], [1,2,3,4])\n"
    "30\n"
);

PyDoc_STRVAR(duplicates_doc,
    "duplicates(iterable, key=None)\n"
    "--\n\n"
    "Return only duplicate entries, remembers all items ever seen.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    `Iterable` containing the elements.\n"
    "\n"
    "key : callable, optional\n"
    "    If given it must be a callable taking one argument and this\n"
    "    callable is applied to the value before checking if it was seen yet.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "iterable : generator\n"
    "    An iterable containing all duplicates values of the `iterable`.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "The items in the `iterable` should implement equality.\n"
    "\n"
    "If the items are hashable the function is much faster.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Multiple duplicates will be kept::\n"
    "\n"
    "    >>> from iteration_utilities import duplicates\n"
    "    >>> list(duplicates('AABBCCDA'))\n"
    "    ['A', 'B', 'C', 'A']\n"
    "\n"
    "    >>> list(duplicates('ABBCcAD', str.lower))\n"
    "    ['B', 'c', 'A']\n"
    "\n"
    "To get each duplicate only once this can be combined with \n"
    ":py:func:`~iteration_utilities.unique_everseen`::\n"
    "\n"
    "    >>> from iteration_utilities import unique_everseen\n"
    "    >>> list(unique_everseen(duplicates('AABBCCDA')))\n"
    "    ['A', 'B', 'C']\n"
);

PyDoc_STRVAR(flip_doc,
    "flip(x, /)\n"
    "--\n\n"
    "Class that reverses the positional arguments to a `func` when called.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "func : callable\n"
    "    The function that should be called with the flipped (reversed) arguments.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This can be used to alter the call to a function::\n"
    "\n"
    "    >>> from iteration_utilities import flip\n"
    "    >>> from functools import partial\n"
    "    >>> flipped = flip(isinstance)\n"
    "    >>> isfloat = partial(flipped, float)\n"
    "\n"
    "    >>> isfloat(10)\n"
    "    False\n"
    "    >>> isfloat(11.25)\n"
    "    True\n"
);

PyDoc_STRVAR(PyIU_Groupby_doc,
    "groupedby(iterable, key, keep=None, reduce=None, reducestart=None)\n"
    "--\n\n"
    "Group values of `iterable` by a `key` function as dictionary.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    The `iterable` to group by a `key` function.\n"
    "\n"
    "key : callable\n"
    "    The items of the `iterable` are grouped by the ``key(item)``.\n"
    "\n"
    "keep : callable, optional\n"
    "    If given append only the result of ``keep(item)`` instead of ``item``.\n"
    "\n"
    "reduce : callable, optional\n"
    "    If given then instead of returning a list of all ``items`` reduce them\n"
    "    using the binary `reduce` function. This works like the `func` parameter\n"
    "    in :py:func:`functools.reduce`.\n"
    "\n"
    "reducestart : any type, optional\n"
    "    If given (even as ``None``) it will be interpreted as startvalue for the\n"
    "    `reduce` function.\n"
    "    \n"
    "    .. note::\n"
    "       Can only be specified if `reduce` is given.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "grouped : dict\n"
    "    A dictionary where the `keys` represent the ``key(item)`` and the `values`\n"
    "    are lists containing all ``items`` having the same `key`.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "This function differs from ``itertools.groupy`` in several ways: (1) This\n"
    "function is eager (consumes the `iterable` in one go) and (2) the itertools\n"
    "function only groups the `iterable` locally.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "A simple example::\n"
    "\n"
    "    >>> from iteration_utilities import groupedby\n"
    "    >>> from operator import itemgetter, add\n"
    "    >>> dct = groupedby(['a', 'bac', 'ba', 'ab', 'abc'], key=itemgetter(0))\n"
    "    >>> dct['a']\n"
    "    ['a', 'ab', 'abc']\n"
    "    >>> dct['b']\n"
    "    ['bac', 'ba']\n"
    "\n"
    "One could also specify a `keep` function::\n"
    "\n"
    "    >>> dct = groupedby(['a', 'bac', 'ba', 'ab', 'abc'], key=itemgetter(0), keep=len)\n"
    "    >>> dct['a']\n"
    "    [1, 2, 3]\n"
    "    >>> dct['b']\n"
    "    [3, 2]\n"
    "\n"
    "Or reduce all values for one key::\n"
    "\n"
    "    >>> from iteration_utilities import is_even\n"
    "    >>> dct = groupedby([1, 2, 3, 4, 5], key=is_even, reduce=add)\n"
    "    >>> dct[True]  # 2 + 4\n"
    "    6\n"
    "    >>> dct[False]  # 1 + 3 + 5\n"
    "    9\n"
    "\n"
    "using `reduce` also allows to specify a startvalue::\n"
    "\n"
    "    >>> dct = groupedby([1, 2, 3, 4, 5], key=is_even, reduce=add, reducestart=7)\n"
    "    >>> dct[True]  # 7 + 2 + 4\n"
    "    13\n"
    "    >>> dct[False]  # 7 + 1 + 3 + 5\n"
    "    16\n"
);

PyDoc_STRVAR(grouper_doc,
    "grouper(iterable, n, fillvalue=None, truncate=False)\n"
    "--\n\n"
    "Collect data into fixed-length chunks or blocks.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    Any `iterable` to group.\n"
    "\n"
    "n : :py:class:`int`\n"
    "    The number of elements in each chunk.\n"
    "\n"
    "fillvalue : any type, optional\n"
    "    The `fillvalue` if the `iterable` is consumed and the last yielded group\n"
    "    should be filled. If not given the last yielded group may be shorter\n"
    "    than the group before. Using ``fillvalue=None`` is different from not \n"
    "    giving a `fillvalue` in that the last group will be filled with ``None``.\n"
    "\n"
    "truncate : :py:class:`bool`, optional\n"
    "    As alternative to `fillvalue` the last group is discarded if it is\n"
    "    shorter than `n` and `truncate` is ``True``.\n"
    "    Default is ``False``.\n"
    "\n"
    "Raises\n"
    "------\n"
    "TypeError\n"
    "    If `truncate` is ``True`` and a `fillvalue` is given.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "groups : generator\n"
    "    An `iterable` containing the groups/chunks as ``tuple``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    ">>> from iteration_utilities import grouper\n"
    "\n"
    ">>> list(grouper('ABCDEFG', 3))\n"
    "[('A', 'B', 'C'), ('D', 'E', 'F'), ('G',)]\n"
    "\n"
    ">>> list(grouper('ABCDEFG', 3, fillvalue='x'))\n"
    "[('A', 'B', 'C'), ('D', 'E', 'F'), ('G', 'x', 'x')]\n"
    "\n"
    ">>> list(grouper('ABCDEFG', 3, truncate=True))\n"
    "[('A', 'B', 'C'), ('D', 'E', 'F')]\n"
);

PyDoc_STRVAR(intersperse_doc,
    "intersperse(iterable, e)\n"
    "--\n\n"
    "Alternately yield an item from the `iterable` and `e`. Recipe based on the\n"
    "homonymous function in the `more-itertools` package ([0]_) but significantly\n"
    "modified.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    The iterable to intersperse.\n"
    "\n"
    "e : any type\n"
    "    The value with which to intersperse the `iterable`.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "interspersed : generator\n"
    "    Interspersed `iterable` as generator.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "This is similar to\n"
    "``itertools.chain.from_iterable(zip(iterable, itertools.repeat(e)))`` except\n"
    "that `intersperse` does not yield `e` as last item.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "A few simple examples::\n"
    "\n"
    "    >>> from iteration_utilities import intersperse\n"
    "    >>> list(intersperse([1,2,3], 0))\n"
    "    [1, 0, 2, 0, 3]\n"
    "\n"
    "    >>> list(intersperse('abc', 'x'))\n"
    "    ['a', 'x', 'b', 'x', 'c']\n"
    "\n"
    "References\n"
    "----------\n"
    ".. [0] https://github.com/erikrose/more-itertools\n"
);

PyDoc_STRVAR(iterexcept_doc,
    "iter_except(func, exception, first=None)\n"
    "--\n\n"
    "Call a function repeatedly until an `exception` is raised.\n"
    "\n"
    "Converts a call-until-exception interface to an iterator interface.\n"
    "Like ``iter(func, sentinel)`` but uses an `exception` instead of a sentinel\n"
    "to end the loop.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "func : callable\n"
    "    The function that is called until `exception` is raised.\n"
    "\n"
    "exception : Exception\n"
    "    The `exception` which terminates the iteration.\n"
    "\n"
    "first : callable or None, optional\n"
    "    If not given (or not ``None``) this function is called once before the \n"
    "    `func` is executed.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "result : generator\n"
    "    The result of the `func` calls as generator.\n"
    "\n"
    "Examples\n"
    "--------\n"
    ">>> from iteration_utilities import iter_except\n"
    ">>> from collections import OrderedDict\n"
    "\n"
    ">>> d = OrderedDict([('a', 1), ('b', 2)])\n"
    ">>> list(iter_except(d.popitem, KeyError))\n"
    "[('b', 2), ('a', 1)]\n"
    "\n"
    ".. note::\n"
    "    ``d.items()`` would yield the same result. At least with Python3.\n"
    "\n"
    ">>> from math import sqrt\n"
    ">>> import sys\n"
    "\n"
    ">>> g = (sqrt(i) for i in [5, 4, 3, 2, 1, 0, -1, -2, -3])\n"
    ">>> func = g.next if sys.version_info.major == 2 else g.__next__\n"
    ">>> def say_go():\n"
    "...     return 'go'\n"
    ">>> list(iter_except(func, ValueError, say_go))\n"
    "['go', 2.23606797749979, 2.0, 1.7320508075688772, 1.4142135623730951, 1.0, 0.0]\n"
    "\n"
    "Notes\n"
    "-----\n"
    "Further examples:\n"
    "\n"
    "- ``bsd_db_iter = iter_except(db.next, bsddb.error, db.first)``\n"
    "- ``heap_iter = iter_except(functools.partial(heappop, h), IndexError)``\n"
    "- ``dict_iter = iter_except(d.popitem, KeyError)``\n"
    "- ``deque_iter = iter_except(d.popleft, IndexError)``\n"
    "- ``queue_iter = iter_except(q.get_nowait, Queue.Empty)``\n"
    "- ``set_iter = iter_except(s.pop, KeyError)``\n"
);

PyDoc_STRVAR(merge_doc,
    "merge(*iterables, /, key=None, reverse=False)\n"
    "--\n\n"
    "Merge several sorted `iterables` into one.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterables : iterable\n"
    "    Any amount of already sorted `iterable` objects.\n"
    "\n"
    "key : callable or None, optional\n"
    "    If not given compare the item themselves otherwise compare the\n"
    "    result of ``key(item)``, like the `key` parameter for\n"
    "    :py:func:`sorted`.\n"
    "\n"
    "reverse : :py:class:`bool`, optional\n"
    "    If ``True`` then merge in decreasing order instead of increasing order.\n"
    "    Default is ``False``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "merged : generator\n"
    "    The merged iterables as generator.\n"
    "\n"
    "See also\n"
    "--------\n"
    "heapq.merge : Equivalent since Python 3.5 but in most cases slower!\n"
    "    Earlier Python versions did not support the `key` or `reverse` argument.\n"
    "\n"
    "sorted : ``sorted(itertools.chain(*iterables))`` supports the same options\n"
    "    and *can* be faster.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "To merge multiple sorted `iterables`::\n"
    "\n"
    "    >>> from iteration_utilities import merge\n"
    "    >>> list(merge([1, 3, 5, 7, 9], [2, 4, 6, 8, 10]))\n"
    "    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n"
    "\n"
    "It's stable and allows a `key` function::\n"
    "\n"
    "    >>> seq1 = [(1, 3), (3, 3)]\n"
    "    >>> seq2 = [(-1, 3), (-3, 3)]\n"
    "    >>> list(merge(seq1, seq2, key=lambda x: abs(x[0])))\n"
    "    [(1, 3), (-1, 3), (3, 3), (-3, 3)]\n"
    "\n"
    "Also possible to `reverse` (biggest to smallest order) the merge::\n"
    "\n"
    "    >>> list(merge([5,1,-8], [10, 2, 1, 0], reverse=True))\n"
    "    [10, 5, 2, 1, 1, 0, -8]\n"
    "\n"
    "But also more than two `iterables`::\n"
    "\n"
    "    >>> list(merge([1, 10, 11], [2, 9], [3, 8], [4, 7], [5, 6], range(10)))\n"
    "    [0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 11]\n"
    "\n"
    "However if the `iterabes` are not sorted the result will be unsorted\n"
    "(partially sorted)::\n"
    "\n"
    "    >>> list(merge(range(10), [6,1,3,2,6,1,6]))\n"
    "    [0, 1, 2, 3, 4, 5, 6, 6, 1, 3, 2, 6, 1, 6, 7, 8, 9]\n"
);

PyDoc_STRVAR(PyIU_MinMax_doc,
    "minmax(iterable, /, key, default)\n"
    "--\n\n"
    "Computes the minimum and maximum values in one-pass using only\n"
    "``1.5*len(iterable)`` comparisons. Recipe based on the snippet\n"
    "of Raymond Hettinger ([0]_) but significantly modified.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    The `iterable` for which to calculate the minimum and maximum.\n"
    "\n"
    "    .. note::\n"
    "        Instead of one `iterable` it is also possible to pass the values (at\n"
    "        least 2) as positional arguments.\n"
    "\n"
    "key : callable, optional\n"
    "    If not given then compare the values, otherwise compare ``key(item)``.\n"
    "\n"
    "default : any type, optional\n"
    "    If not given raise ``ValueError`` if the `iterable` is empty otherwise\n"
    "    return ``(default, default)``\n"
    "\n"
    "Returns\n"
    "-------\n"
    "minimum : any type\n"
    "    The `minimum` of the `iterable`.\n"
    "\n"
    "maximum : any type\n"
    "    The `maximum` of the `iterable`.\n"
    "\n"
    "Raises\n"
    "------\n"
    "ValueError\n"
    "    If `iterable` is empty and no `default` is given.\n"
    "\n"
    "See also\n"
    "--------\n"
    "min : Calculate the minimum of an iterable.\n"
    "\n"
    "max : Calculate the maximum of an iterable.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "This function calculates the minimum (:py:func:`min`) and maximum\n"
    "(:py:func:`max`) of an `iterable`::\n"
    "\n"
    "    >>> from iteration_utilities import minmax\n"
    "    >>> minmax([2,1,3,5,4])\n"
    "    (1, 5)\n"
    "\n"
    "or pass in the values as arguments::\n"
    "\n"
    "    >>> minmax(2, 1, -1, 5, 4)\n"
    "    (-1, 5)\n"
    "\n"
    "If the iterable is empty `default` is returned::\n"
    "\n"
    "    >>> minmax([], default=0)\n"
    "    (0, 0)\n"
    "\n"
    "Like the builtin functions it also supports a `key` argument::\n"
    "\n"
    "    >>> import operator\n"
    "    >>> seq = [(3, 2), (5, 1), (10, 3), (8, 5), (3, 4)]\n"
    "    >>> minmax(seq, key=operator.itemgetter(1))\n"
    "    ((5, 1), (8, 5))\n"
    "\n"
    "References\n"
    "----------\n"
    ".. [0] http://code.activestate.com/recipes/577916/\n"
);

PyDoc_STRVAR(nth_doc,
    "nth(x)\n"
    "--\n\n"
    "Class that returns the `n`-th found value.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "n : :py:class:`int`\n"
    "    The index of the wanted item. If negative the last item is searched.\n"
    "    \n"
    "    .. note::\n"
    "       This is the only parameter for ``__init__``. The following parameters\n"
    "       have to be specified when calling the instance.\n"
    "\n"
    "iterable : iterable\n"
    "    The `iterable` for which to determine the nth value.\n"
    "\n"
    "default : any type, optional\n"
    "    If no nth value is found and `default` is given the `default` is \n"
    "    returned.\n"
    "\n"
    "pred : callable, optional\n"
    "    If given return the nth item for which ``pred(item)`` is ``True``.\n"
    "    \n"
    "    .. note::\n"
    "       ``pred=None`` is equivalent to ``pred=bool``.\n"
    "\n"
    "truthy : :py:class:`bool`, optional\n"
    "    If ``False`` search for the nth item for which ``pred(item)`` is ``False``.\n"
    "    Default is ``True``.\n"
    "\n"
    "    .. note::\n"
    "       Parameter is ignored if `pred` is not given.\n"
    "\n"
    "retpred : :py:class:`bool`, optional\n"
    "    If given return ``pred(item)`` instead of ``item``.\n"
    "    Default is ``False``.\n"
    "\n"
    "    .. note::\n"
    "       Parameter is ignored if `pred` is not given.\n"
    "\n"
    "retidx : :py:class:`bool`, optional\n"
    "    If given return the index of the `n`-th element instead of the value.\n"
    "    Default is ``False``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "nth : any type\n"
    "    The last value or the nth value for which `pred` is ``True``.\n"
    "    If there is no such value then `default` is returned.\n"
    "\n"
    "Raises\n"
    "-------\n"
    "TypeError :\n"
    "    If there is no nth element and no `default` is given.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Some basic examples including the use of ``pred``::\n"
    "\n"
    "    >>> from iteration_utilities import nth\n"
    "    >>> # First item\n"
    "    >>> nth(0)([0, 1, 2])\n"
    "    0\n"
    "    >>> # Second item\n"
    "    >>> nth(1)([0, 1, 2])\n"
    "    1\n"
    "    >>> # Last item\n"
    "    >>> nth(-1)([0, 1, 2])\n"
    "    2\n"
    "    \n"
    "    >>> nth(1)([0, 10, '', tuple(), 20], pred=bool)\n"
    "    20\n"
    "    \n"
    "    >>> # second odd number\n"
    "    >>> nth(1)([0, 2, 3, 5, 8, 9, 10], pred=lambda x: x%2)\n"
    "    5\n"
    "    \n"
    "    >>> # default value if empty or no true value\n"
    "    >>> nth(0)([], default=100)\n"
    "    100\n"
    "    >>> nth(-1)([0, 10, 0, 0], pred=bool, default=100)\n"
    "    10\n"
    "\n"
    "Given a `pred` it is also possible to look for the nth ``False`` value and \n"
    "return the result of ``pred(item)``::\n"
    "\n"
    "    >>> nth(1)([1,2,0], pred=bool)\n"
    "    2\n"
    "    >>> nth(-1)([1,0,2,0], pred=bool, truthy=False)\n"
    "    0\n"
    "    >>> import operator\n"
    "    >>> nth(-1)([[0,3], [0,1], [0,2]], pred=operator.itemgetter(1))\n"
    "    [0, 2]\n"
    "    >>> nth(-1)([[0,3], [0,1], [0,2]], pred=operator.itemgetter(1), retpred=True)\n"
    "    2\n"
    "\n"
    "There are already three predefined instances:\n"
    "\n"
    "- :py:func:`~iteration_utilities.first`: equivalent to ``nth(0)``.\n"
    "- :py:func:`~iteration_utilities.second`: equivalent to ``nth(1)``.\n"
    "- :py:func:`~iteration_utilities.third`: equivalent to ``nth(2)``.\n"
    "- :py:func:`~iteration_utilities.last`: equivalent to ``nth(-1)``.\n"
);

PyDoc_STRVAR(PyIU_One_doc,
    "one(iterable, /)\n"
    "--\n\n"
    "Return the first value in the `iterable` and expects it only contains one element.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    The `iterable` from which to get the one item.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "one : any type\n"
    "    The first value.\n"
    "\n"
    "Raises\n"
    "-------\n"
    "ValueError :\n"
    "    If the `iterable` contains no items or more than one item.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Some basic examples::\n"
    "\n"
    "    >>> from iteration_utilities import one\n"
    "    >>> one([0])\n"
    "    0\n"
    "    >>> one('b')\n"
    "    'b'\n"
    "\n"
    ".. warning::\n"
    "    :py:func:`~iteration_utilities.one` will access the first two values of \n"
    "    the `iterable` so it shoul only be used if the `iterable` must only \n"
    "    contain one item!\n"
);

PyDoc_STRVAR(packed_doc,
    "packed(func, /)\n"
    "--\n\n"
    "Class that always returns ``func(*x)`` when called with ``packed(func)(x)``.\n"
    "\n"
    ".. versionadded:: 0.3\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "func : callable\n"
    "    The function that should be called when the packed-instance is called.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Creating :py:class:`~iteration_utilities.packed` instances::\n"
    "\n"
    "    >>> from iteration_utilities import packed\n"
    "    >>> from operator import eq\n"
    "    >>> five = packed(eq)\n"
    "    >>> five((2, 2))\n"
    "    True\n"
    "\n"
    "This is a convenience class that emulates the behaviour of \n"
    ":py:func:`itertools.starmap` (compared to :py:func:`map`)::\n"
    "\n"
    "    >>> from itertools import starmap\n"
    "    >>> list(map(packed(eq), [(2, 2), (3, 3), (2, 3)]))\n"
    "    [True, True, False]\n"
    "    >>> list(starmap(eq, [(2, 2), (3, 3), (2, 3)]))\n"
    "    [True, True, False]\n"
    "\n"
    "and :py:func:`~iteration_utilities.starfilter` (compared to \n"
    ":py:func:`filter`)::\n"
    "\n"
    "    >>> from iteration_utilities import starfilter\n"
    "    >>> list(filter(packed(eq), [(2, 2), (3, 3), (2, 3)]))\n"
    "    [(2, 2), (3, 3)]\n"
    "    >>> list(starfilter(eq, [(2, 2), (3, 3), (2, 3)]))\n"
    "    [(2, 2), (3, 3)]\n"
    "\n"
    "Of course in these cases the appropriate `star`-function can be used but \n"
    "in case a function does not have such a convenience function already \n"
    ":py:class:`~iteration_utilities.packed` can be used.\n"
);

PyDoc_STRVAR(partial_doc,
    "partial(func, *args, **kwargs)\n"
    "--\n\n"
    "Like :py:func:`functools.partial` but supporting placeholders.\n"
    "\n"
    ".. versionadded:: 0.4.0\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "\n"
    "func : callable\n"
    "    The function to partially wrap.\n"
    "\n"
    "args : any type\n"
    "    The positional arguments for `func`.\n"
    "    \n"
    "    .. note::\n"
    "       Using :py:attr:`.partial._` as one or multiple positional arguments \n"
    "       will be interpreted as placeholder that need to be filled when the \n"
    "       :py:class:`~iteration_utilities.partial` instance is called.\n"
    "\n"
    "kwargs : any type\n"
    "    The keyword arguments for `func`.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "\n"
    "partial : callable\n"
    "    The `func` where the given positional arguments are fixed (or represented\n"
    "    as placeholders) and with optional keyword arguments.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "While placeholders can be used for the :py:attr:`args` they can't be used \n"
    "for the :py:attr:`keywords`.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "The :py:class:`iteration_utilities.partial` can be used as slightly slower\n"
    "drop-in replacement for :py:func:`functools.partial`. However it offers the\n"
    "possibility to pass in placeholders as positional arguments. This can be\n"
    "especially useful if a function does not allow keyword arguments::\n"
    "\n"
    "    >>> from iteration_utilities import partial\n"
    "    >>> isint = partial(isinstance, partial._, int)\n"
    "    >>> isint(10)\n"
    "    True\n"
    "    >>> isint(11.11)\n"
    "    False\n"
    "\n"
    "In this case the `isint` function is equivalent but faster than\n"
    "``lambda x: isinstance(x, int)``.\n"
    "The :py:attr:`.partial._` attribute or the \n"
    ":py:const:`~iteration_utilities.Placeholder`  or instances of \n"
    ":py:func:`~iteration_utilities.PlaceholderType` can be used as placeholders \n"
    "for the positional arguments.\n"
    "\n"
    "For example most iterators in :py:mod:`iteration_utilities` take the `iterable` \n"
    "as the first argument so other arguments can be easily added::\n"
    "\n"
    "    >>> from iteration_utilities import accumulate, Placeholder\n"
    "    >>> from operator import mul\n"
    "    >>> cumprod = partial(accumulate, Placeholder, mul)\n"
    "    >>> list(cumprod([1,2,3,4,5]))\n"
    "    [1, 2, 6, 24, 120]\n"
);

PyDoc_STRVAR(PyIU_Partition_doc,
    "partition(iterable, pred=None)\n"
    "--\n\n"
    "Use a predicate to partition entries into ``False`` entries and ``True``\n"
    "entries.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    `Iterable` to partition.\n"
    "\n"
    "pred : callable or None, optional\n"
    "    The predicate which determines the partition.\n"
    "    Default is ``None``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "false_values : list\n"
    "    An list containing the values for which the `pred` was False.\n"
    "\n"
    "true_values : list\n"
    "    An list containing the values for which the `pred` was True.\n"
    "\n"
    "See also\n"
    "--------\n"
    ".ipartition : Generator variant of :py:func:`~iteration_utilities.partition`.\n"
    "\n"
    "Examples\n"
    "--------\n"
    ">>> from iteration_utilities import partition\n"
    ">>> def is_odd(val): return val % 2\n"
    ">>> partition(range(10), is_odd)\n"
    "([0, 2, 4, 6, 8], [1, 3, 5, 7, 9])\n"
    "\n"
    ".. warning::\n"
    "    In case the `pred` is expensive then \n"
    "    :py:func:`~iteration_utilities.partition` can be noticable\n"
    "    faster than :py:func:`~iteration_utilities.ipartition`.\n"
);

PyDoc_STRVAR(placeholder_doc,
    "PlaceholderType(/)\n"
    "--\n\n"
    "A placeholder for :py:func:`iteration_utilities.partial`. It defines the\n"
    "class for :attr:`iteration_utilities.partial._` and \n"
    ":py:const:`iteration_utilities.Placeholder`.\n"
);

PyDoc_STRVAR(replicate_doc,
    "replicate(iterable, times)\n"
    "--\n\n"
    "Replicates each item in the `iterable` for `times` times.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    The iterable which contains the elements to be replicated.\n"
    "\n"
    "times : positive :py:class:`int`\n"
    "    The number of `times` each element is replicated.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "repeated_iterable : generator\n"
    "    A generator containing the replicated items from `iterable`.\n"
    "\n"
    "Examples\n"
    "--------\n"
    ">>> from iteration_utilities import replicate\n"
    ">>> ''.join(replicate('abc', 3))\n"
    "'aaabbbccc'\n"
    "\n"
    ">>> list(replicate(range(3), 5))\n"
    "[0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2]\n"
);

PyDoc_STRVAR(roundrobin_doc,
    "roundrobin(*iterables)\n"
    "--\n\n"
    "Round-Robin implementation ([0]_).\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterables : iterable\n"
    "    `Iterables` to combine using the round-robin. Any amount of iterables\n"
    "    are supported.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "roundrobin : generator\n"
    "    Iterable filled with the values of the `iterables`.\n"
    "\n"
    "Examples\n"
    "--------\n"
    ">>> from iteration_utilities import roundrobin\n"
    ">>> list(roundrobin('ABC', 'D', 'EF'))\n"
    "['A', 'D', 'E', 'B', 'F', 'C']\n"
    "\n"
    "References\n"
    "----------\n"
    ".. [0] https://en.wikipedia.org/wiki/Round-robin_scheduling\n"
);

PyDoc_STRVAR(sideeffects_doc,
    "sideeffects(iterable, func, times=0)\n"
    "--\n\n"
    "Does a normal iteration over `iterable` and only uses `func` each `times` \n"
    "items for it's side effects.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    `Iterable` containing the elements.\n"
    "\n"
    "func : callable\n"
    "    Function that is called for the side effects.\n"
    "\n"
    "times : :py:class:`int`, optional\n"
    "    Call the function each `times` items with the last `times` items. \n"
    "    If ``0`` the argument for `func` will be the item itself. For any \n"
    "    number greater than zero the argument will be a tuple.\n"
    "    Default is ``0``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "iterator : generator\n"
    "    A normal iterator over `iterable`.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "A simple example::\n"
    "\n"
    "    >>> from iteration_utilities import sideeffects\n"
    "    >>> def printit(val):\n"
    "    ...     print(val)\n"
    "    >>> list(sideeffects([1,2,3,4], printit))  # in python3 one could use print directly\n"
    "    1\n"
    "    2\n"
    "    3\n"
    "    4\n"
    "    [1, 2, 3, 4]\n"
    "    >>> list(sideeffects([1,2,3,4,5], printit, 2))\n"
    "    (1, 2)\n"
    "    (3, 4)\n"
    "    (5,)\n"
    "    [1, 2, 3, 4, 5]\n"
);

PyDoc_STRVAR(split_doc,
    "split(iterable, key, maxsplit=-1, keep=False, keep_before=False, keep_after=False, eq=False)\n"
    "--\n\n"
    "Splits an `iterable` by a `key` function or delimiter.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    The `iterable` to split.\n"
    "\n"
    "key : callable\n"
    "    The function by which to split the `iterable` (split where\n"
    "    ``key(item) == True``).\n"
    "\n"
    "maxsplit : :py:class:`int`, optional\n"
    "    The number of maximal splits. If ``maxsplit=-1`` then there is no limit.\n"
    "    Default is ``-1``.\n"
    "\n"
    "keep : :py:class:`bool`\n"
    "    If ``True`` also include the items where ``key(item)=True`` as seperate list.\n"
    "    Default is ``False``.\n"
    "\n"
    "keep_before : :py:class:`bool`\n"
    "    If ``True`` also include the items where ``key(item)=True`` in the \n"
    "    list before splitting.\n"
    "    Default is ``False``.\n"
    "\n"
    "keep_after : :py:class:`bool`\n"
    "    If ``True`` also include the items where ``key(item)=True`` as first \n"
    "    item in the list after splitting.\n"
    "    Default is ``False``.\n"
    "\n"
    "eq : :py:class:`bool`\n"
    "    If ``True`` split the `iterable` where ``key == item`` instead of\n"
    "    ``key(item) == True``. This can significantly speed up the function if a\n"
    "    single delimiter is used.\n"
    "    Default is ``False``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "splitted_iterable : generator\n"
    "    Generator containing the splitted `iterable` (lists).\n"
    "\n"
    "Raises\n"
    "-------\n"
    "TypeError\n"
    "    If ``maxsplit`` is smaller than ``-2``. If more than one of the ``keep``\n"
    "    arguments is ``True``.\n"
    "\n"
    "Examples\n"
    "--------\n"
    ">>> from iteration_utilities import split\n"
    ">>> list(split(range(1, 10), lambda x: x%3==0))\n"
    "[[1, 2], [4, 5], [7, 8]]\n"
    "\n"
    ">>> list(split(range(1, 10), lambda x: x%3==0, keep=True))\n"
    "[[1, 2], [3], [4, 5], [6], [7, 8], [9]]\n"
    "\n"
    ">>> list(split(range(1, 10), lambda x: x%3==0, keep_before=True))\n"
    "[[1, 2, 3], [4, 5, 6], [7, 8, 9]]\n"
    "\n"
    ">>> list(split(range(1, 10), lambda x: x%3==0, keep_after=True))\n"
    "[[1, 2], [3, 4, 5], [6, 7, 8], [9]]\n"
    "\n"
    ">>> list(split(range(1, 10), lambda x: x%3==0, maxsplit=1))\n"
    "[[1, 2], [4, 5, 6, 7, 8, 9]]\n"
    "\n"
    ">>> list(split([1,2,3,4,5,3,7,8,3], 3, eq=True))\n"
    "[[1, 2], [4, 5], [7, 8]]\n"
);

PyDoc_STRVAR(starfilter_doc,
    "starfilter(pred, iterable)\n"
    "--\n\n"
    "Like :py:func:`filter` but unpacks the current item in `iterable` when \n"
    "calling `pred`. This is similar to the difference between :py:func:`map` and \n"
    ":py:func:`itertools.starmap`.\n"
    "\n"
    ".. versionadded:: 0.3\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "pred : callable\n"
    "    The predicate function that is called to determine if the items should\n"
    "    be kept.\n"
    "\n"
    "    .. note::\n"
    "       Unlike :py:func:`filter` the `pred` cannot be ``None``.\n"
    "\n"
    "iterable : iterable\n"
    "    `Iterable` containing the elements.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "iterator : generator\n"
    "    A normal iterator over `iterable` containing only the items where \n"
    "    ``pred(*item)`` is ``True``.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "This is identical to ``filter(lambda x: pred(*x), iterable)`` but faster.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "A simple example::\n"
    "\n"
    "    >>> from iteration_utilities import starfilter\n"
    "    >>> from operator import eq\n"
    "    >>> list(starfilter(eq, zip([1,2,3], [2,2,2])))\n"
    "    [(2, 2)]\n"
    "\n"
    "See also\n"
    "--------\n"
    "filter\n"
    "iteration_utilities.packed\n"
);

PyDoc_STRVAR(successive_doc,
    "successive(iterable, times=2)\n"
    "--\n\n"
    "Like the recipe for pairwise but allows to get an arbitary number\n"
    "of successive elements.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    Get the successive elements from this `iterable`.\n"
    "\n"
    "times : :py:class:`int`, optional\n"
    "    The number of successive elements.\n"
    "    Default is ``2``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "successive_elements : generator\n"
    "    The successive elements as generator. Each element of the generator\n"
    "    is a tuple containing `times` successive elements.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Each item of the `iterable` is returned as ``tuple`` with `times` successive\n"
    "items::\n"
    "\n"
    "    >>> from iteration_utilities import successive\n"
    "    >>> list(successive(range(5)))\n"
    "    [(0, 1), (1, 2), (2, 3), (3, 4)]\n"
    "\n"
    "Varying the `times` can give you also 3 successive elements::\n"
    "\n"
    "    >>> list(successive(range(5), times=3))\n"
    "    [(0, 1, 2), (1, 2, 3), (2, 3, 4)]\n"
    "    >>> list(successive('Hello!', times=2))\n"
    "    [('H', 'e'), ('e', 'l'), ('l', 'l'), ('l', 'o'), ('o', '!')]\n"
);

PyDoc_STRVAR(tabulate_doc,
    "tabulate(func, start=0)\n"
    "--\n\n"
    "Return ``function(0)``, ``function(1)``, ...\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "func : callable\n"
    "    The `function` to apply.\n"
    "\n"
    "start : any type, optional\n"
    "    The starting value to apply the `function` on. Each time `tabulate` is\n"
    "    called this value will be incremented by one.\n"
    "    Default is ``0``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "tabulated : generator\n"
    "    An infinite generator containing the results of the `function` applied\n"
    "    on the values beginning by `start`.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Since the return is an infinite generator you need some other function\n"
    "to extract only the needed values. For example\n"
    ":py:func:`~iteration_utilities.getitem`::\n"
    "\n"
    "    >>> from iteration_utilities import tabulate, getitem\n"
    "    >>> from math import sqrt\n"
    "    >>> t = tabulate(sqrt, 0)\n"
    "    >>> list(getitem(t, stop=3))\n"
    "    [0.0, 1.0, 1.4142135623730951]\n"
    "\n"
    ".. warning::\n"
    "    This will return an infinitly long generator so do **not** try to do\n"
    "    something like ``list(tabulate())``!\n"
    "\n"
    "This is equivalent to:\n"
    "\n"
    ".. code::\n"
    "\n"
    "    import itertools\n"
    "    \n"
    "    def tabulate(function, start=0)\n"
    "        return map(function, itertools.count(start))\n"
);

PyDoc_STRVAR(uniqueever_doc,
    "unique_everseen(iterable, key=None)\n"
    "--\n\n"
    "Find unique elements, preserving their order. Remembers all elements ever seen.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    `Iterable` containing the elements.\n"
    "\n"
    "key : callable, optional\n"
    "    If given it must be a callable taking one argument and this\n"
    "    callable is applied to the value before checking if it was seen yet.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "iterable : generator\n"
    "    An iterable containing all unique values ever seen in the `iterable`.\n"
    "\n"
    "Notes\n"
    "-----\n"
    "The items in the `iterable` should implement equality.\n"
    "\n"
    "If the items are hashable the function is much faster.\n"
    "\n"
    "Examples\n"
    "--------\n"
    "Some simple examples::\n"
    "\n"
    "    >>> from iteration_utilities import unique_everseen, consume\n"
    "    >>> list(unique_everseen('AAAABBBCCDAABBB'))\n"
    "    ['A', 'B', 'C', 'D']\n"
    "    \n"
    "    >>> list(unique_everseen('ABBCcAD', str.lower))\n"
    "    ['A', 'B', 'C', 'D']\n"
    "    \n"
    "Even unhashable values can be processed, like `list`::\n"
    "\n"
    "    >>> list(unique_everseen([[1, 2], [1, 1], [1, 2]]))\n"
    "    [[1, 2], [1, 1]]\n"
    "    \n"
    "However using ``key=tuple`` (to make them hashable) is faster::\n"
    "\n"
    "    >>> list(unique_everseen([[1, 2], [1, 1], [1, 2]], key=tuple))\n"
    "    [[1, 2], [1, 1]]\n"
    "    \n"
    "One can access the already seen values by accessing the `seen` attribute.\n"
);

PyDoc_STRVAR(uniquejust_doc,
    "unique_justseen(iterable, key=None)\n"
    "--\n\n"
    "List unique elements, preserving order. Remember only the element just seen.\n"
    "\n"
    "Parameters\n"
    "----------\n"
    "iterable : iterable\n"
    "    `Iterable` to check.\n"
    "\n"
    "key : callable or None, optional\n"
    "    If ``None`` the values are taken as they are. If it's a callable the\n"
    "    callable is applied to the value before comparing it.\n"
    "    Default is ``None``.\n"
    "\n"
    "Returns\n"
    "-------\n"
    "iterable : generator\n"
    "    An iterable containing all unique values just seen in the `iterable`.\n"
    "\n"
    "Examples\n"
    "--------\n"
    ">>> from iteration_utilities import unique_justseen\n"
    ">>> list(unique_justseen('AAAABBBCCDAABBB'))\n"
    "['A', 'B', 'C', 'D', 'A', 'B']\n"
    "\n"
    ">>> list(unique_justseen('ABBCcAD', str.lower))\n"
    "['A', 'B', 'C', 'A', 'D']\n"
);
