PyoCollection

class PyoCollection[T](PyoIterable[T], Collection[T]):
    """Base trait for eager pyochain collections.

    `PyoCollection[T]` is the shared trait for concrete, eager collections:
    `Seq`, `Vec`, `Set`, `SetMut`, `Dict`.

    It extends `PyoIterable[T]` and `collections.abc.Collection[T]` and provides
    a few convenience methods like `contains()` and `repeat()`.

    This is equivalent to subclassing `collections.abc.Collection[T]` (this
    trait already does), meaning any concrete subclass must implement the
    required `Collection` dunder methods:

    - `__iter__`
    - `__len__`
    - `__contains__`

    On top of the standard `Collection` protocol, it provides the additional
    pyochain API (from `PyoIterable`, `Pipeable`, `Checkable`, plus the helpers
    defined here).

    """

    __slots__ = ()

    @override
    def length(self) -> int:
        return len(self)

    def contains(self, value: T) -> bool:
        """Check if the `Collection` contains the specified **value**.

        This is equivalent to using the `in` keyword directly on the `Collection`.

        Args:
            value (T): The value to check for existence.

        Returns:
            bool: True if the value exists in the Collection, False otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> data = pc.Dict({1: "a", 2: "b"})
        >>> data.contains(1)
        True
        >>> data.contains(3)
        False

        ```
        """
        return value in self

    def repeat(self, n: int | None = None) -> Iter[Self]:
        """Repeat the entire `Collection` **n** times (as elements) in an `Iter`.

        If **n** is `None`, repeat indefinitely.

        Warning:
            If **n** is `None`, this will create an infinite `Iterator`.

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

        See Also:
            `Iter.cycle()` to repeat the *elements* of the `Iter` indefinitely.

        Args:
            n (int | None): Optional number of repetitions.

        Returns:
            Iter[Self]: An `Iter` of repeated `Iter`.

        Example:
        ```python
        >>> import pyochain as pc
        >>> pc.Seq([1, 2]).repeat(3).collect()
        Seq(Seq(1, 2), Seq(1, 2), Seq(1, 2))
        >>> pc.Seq(("a", "b")).repeat(2).collect()
        Seq(Seq('a', 'b'), Seq('a', 'b'))
        >>> pc.Seq([0]).repeat().flatten().take(5).collect()
        Seq(0, 0, 0, 0, 0)

        ```
        """
        from .._iter import Iter

        if n is None:
            return Iter(itertools.repeat(self))
        return Iter(itertools.repeat(self, n))

    def is_empty(self) -> bool:
        """Returns `True` if the `Collection` contains no elements.

        Returns:
            bool: `True` if the `Collection` is empty, `False` otherwise.

        Example:
        ```python
        >>> import pyochain as pc
        >>> d = pc.Dict.new()
        >>> d.is_empty()
        True
        >>> d.insert(1, "a")
        NONE
        >>> d.is_empty()
        False

        ```
        """
        return len(self) == 0