sain.collections.slice

  1# BSD 3-Clause License
  2#
  3# Copyright (c) 2022-Present, nxtlo
  4# All rights reserved.
  5#
  6# Redistribution and use in source and binary forms, with or without
  7# modification, are permitted provided that the following conditions are met:
  8#
  9# * Redistributions of source code must retain the above copyright notice, this
 10#   list of conditions and the following disclaimer.
 11#
 12# * Redistributions in binary form must reproduce the above copyright notice,
 13#   this list of conditions and the following disclaimer in the documentation
 14#   and/or other materials provided with the distribution.
 15#
 16# * Neither the name of the copyright holder nor the names of its
 17#   contributors may be used to endorse or promote products derived from
 18#   this software without specific prior written permission.
 19#
 20# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 21# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 22# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 23# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 24# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 25# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 26# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 27# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 28# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 29# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 30
 31from __future__ import annotations
 32
 33__all__ = ("Slice", "SliceMut", "SpecContains")
 34
 35import typing
 36from collections import abc as collections
 37
 38from sain import iter as _iter
 39
 40T = typing.TypeVar("T")
 41
 42
 43Pattern = T | collections.Iterable[T]
 44
 45
 46class SpecContains(typing.Generic[T]):
 47    """Provides a default `contains` method."""
 48
 49    __slots__ = ()
 50
 51    @typing.final
 52    def contains(self: collections.Container[T], pat: Pattern[T]) -> bool:
 53        """Check if `pat` is contained in `self`.
 54
 55        `pat` here can be either an element of type `T` or an iterable of type `T`.
 56
 57        If an iterable is passed, it will check if at least one of the elements is in `self`.
 58
 59        Example
 60        ```py
 61        vec = Vec([1, 2, 3, 4])
 62        assert vec.contains(1) is True
 63        assert vec.contains([3, 4]) is True
 64        assert vec.contains(map(int, ['1', '2'])) is True
 65        ```
 66
 67        The implementation is roughly this simple:
 68        ```py
 69        if isinstance(pat, Iterable):
 70            return any(_ in sequence for _ in pat)
 71        return pat in sequence
 72        ```
 73        """
 74        if isinstance(pat, collections.Iterable):
 75            return any(_ in self for _ in pat)  # pyright: ignore - bad type inference.
 76
 77        return pat in self
 78
 79
 80@typing.final
 81class Slice(typing.Generic[T], collections.Sequence[T], SpecContains[T]):
 82    """An immutable view over some sequence of type `T`.
 83
 84    Similar to `&[T]`
 85
 86    Parameters
 87    ----------
 88    ptr : `collections.Sequence[T]`
 89        The sequence to point to.
 90    """
 91
 92    __slots__ = ("__buf",)
 93
 94    def __init__(self, ptr: collections.Sequence[T]) -> None:
 95        self.__buf = ptr
 96
 97    def into_inner(self) -> collections.Sequence[T]:
 98        """Consume this `Slice`, returning the sequence that's being pointed to.
 99
100        `self` will no longer reference the sequence.
101
102        Example
103        -------
104        ```py
105        def from_parts(slice: Slice[int], len: int) -> list[int]:
106            uninit: list[int] = []
107            uninit.extend(slice.into_inner()[:len])
108            return uninit
109
110        vec = Vec([1, 2, 3, 4])
111        new = from_parts(vec.as_ref(), 2)
112        assert new == [1, 2]
113        ```
114        """
115        ptr = self.__buf
116        del self.__buf
117        return ptr
118
119    def iter(self) -> _iter.TrustedIter[T]:
120        """Returns an iterator over the slice.
121
122        The iterator yields all items from start to end.
123
124        Example
125        -------
126        ```py
127        x = Vec([1, 2, 3])
128        iterator = x.iter()
129
130        assert iterator.next() == Some(1)
131        assert iterator.next() == Some(2)
132        assert iterator.next() == Some(3)
133        assert iterator.next().is_none()
134        ```
135        """
136        return _iter.TrustedIter(self.__buf)
137
138    def __len__(self) -> int:
139        return len(self.__buf)
140
141    def __iter__(self) -> collections.Iterator[T]:
142        return iter(self.__buf)
143
144    def __repr__(self) -> str:
145        return repr(self.__buf)
146
147    @typing.overload
148    def __getitem__(self, index: slice) -> Slice[T]: ...
149
150    @typing.overload
151    def __getitem__(self, index: int) -> T: ...
152
153    def __getitem__(self, index: int | slice) -> T | Slice[T]:
154        if isinstance(index, slice):
155            return Slice(self.__buf[index])
156
157        return self.__buf[index]
158
159    def __eq__(self, other: object, /) -> bool:
160        return self.__buf == other
161
162    def __ne__(self, other: object, /) -> bool:
163        return self.__buf != other
164
165
166@typing.final
167class SliceMut(typing.Generic[T], collections.MutableSequence[T], SpecContains[T]):
168    """A mutable view over some sequence of type `T`.
169
170    Similar to `&mut [T]`
171
172    Parameters
173    ----------
174    ptr : `collections.MutableSequence[T]`
175        The mutable sequence to point to.
176    """
177
178    __slots__ = ("__buf",)
179
180    def __init__(self, ptr: collections.MutableSequence[T]) -> None:
181        self.__buf = ptr
182
183    def into_inner(self) -> collections.MutableSequence[T]:
184        """Consume this `SliceMut`, returning the sequence that's being pointed to.
185
186        `self` will no longer reference the sequence.
187
188        Example
189        -------
190        ```py
191        x = Vec(["x", "y", "z"])
192
193        # mutable reference to `x`
194        mut_ref = x.as_mut()
195        # make all elements in `x` uppercase, then detach from `mut_ref`.
196        mut_ref.into_inner()[:] = [s.upper() for s in mut_ref]
197
198        assert x == ["X", "Y", "Z"]
199        ```
200        """
201        ptr = self.__buf
202        del self.__buf
203        return ptr
204
205    def iter(self) -> _iter.TrustedIter[T]:
206        """Returns an iterator over the slice.
207
208        The iterator yields all items from start to end.
209
210        Example
211        -------
212        ```py
213        x = Vec([1, 2, 3])
214        iterator = x.iter()
215
216        assert iterator.next() == Some(1)
217        assert iterator.next() == Some(2)
218        assert iterator.next() == Some(3)
219        assert iterator.next().is_none()
220        ```
221        """
222        return _iter.TrustedIter(self.__buf)
223
224    def insert(self, index: int, value: T) -> None:
225        self.__buf.insert(index, value)
226
227    def __len__(self) -> int:
228        return len(self.__buf)
229
230    def __iter__(self) -> collections.Iterator[T]:
231        return iter(self.__buf)
232
233    def __repr__(self) -> str:
234        return repr(self.__buf)
235
236    def __setitem__(self, index: int, item: T) -> None:
237        self.__buf.__setitem__(index, item)
238
239    def __delitem__(self, at: int) -> None:
240        del self.__buf[at]
241
242    @typing.overload
243    def __getitem__(self, index: slice) -> Slice[T]: ...
244
245    @typing.overload
246    def __getitem__(self, index: int) -> T: ...
247
248    def __getitem__(self, index: int | slice) -> T | Slice[T]:
249        if isinstance(index, slice):
250            return Slice(self.__buf[index])
251
252        return self.__buf[index]
253
254    def __eq__(self, other: object, /) -> bool:
255        return self.__buf == other
256
257    def __ne__(self, other: object, /) -> bool:
258        return self.__buf != other