PyoIterator

class PyoIterator[T](PyoIterable[T], Iterator[T]):
    """Base trait for lazy `Iterator` classes.

    Pyochain's `Iter[T]` implements this trait.
    This trait extends `PyoIterable[T]` and `collections.abc.Iterator[T]`, providing
    additional methods for working with lazy sequences.
    """

    __slots__ = ()

    def nth(self, n: int) -> Option[T]:
        """Return the nth item of the `Iterable` at the specified *n*.

        This is similar to `__getitem__` but for lazy `Iterators`.

        If *n* is out of bounds, returns `NONE`.

        Args:
            n (int): The index of the item to retrieve.

        Returns:
            Option[T]: `Some(item)` at the specified *n*.

        ```python
        >>> import pyochain as pc
        >>> pc.Iter([10, 20]).nth(1)
        Some(20)
        >>> pc.Iter([10, 20]).nth(3)
        NONE

        ```
        """
        try:
            return Some(next(itertools.islice(self.__iter__(), n, n + 1)))
        except StopIteration:
            return NONE

    def eq(self, other: Iterable[T]) -> bool:
        """Check if two `Iterable`s are equal based on their data.

        Note:
            This will consume any `Iterator` instances involved in the comparison (**self** and/or **other**).

        Args:
            other (Iterable[T]): Another instance of `Iterable[T]` to compare against.

        Returns:
            bool: `True` if the underlying data are equal, `False` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1,2,3)).eq(pc.Iter((1,2,3)))
        True
        >>> pc.Iter((1,2,3)).eq(pc.Seq([1,2]))
        False
        >>> pc.Iter((1,2,3)).eq(pc.Iter((1,2)))
        False
        >>> pc.Iter((1,2,3)).eq(pc.Vec([1,2,3]))
        True

        ```
        """
        return tls.eq(self.__iter__(), other)

    def ne(self, other: Iterable[T]) -> bool:
        """Check if this `Iterator` and *other* are not equal based on their data.

        Args:
            other (Iterable[T]): Another instance of `Iterable[T]` to compare against.

        Returns:
            bool: `True` if the underlying data are not equal, `False` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1,2,3)).ne(pc.Iter((1,2,3)))
        False
        >>> pc.Iter((1,2,3)).ne(pc.Seq([1,2]))
        True
        >>> pc.Iter((1,2,3)).ne(pc.Iter((1,2)))
        True
        >>> pc.Iter((1,2,3)).ne(pc.Vec([1,2,3]))
        False

        ```
        """
        return tls.ne(self.__iter__(), other)

    def le(self, other: Iterable[T]) -> bool:
        """Check if this `Iterator` is less than or equal to *other* based on their data.

        Args:
            other (Iterable[T]): Another instance of `Iterable[T]` to compare against.

        Returns:
            bool: `True` if the underlying data of self is less than or equal to that of other, `False` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1,2)).le(pc.Seq((1,2,3)))
        True
        >>> pc.Iter((1,2,3)).le(pc.Seq((1,2)))
        False

        ```
        """
        return tls.le(self.__iter__(), other)

    def lt(self, other: Iterable[T]) -> bool:
        """Check if this `Iterator` is less than *other* based on their data.

        Args:
            other (Iterable[T]): Another `Iterable[T]` to compare against.

        Returns:
            bool: `True` if the underlying data of self is less than that of other, `False` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1,2)).lt(pc.Seq((1,2,3)))
        True
        >>> pc.Iter((1,2,3)).lt(pc.Seq((1,2)))
        False

        ```
        """
        return tls.lt(self.__iter__(), other)

    def gt(self, other: Iterable[T]) -> bool:
        """Check if this `Iterator` is greater than *other* based on their data.

        Args:
            other (Iterable[T]): Another `Iterable[T]` to compare against.

        Returns:
            bool: `True` if the underlying data of **self** is greater than that of **other**, `False` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1,2,3)).gt((1,2))
        True
        >>> pc.Iter((1,2)).gt((1,2,3))
        False

        ```
        """
        return tls.gt(self.__iter__(), other)

    def ge(self, other: Iterable[T]) -> bool:
        """Check if this `Iterator` is greater than or equal to *other* based on their data.

        Args:
            other (Iterable[T]): Another `Iterable[T]` to compare against.

        Returns:
            bool: `True` if the underlying data of **self** is greater than or equal to that of **other**, `False` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1,2,3)).ge((1,2))
        True
        >>> pc.Iter((1,2)).ge((1,2,3))
        False

        ```
        """
        return tls.ge(self.__iter__(), other)

    def next(self) -> Option[T]:
        """Return the next element in the `Iterator`.

        Note:
            The actual `.__next__()` method must be conform to the Python `Iterator` Protocol, and is what will be actually called if you iterate over the `PyoIterator` instance.

            `PyoIterator.next()` is a convenience method that wraps the result in an `Option` to handle exhaustion gracefully, for custom use cases.

        Returns:
            Option[T]: The next element in the iterator. `Some[T]`, or `NONE` if the iterator is exhausted.

        Example:
        ```python
        >>> import pyochain as pc
        >>> it = pc.Seq([1, 2, 3]).iter()
        >>> it.next().unwrap()
        1
        >>> it.next().unwrap()
        2

        ```
        """
        return Option(next(self, None))

    def reduce(self, func: Callable[[T, T], T]) -> T:
        """Apply a function of two arguments cumulatively to the items of an iterable, from left to right.

        Args:
            func (Callable[[T, T], T]): Function to apply cumulatively to the items of the iterable.

        Returns:
            T: Single value resulting from cumulative reduction.

        This effectively reduces the `Iterator` to a single value.

        If initial is present, it is placed before the items of the `Iterator` in the calculation.

        It then serves as a default when the `Iterator` is empty.
        ```python
        >>> import pyochain as pc
        >>> pc.Iter([1, 2, 3]).reduce(lambda a, b: a + b)
        6

        ```
        """
        return functools.reduce(func, self)

    def fold[B](self, init: B, func: Callable[[B, T], B]) -> B:
        """Fold every element of the `Iterator` into an accumulator by applying an operation, returning the final result.

        Args:
            init (B): Initial value for the accumulator.
            func (Callable[[B, T], B]): Function that takes the accumulator and current element,
                returning the new accumulator value.

        Returns:
            B: The final accumulated value.

        Note:
            This is similar to `reduce()` but with an initial value, making it equivalent to
            Python `functools.reduce()` with an initializer.

        ```python
        >>> import pyochain as pc
        >>> pc.Iter([1, 2, 3]).fold(0, lambda acc, x: acc + x)
        6
        >>> pc.Iter([1, 2, 3]).fold(10, lambda acc, x: acc + x)
        16
        >>> pc.Iter(['a', 'b', 'c']).fold('', lambda acc, x: acc + x)
        'abc'

        ```
        """
        return functools.reduce(func, self, init)

    def find(self, predicate: Callable[[T], bool]) -> Option[T]:
        """Searches for an element of an iterator that satisfies a `predicate`.

        Takes a closure that returns true or false as `predicate`, and applies it to each element of the iterator.

        Args:
            predicate (Callable[[T], bool]): Function to evaluate each item.

        Returns:
            Option[T]: The first element satisfying the predicate. `Some(value)` if found, `NONE` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> def gt_five(x: int) -> bool:
        ...     return x > 5
        >>>
        >>> def gt_nine(x: int) -> bool:
        ...     return x > 9
        >>>
        >>> pc.Iter(range(10)).find(predicate=gt_five)
        Some(6)
        >>> pc.Iter(range(10)).find(predicate=gt_nine).unwrap_or("missing")
        'missing'

        ```
        """
        return Option(next(filter(predicate, self), None))

    def try_find[E](
        self, predicate: Callable[[T], Result[bool, E]]
    ) -> Result[Option[T], E]:
        """Applies a function returning `Result[bool, E]` to find first matching element.

        Short-circuits: stops at the first successful `True` or on the first error.

        Args:
            predicate (Callable[[T], Result[bool, E]]): Function returning a `Result[bool, E]`.

        Returns:
            Result[Option[T], E]: The first matching element, or the first error.

        Example:
        ```python
        >>> import pyochain as pc
        >>> def is_even(x: int) -> pc.Result[bool, str]:
        ...     return pc.Ok(x % 2 == 0) if x >= 0 else pc.Err("negative number")
        >>>
        >>> pc.Iter(range(1, 6)).try_find(is_even)
        Ok(Some(2))

        ```
        """
        return tls.try_find(self.__iter__(), predicate)

    def try_fold[B, E](
        self, init: B, func: Callable[[B, T], Result[B, E]]
    ) -> Result[B, E]:
        """Folds every element into an accumulator, short-circuiting on error.

        Applies **func** cumulatively to items and the accumulator.

        If **func** returns an error, stops and returns that error.

        Args:
            init (B): Initial accumulator value.
            func (Callable[[B, T], Result[B, E]]): Function that takes the accumulator and element, returns a `Result[B, E]`.

        Returns:
            Result[B, E]: Final accumulator or the first error.

        Example:
        ```python
        >>> import pyochain as pc
        >>> def checked_add(acc: int, x: int) -> pc.Result[int, str]:
        ...     new_val = acc + x
        ...     if new_val > 100:
        ...         return pc.Err("overflow")
        ...     return pc.Ok(new_val)
        >>>
        >>> pc.Iter([1, 2, 3]).try_fold(0, checked_add)
        Ok(6)
        >>> pc.Iter([50, 40, 20]).try_fold(0, checked_add)
        Err('overflow')
        >>> pc.Iter([]).try_fold(0, checked_add)
        Ok(0)

        ```
        """
        return tls.try_fold(self.__iter__(), init, func)

    def try_reduce[E](
        self, func: Callable[[T, T], Result[T, E]]
    ) -> Result[Option[T], E]:
        """Reduces elements to a single one, short-circuiting on error.

        Uses the first element as the initial accumulator. If **func** returns an error, stops immediately.

        Args:
            func (Callable[[T, T], Result[T, E]]): Function that reduces two items, returns a `Result[T, E]`.

        Returns:
            Result[Option[T], E]: Final accumulated value or the first error. Returns `Ok(NONE)` for empty iterable.

        Example:
        ```python
        >>> import pyochain as pc
        >>> def checked_add(x: int, y: int) -> pc.Result[int, str]:
        ...     if x + y > 100:
        ...         return pc.Err("overflow")
        ...     return pc.Ok(x + y)
        >>>
        >>> pc.Iter([1, 2, 3]).try_reduce(checked_add)
        Ok(Some(6))
        >>> pc.Iter([50, 60]).try_reduce(checked_add)
        Err('overflow')
        >>> pc.Iter([]).try_reduce(checked_add)
        Ok(NONE)

        ```
        """
        return tls.try_reduce(self.__iter__(), func)

    def is_sorted[U: SupportsComparison[Any]](
        self: PyoIterator[U], *, reverse: bool = False, strict: bool = False
    ) -> bool:
        """Returns `True` if the items of the `Iterator` are in sorted order.

        The elements of the `Iterator` must support comparison operations.

        The function returns `False` after encountering the first out-of-order item.

        If there are no out-of-order items, the `Iterator` is exhausted.

        Credits to **more-itertools** for the implementation.

        See Also:
            - `is_sorted_by()`: If your elements do not support comparison operations directly, or you want to sort based on a specific attribute or transformation.

        Args:
            reverse (bool): Whether to check for descending order.
            strict (bool): Whether to enforce strict sorting (no equal elements).

        Returns:
            bool: `True` if items are sorted according to the criteria, `False` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter([1, 2, 3, 4, 5]).is_sorted()
        True

        ```
        If strict, tests for strict sorting, that is, returns False if equal elements are found:
        ```python
        >>> pc.Iter([1, 2, 2]).is_sorted()
        True
        >>> pc.Iter([1, 2, 2]).is_sorted(strict=True)
        False

        ```

        """
        return tls.is_sorted(self.__iter__(), reverse=reverse, strict=strict)

    def is_sorted_by(
        self,
        key: Callable[[T], SupportsComparison[Any]],
        *,
        reverse: bool = False,
        strict: bool = False,
    ) -> bool:
        """Returns `True` if the items of the `Iterator` are in sorted order according to the key function.

        The function returns `False` after encountering the first out-of-order item.

        If there are no out-of-order items, the `Iterator` is exhausted.

        Credits to **more-itertools** for the implementation.

        Args:
            key (Callable[[T], SupportsComparison[Any]]): Function to extract a comparison key from each element.
            reverse (bool): Whether to check for descending order.
            strict (bool): Whether to enforce strict sorting (no equal elements).

        Returns:
            bool: `True` if items are sorted according to the criteria, `False` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter(["1", "2", "3", "4", "5"]).is_sorted_by(int)
        True
        >>> pc.Iter(["5", "4", "3", "1", "2"]).is_sorted_by(int, reverse=True)
        False

        ```
        If strict, tests for strict sorting, that is, returns False if equal elements are found:
        ```python
        >>> pc.Iter(["1", "2", "2"]).is_sorted_by(int)
        True
        >>> pc.Iter(["1", "2", "2"]).is_sorted_by(key=int, strict=True)
        False

        ```
        """
        return tls.is_sorted_by(self.__iter__(), key, reverse=reverse, strict=strict)

    def all_equal[U](self, key: Callable[[T], U] | None = None) -> bool:
        """Return `True` if all items of the `Iterator` are equal.

        A function that accepts a single argument and returns a transformed version of each input item can be specified with **key**.

        Credits to **more-itertools** for the implementation.

        Args:
            key (Callable[[T], U] | None): Function to transform items before comparison.

        Returns:
            bool: `True` if all items are equal, `False` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter("AaaA").all_equal(key=str.casefold)
        True
        >>> pc.Iter([1, 2, 3]).all_equal(key=lambda x: x < 10)
        True

        ```
        """
        iterator = itertools.groupby(self.__iter__(), key)
        for _first in iterator:
            for _second in iterator:
                return False
            return True
        return True

    def all_unique[U](self, key: Callable[[T], U] | None = None) -> bool:
        """Returns True if all the elements of iterable are unique.

        The function returns as soon as the first non-unique element is encountered.

        `Iters` with a mix of hashable and unhashable items can be used, but the function will be slower for unhashable items.

        A function that accepts a single argument and returns a transformed version of each input item can be specified with **key**.

        Credits to **more-itertools** for the implementation.

        Args:
            key (Callable[[T], U] | None): Function to transform items before comparison.

        Returns:
            bool: `True` if all elements are unique, `False` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter("ABCB").all_unique()
        False
        >>> pc.Iter("ABCb").all_unique()
        True
        >>> pc.Iter("ABCb").all_unique(str.lower)
        False

        ```
        """
        seenset: set[T | U] = set()
        seenset_add = seenset.add
        seenlist: list[T | U] = []
        seenlist_add = seenlist.append
        for element in map(key, self.__iter__()) if key else self.__iter__():
            try:
                if element in seenset:
                    return False
                seenset_add(element)
            except TypeError:
                if element in seenlist:
                    return False
                seenlist_add(element)
        return True

    def argmax[U](self, key: Callable[[T], U] | None = None) -> int:
        """Index of the first occurrence of a maximum value in the `Iterator`.

        A function that accepts a single argument and returns a transformed version of each input item can be specified with **key**.

        Credits to more-itertools for the implementation.

        Args:
            key (Callable[[T], U] | None): Optional function to determine the value for comparison.

        Returns:
            int: The index of the maximum value.

        ```python
        >>> import pyochain as pc
        >>> pc.Iter("abcdefghabcd").argmax()
        7
        >>> pc.Iter([0, 1, 2, 3, 3, 2, 1, 0]).argmax()
        3

        ```
        For example, identify the best machine learning model:
        ```python
        >>> models = pc.Seq(["svm", "random forest", "knn", "naïve bayes"])
        >>> accuracy = pc.Seq([68, 61, 84, 72])
        >>> # Most accurate model
        >>> models.get(accuracy.iter().argmax()).unwrap()
        'knn'
        >>>
        >>> # Best accuracy
        >>> accuracy.max()
        84

        ```
        """
        it = self.__iter__()
        if key is not None:
            it = map(key, it)
        return max(enumerate(it), key=itemgetter(1))[0]

    def argmin[U](self, key: Callable[[T], U] | None = None) -> int:
        """Index of the first occurrence of a minimum value in the `Iterator`.

        A function that accepts a single argument and returns a transformed version of each input item can be specified with **key**.

        Credits to more-itertools for the implementation.

        Args:
            key (Callable[[T], U] | None): Optional function to determine the value for comparison.

        Returns:
            int: The index of the minimum value.

        ```python
        >>> import pyochain as pc
        >>> # Example 1: Basic usage
        >>> pc.Iter("efghabcdijkl").argmin()
        4
        >>> pc.Iter([3, 2, 1, 0, 4, 2, 1, 0]).argmin()
        3
        >>> # Example 2: look up a label corresponding to the position of a value that minimizes a cost function
        >>> def cost(x: int) -> float:
        ...     "Days for a wound to heal given a subject's age."
        ...     return x**2 - 20 * x + 150
        >>>
        >>> labels = pc.Seq(["homer", "marge", "bart", "lisa", "maggie"])
        >>> ages = pc.Seq([35, 30, 10, 9, 1])
        >>> # Fastest healing family member
        >>> labels.get(ages.iter().argmin(key=cost)).unwrap()
        'bart'
        >>> # Age with fastest healing
        >>> ages.min_by(key=cost)
        10

        ```
        """
        it = self.__iter__()
        if key is not None:
            it = map(key, it)
        return min(enumerate(it), key=itemgetter(1))[0]

    def take_while(self, predicate: Callable[[T], bool]) -> Self:
        """Take items while predicate holds.

        Args:
            predicate (Callable[[T], bool]): Function to evaluate each item.

        Returns:
            Self: An `Iterator` of the items taken while the predicate is true.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1, 2, 0)).take_while(lambda x: x > 0).collect()
        Seq(1, 2)

        ```
        """
        return self.__class__(itertools.takewhile(predicate, self.__iter__()))

    def skip_while(self, predicate: Callable[[T], bool]) -> Self:
        """Drop items while predicate holds.

        Args:
            predicate (Callable[[T], bool]): Function to evaluate each item.

        Returns:
            Self: An `Iterator` of the items after skipping those for which the predicate is true.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1, 2, 0)).skip_while(lambda x: x > 0).collect()
        Seq(0,)

        ```
        """
        return self.__class__(itertools.dropwhile(predicate, self.__iter__()))

    def compress(self, *selectors: bool) -> Self:
        """Filter elements using a boolean selector iterable.

        Args:
            *selectors (bool): Boolean values indicating which elements to keep.

        Returns:
            Self: An `Iterator` of the items selected by the boolean selectors.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter("ABCDEF").compress(1, 0, 1, 0, 1, 1).collect()
        Seq('A', 'C', 'E', 'F')

        ```
        """
        return self.__class__(itertools.compress(self.__iter__(), selectors))

    def unique(self, key: Callable[[T], Any] | None = None) -> Self:
        """Return only unique elements of the iterable.

        Args:
            key (Callable[[T], Any] | None): Function to transform items before comparison.

        Returns:
            Self: An `Iterator` of the unique items.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter([1, 2, 3]).unique().collect()
        Seq(1, 2, 3)
        >>> pc.Iter([1, 2, 1, 3]).unique().collect()
        Seq(1, 2, 3)

        ```
        Uniqueness can be defined by key keyword
        ```python
        >>> pc.Iter(["cat", "mouse", "dog", "hen"]).unique(key=len).collect()
        Seq('cat', 'mouse')

        ```
        """
        return self.__class__(cz.itertoolz.unique(self.__iter__(), key=key))

    def take(self, n: int) -> Self:
        """Creates an iterator that yields the first n elements, or fewer if the underlying iterator ends sooner.

        `Iter.take(n)` yields elements until n elements are yielded or the end of the iterator is reached (whichever happens first).

        The returned iterator is either:

        - A prefix of length n if the original iterator contains at least n elements
        - All of the (fewer than n) elements of the original iterator if it contains fewer than n elements.

        Args:
            n (int): Number of elements to take.

        Returns:
            Self: An `Iterator` of the first n items.

        Example:
        ```python
        >>> import pyochain as pc
        >>> data = [1, 2, 3]
        >>> pc.Iter(data).take(2).collect()
        Seq(1, 2)
        >>> pc.Iter(data).take(5).collect()
        Seq(1, 2, 3)

        ```
        """
        return self.__class__(itertools.islice(self.__iter__(), n))

    def skip(self, n: int) -> Self:
        """Drop first n elements.

        Args:
            n (int): Number of elements to skip.

        Returns:
            Self: An `Iterator` of the items after skipping the first n items.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1, 2, 3)).skip(1).collect()
        Seq(2, 3)

        ```
        """
        return self.__class__(cz.itertoolz.drop(n, self.__iter__()))

    def step_by(self, step: int) -> Self:
        """Creates an `Iterator` starting at the same point, but stepping by the given **step** at each iteration.

        Note:
            The first element of the iterator will always be returned, regardless of the **step** given.

        Args:
            step (int): Step size for selecting items.

        Returns:
            Self: An `Iterator` of every nth item.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter([0, 1, 2, 3, 4, 5]).step_by(2).collect()
        Seq(0, 2, 4)

        ```
        """
        return self.__class__(cz.itertoolz.take_nth(step, self.__iter__()))

    def slice(
        self,
        start: int | None = None,
        stop: int | None = None,
        step: int | None = None,
    ) -> Self:
        """Return a slice of the `Iterator`.

        Args:
            start (int | None): Starting index of the slice.
            stop (int | None): Ending index of the slice.
            step (int | None): Step size for the slice.

        Returns:
            Self: An `Iterator` of the sliced items.

        Example:
        ```python
        >>> import pyochain as pc
        >>> data = (1, 2, 3, 4, 5)
        >>> pc.Iter(data).slice(1, 4).collect()
        Seq(2, 3, 4)
        >>> pc.Iter(data).slice(step=2).collect()
        Seq(1, 3, 5)

        ```
        """
        return self.__class__(itertools.islice(self.__iter__(), start, stop, step))

    def cycle(self) -> Self:
        """Repeat the `Iterator` indefinitely.

        Warning:
            This creates an infinite `Iterator`.

            Be sure to use `Iter.take()` or `Iter.slice()` to limit the number of items taken.

        See Also:
            `Iter.repeat()` to repeat *self* as elements (`Iter[Self]`).

        Returns:
            Self: A new `Iterator` that cycles through the elements indefinitely.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1, 2)).cycle().take(5).collect()
        Seq(1, 2, 1, 2, 1)

        ```
        """
        return self.__class__(itertools.cycle(self.__iter__()))

    def intersperse(self, element: T) -> Self:
        """Creates a new `Iterator` which places a copy of separator between adjacent items of the original iterator.

        Args:
            element (T): The element to interpose between items.

        Returns:
            Self: A new `Iterator` with the element interposed.

        Example:
        ```python
        >>> import pyochain as pc
        >>> # Simple example with numbers
        >>> pc.Iter([1, 2, 3]).intersperse(0).collect()
        Seq(1, 0, 2, 0, 3)
        >>> # Useful when chaining with other operations
        >>> pc.Iter([10, 20, 30]).intersperse(5).sum()
        70
        >>> # Inserting separators between groups, then flattening
        >>> pc.Iter([[1, 2], [3, 4], [5, 6]]).intersperse([-1]).flatten().collect()
        Seq(1, 2, -1, 3, 4, -1, 5, 6)

        ```
        """
        return self.__class__(cz.itertoolz.interpose(element, self.__iter__()))

    def random_sample(
        self, probability: float, state: Random | int | None = None
    ) -> Self:
        """Return elements from the `Iterator` with a given *probability*.

        `.random_sample()` considers each item independently and without replacement.

        See below how the first time it returned 13 items and the next time it returned 6 items.

        Args:
            probability (float): The probability of including each element.
            state (Random | int | None): Random state or seed for deterministic sampling.

        Returns:
            Self: A new `Iterator` with randomly sampled elements.
        ```python
        >>> import pyochain as pc
        >>> data = pc.Iter(range(100)).collect()
        >>> data.iter().random_sample(0.1).collect()  # doctest: +SKIP
        Seq(6, 9, 19, 35, 45, 50, 58, 62, 68, 72, 78, 86, 95)
        >>> data.iter().random_sample(0.1).collect()  # doctest: +SKIP
        Seq(6, 44, 54, 61, 69, 94)
        ```
        Providing an integer seed for random_state will result in deterministic sampling.

        Given the same seed it will return the same sample every time.
        ```python
        >>> data.iter().random_sample(0.1, state=2016).collect()
        Seq(7, 9, 19, 25, 30, 32, 34, 48, 59, 60, 81, 98)
        >>> data.iter().random_sample(0.1, state=2016).collect()
        Seq(7, 9, 19, 25, 30, 32, 34, 48, 59, 60, 81, 98)

        ```
        random_state can also be any object with a method random that returns floats between 0.0 and 1.0 (exclusive).
        ```python
        >>> from random import Random
        >>> randobj = Random(2016)
        >>> data.iter().random_sample(0.1, state=randobj).collect()
        Seq(7, 9, 19, 25, 30, 32, 34, 48, 59, 60, 81, 98)

        ```
        """
        return self.__class__(
            cz.itertoolz.random_sample(probability, self.__iter__(), random_state=state)
        )

    def insert(self, value: T) -> Self:
        """Prepend the *value* to the `Iterator`.

        Note:
            This can be considered the equivalent as `list.append()`, but for a lazy `Iterator`.
            However, append add the value at the **end**, while insert add it at the **beginning**.

        See Also:
            `Iter.chain()` to add multiple elements at the end of the `Iterator`.

        Args:
            value (T): The value to prepend.

        Returns:
            Self: A new Iterable wrapper with the value prepended.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((2, 3)).insert(1).collect()
        Seq(1, 2, 3)

        ```
        """
        return self.__class__(cz.itertoolz.cons(value, self.__iter__()))

    def interleave(self, *others: Iterable[T]) -> Self:
        """Interleave multiple sequences element-wise.

        Args:
            *others (Iterable[T]): Other iterables to interleave.

        Returns:
            Self: A new Iterable wrapper with interleaved elements.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1, 2)).interleave((3, 4)).collect()
        Seq(1, 3, 2, 4)

        ```
        """
        return self.__class__(cz.itertoolz.interleave((self.__iter__(), *others)))

    def chain(self, *others: Iterable[T]) -> Self:
        """Concatenate **self** with one or more `Iterables`, any of which may be infinite.

        In other words, it links **self** and **others** together, in a chain. 🔗

        An infinite `Iterable` will prevent the rest of the arguments from being included.

        This is equivalent to `list.extend()`, except it is fully lazy and works with any `Iterable`.

        See Also:
            `Iter.insert()` to add a single element at the beginning of the `Iterator`.

        Args:
            *others (Iterable[T]): Other iterables to concatenate.

        Returns:
            Self: A new `Iterator` which will first iterate over values from the original `Iterator` and then over values from the **others** `Iterable`s.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1, 2)).chain((3, 4), [5]).collect()
        Seq(1, 2, 3, 4, 5)
        >>> pc.Iter((1, 2)).chain(pc.Iter.from_count(3)).take(5).collect()
        Seq(1, 2, 3, 4, 5)

        ```
        """
        return self.__class__(cz.itertoolz.concat((self.__iter__(), *others)))

    def elements(self) -> Self:
        """Iterator over elements repeating each as many times as its count.

        Note:
            if an element's count has been set to zero or is a negative
            number, elements() will ignore it.

        Returns:
            Self: A new `Iterator` with elements repeated according to their counts.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter("ABCABC").elements().sort()
        Vec('A', 'A', 'B', 'B', 'C', 'C')

        ```
        Knuth's example for prime factors of 1836:  2**2 * 3**3 * 17**1
        ```python
        >>> import math
        >>> data = [2, 2, 3, 3, 3, 17]
        >>> pc.Iter(data).elements().into(math.prod)
        1836

        ```
        """
        from collections import Counter

        return self.__class__(Counter(self.__iter__()).elements())

    def accumulate(self, func: Callable[[T, T], T], initial: T | None = None) -> Self:
        """Return an `Iterator` of accumulated binary function results.

        In principle, `.accumulate()` is similar to `.fold()` if you provide it with the same binary function.

        However, instead of returning the final accumulated result, it returns an `Iterator` that yields the current value `T` of the accumulator for each iteration.

        In other words, the last element yielded by `.accumulate()` is what would have been returned by `.fold()` if it had been used instead.

        Args:
            func (Callable[[T, T], T]): A binary function to apply cumulatively.
            initial (T | None): Optional initial value to start the accumulation.

        Returns:
            Self: A new `Iterator` with accumulated results.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter((1, 2, 3)).accumulate(lambda a, b: a + b, 0).collect()
        Seq(0, 1, 3, 6)
        >>> # The final accumulated result is the same as fold:
        >>> pc.Iter((1,2,3)).fold(0, lambda a, b: a + b)
        6
        >>> pc.Iter((1, 2, 3)).accumulate(lambda a, b: a * b).collect()
        Seq(1, 2, 6)

        ```
        """
        return self.__class__(
            itertools.accumulate(self.__iter__(), func, initial=initial)
        )

    def for_each[**P](
        self,
        func: Callable[Concatenate[T, P], Any],
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> None:
        """Consume the `Iterator` by applying a function to each element in the `Iterable`.

        Is a terminal operation, and is useful for functions that have side effects,
        or when you want to force evaluation of a lazy iterable.

        Args:
            func (Callable[Concatenate[T, P], Any]): Function to apply to each element.
            *args (P.args): Positional arguments for the function.
            **kwargs (P.kwargs): Keyword arguments for the function.

        Returns:
            None: This is a terminal operation with no return value.


        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Seq([1, 2, 3]).iter().for_each(lambda x: print(x + 1))
        2
        3
        4

        ```
        """
        for v in self.__iter__():
            func(v, *args, **kwargs)

    @overload
    def for_each_star[R](
        self: PyoIterator[tuple[Any]],
        func: Callable[[Any], R],
    ) -> None: ...
    @overload
    def for_each_star[T1, T2, R](
        self: PyoIterator[tuple[T1, T2]],
        func: Callable[[T1, T2], R],
    ) -> None: ...
    @overload
    def for_each_star[T1, T2, T3, R](
        self: PyoIterator[tuple[T1, T2, T3]],
        func: Callable[[T1, T2, T3], R],
    ) -> None: ...
    @overload
    def for_each_star[T1, T2, T3, T4, R](
        self: PyoIterator[tuple[T1, T2, T3, T4]],
        func: Callable[[T1, T2, T3, T4], R],
    ) -> None: ...
    @overload
    def for_each_star[T1, T2, T3, T4, T5, R](
        self: PyoIterator[tuple[T1, T2, T3, T4, T5]],
        func: Callable[[T1, T2, T3, T4, T5], R],
    ) -> None: ...
    @overload
    def for_each_star[T1, T2, T3, T4, T5, T6, R](
        self: PyoIterator[tuple[T1, T2, T3, T4, T5, T6]],
        func: Callable[[T1, T2, T3, T4, T5, T6], R],
    ) -> None: ...
    @overload
    def for_each_star[T1, T2, T3, T4, T5, T6, T7, R](
        self: PyoIterator[tuple[T1, T2, T3, T4, T5, T6, T7]],
        func: Callable[[T1, T2, T3, T4, T5, T6, T7], R],
    ) -> None: ...
    @overload
    def for_each_star[T1, T2, T3, T4, T5, T6, T7, T8, R](
        self: PyoIterator[tuple[T1, T2, T3, T4, T5, T6, T7, T8]],
        func: Callable[[T1, T2, T3, T4, T5, T6, T7, T8], R],
    ) -> None: ...
    @overload
    def for_each_star[T1, T2, T3, T4, T5, T6, T7, T8, T9, R](
        self: PyoIterator[tuple[T1, T2, T3, T4, T5, T6, T7, T8, T9]],
        func: Callable[[T1, T2, T3, T4, T5, T6, T7, T8, T9], R],
    ) -> None: ...
    @overload
    def for_each_star[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, R](
        self: PyoIterator[tuple[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10]],
        func: Callable[[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10], R],
    ) -> None: ...
    def for_each_star[U: Iterable[Any], R](
        self: PyoIterator[U],
        func: Callable[..., R],
    ) -> None:
        """Consume the `Iterator` by applying a function to each unpacked item in the `Iterable` element.

        Is a terminal operation, and is useful for functions that have side effects,
        or when you want to force evaluation of a lazy iterable.

        Each item yielded by the `Iterator` is expected to be an `Iterable` itself (e.g., a tuple or list),
        and its elements are unpacked as arguments to the provided function.

        This is often used after methods like `zip()` or `enumerate()` that yield tuples.

        Args:
            func (Callable[..., R]): Function to apply to each unpacked element.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Iter([(1, 2), (3, 4)]).for_each_star(lambda x, y: print(x + y))
        3
        7

        ```
        """
        for item in self.__iter__():
            func(*item)

    def try_for_each[E](self, f: Callable[[T], Result[Any, E]]) -> Result[None, E]:
        """Applies a fallible function to each item in the `Iterator`, stopping at the first error and returning that error.

        This can also be thought of as the fallible form of `.for_each()`.

        Args:
            f (Callable[[T], Result[Any, E]]): A function that takes an item of type `T` and returns a `Result`.

        Returns:
            Result[None, E]: Returns `Ok(None)` if all applications of **f** were successful (i.e., returned `Ok`), or the first error `E` encountered.

        Example:
        ```python
        >>> import pyochain as pc
        >>> def validate_positive(n: int) -> pc.Result[None, str]:
        ...     if n > 0:
        ...         return pc.Ok(None)
        ...     return pc.Err(f"Value {n} is not positive")
        >>> pc.Iter([1, 2, 3, 4, 5]).try_for_each(validate_positive)
        Ok(None)
        >>> # Short-circuit on first error:
        >>> pc.Iter([1, 2, -1, 4]).try_for_each(validate_positive)
        Err('Value -1 is not positive')

        ```
        """
        for item in self.__iter__():
            res = f(item)
            if res.is_err():
                return res
        return Ok(None)