Iter

@final
class Iter[T](PyoIterator[T], ArgsWrapper[T]):
    """Concrete implementation for `abc::PyoIterator`.

    Can be instantiated from any `Iterable` (like lists, sets, generators, etc.) efficiently (it only calls the builtin `iter()` on the input).

    As such, creating an `Iter` from an `Iterator` is virtually free.

    Tip:
        `Iter::__iter__()` returns the underlying wrapped `Iterator`, hence native speed is kept.

        i.e `Iter(...).map(f).collect(list)` is as fast as `list(map(f, [...]))`.

    See Also:
        [`abc::PyoIterator`][PyoIterator]: The abstract base class that `Iter` implements.

    Example:
        ```python
        from pyochain import Iter, Seq

        data = (0, 1, 2, 3, 4)

        assert Iter(data).collect(Seq) == Seq(data)
        iterator = Iter(data)

        # First we have a tuple iterator
        assert iterator.__iter__().__class__.__name__ == "tuple_iterator"

        # Now we have a map object
        mapped = iterator.map(lambda x: x * 2)
        assert mapped.__iter__().__class__.__name__ == "map"

        # We collect it, by default into a Seq
        assert mapped.collect(Seq) == Seq(0, 2, 4, 6, 8)

        # iterator is now exhausted
        assert iterator.collect(Seq) == Seq()
        ```
    """

    def __new__(cls, data: Iterable[T] | T = (), /, *more: T) -> Self:
        """Create a new `Iter` instance.

        If no arguments are provided, an empty `Iterator` is created.

        Args:
            data (Iterable[T] | T): Input data to create the `Iter` instance from.
            *more (T): Additional elements to yield from the iterator.

        Returns:
            Self: A new `Iter` instance.

        Example:
            ```python
            from pyochain import Iter, Range

            data = (0, 1, 2, 3)

            # Create an `Iter` from an iterable
            assert Iter(data).collect(tuple) == Iter(Range(0, 4)).collect(tuple) == data

            # Create an `Iter` from individual elements
            assert Iter(0, 1, 2, 3).collect(tuple) == Iter(*data).collect(tuple) == data

            # Create an empty `Iter`
            assert 0 == Iter().count() == Iter(()).count() == Iter([]).count()
            ```
            You can also easily create an `Iter` from a generator expression:
            ```python
            from pyochain import Iter, Seq

            gen_expr = (x * x for x in range(5))
            assert Iter(gen_expr).collect(Seq) == Seq(0, 1, 4, 9, 16)
            ```
            Or from a generator function:
            ```python
            from pyochain import Iter

            def gen_func():
                for x in range(5):
                    yield x * x

            assert Iter(gen_func()).collect(Seq) == Seq(0, 1, 4, 9, 16)
            ```
        """
    @override
    def __iter__(self) -> Iterator[T]: ...
    @override
    def __next__(self) -> T: ...
    @override
    @staticmethod
    def from_iter[I](iterable: Iterable[I], /) -> Iter[I]: ...
    @override
    @staticmethod
    def of[I](*elements: I) -> Iter[I]: ...
    @override
    @staticmethod
    def wrap[W](wrapped: Iterator[W], /) -> Iter[W]: ...  # pyright: ignore[reportIncompatibleMethodOverride]