rangeable 1.0.0__tar.gz → 2.0.0__tar.gz

{rangeable-1.0.0 → rangeable-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rangeable
-Version: 1.0.0
+Version: 2.0.0
 Summary: Hashable-element interval set with first-insert ordered active queries.
 Project-URL: Homepage, https://github.com/ZhgChgLi/PythonRangeable
 Project-URL: Source, https://github.com/ZhgChgLi/PythonRangeable
@@ -108,14 +108,16 @@ See [RangeableRFC](https://github.com/ZhgChgLi/RangeableRFC) § 4 for normative
 
 ## Cross-language consistency
 
-This Python implementation, the [Ruby implementation](https://github.com/ZhgChgLi/RubyRangeable), and the [Swift implementation](https://github.com/ZhgChgLi/SwiftRangeable) share a 160-op / 86-probe JSON fixture; all three produce byte-identical outputs.
+This Python implementation joins the [Ruby](https://github.com/ZhgChgLi/RubyRangeable), [Swift](https://github.com/ZhgChgLi/SwiftRangeable), [JS](https://github.com/ZhgChgLi/JSRangeable), [Kotlin](https://github.com/ZhgChgLi/KotlinRangeable) and [Go](https://github.com/ZhgChgLi/GoRangeable) implementations. All six share a 160-op / 86-probe JSON fixture and produce byte-identical outputs.
 
 ## See also
 
 - **[RangeableRFC](https://github.com/ZhgChgLi/RangeableRFC)** — normative specification.
-- **[RubyRangeable](https://github.com/ZhgChgLi/RubyRangeable)** — sibling Ruby reference implementation, published as the `rangeable` gem.
-- **[SwiftRangeable](https://github.com/ZhgChgLi/SwiftRangeable)** — sibling Swift reference implementation.
-- **[JSRangeable](https://github.com/ZhgChgLi/JSRangeable)** — sibling TypeScript reference implementation, published as the `rangeable-js` npm package.
+- **[RubyRangeable](https://github.com/ZhgChgLi/RubyRangeable)** — Ruby reference (`gem install rangeable`).
+- **[SwiftRangeable](https://github.com/ZhgChgLi/SwiftRangeable)** — Swift reference (SPM).
+- **[JSRangeable](https://github.com/ZhgChgLi/JSRangeable)** — TypeScript reference (`npm i rangeable-js`).
+- **[KotlinRangeable](https://github.com/ZhgChgLi/KotlinRangeable)** — Kotlin/JVM reference (JitPack).
+- **[GoRangeable](https://github.com/ZhgChgLi/GoRangeable)** — Go reference (`go get github.com/ZhgChgLi/GoRangeable`).
 
 ## Development
 

{rangeable-1.0.0 → rangeable-2.0.0}/README.md

@@ -77,14 +77,16 @@ See [RangeableRFC](https://github.com/ZhgChgLi/RangeableRFC) § 4 for normative
 
 ## Cross-language consistency
 
-This Python implementation, the [Ruby implementation](https://github.com/ZhgChgLi/RubyRangeable), and the [Swift implementation](https://github.com/ZhgChgLi/SwiftRangeable) share a 160-op / 86-probe JSON fixture; all three produce byte-identical outputs.
+This Python implementation joins the [Ruby](https://github.com/ZhgChgLi/RubyRangeable), [Swift](https://github.com/ZhgChgLi/SwiftRangeable), [JS](https://github.com/ZhgChgLi/JSRangeable), [Kotlin](https://github.com/ZhgChgLi/KotlinRangeable) and [Go](https://github.com/ZhgChgLi/GoRangeable) implementations. All six share a 160-op / 86-probe JSON fixture and produce byte-identical outputs.
 
 ## See also
 
 - **[RangeableRFC](https://github.com/ZhgChgLi/RangeableRFC)** — normative specification.
-- **[RubyRangeable](https://github.com/ZhgChgLi/RubyRangeable)** — sibling Ruby reference implementation, published as the `rangeable` gem.
-- **[SwiftRangeable](https://github.com/ZhgChgLi/SwiftRangeable)** — sibling Swift reference implementation.
-- **[JSRangeable](https://github.com/ZhgChgLi/JSRangeable)** — sibling TypeScript reference implementation, published as the `rangeable-js` npm package.
+- **[RubyRangeable](https://github.com/ZhgChgLi/RubyRangeable)** — Ruby reference (`gem install rangeable`).
+- **[SwiftRangeable](https://github.com/ZhgChgLi/SwiftRangeable)** — Swift reference (SPM).
+- **[JSRangeable](https://github.com/ZhgChgLi/JSRangeable)** — TypeScript reference (`npm i rangeable-js`).
+- **[KotlinRangeable](https://github.com/ZhgChgLi/KotlinRangeable)** — Kotlin/JVM reference (JitPack).
+- **[GoRangeable](https://github.com/ZhgChgLi/GoRangeable)** — Go reference (`go get github.com/ZhgChgLi/GoRangeable`).
 
 ## Development
 

{rangeable-1.0.0 → rangeable-2.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rangeable"
-version = "1.0.0"
+version = "2.0.0"
 description = "Hashable-element interval set with first-insert ordered active queries."
 readme = "README.md"
 requires-python = ">=3.10"

{rangeable-1.0.0 → rangeable-2.0.0}/src/rangeable/__init__.py

@@ -24,3 +24,4 @@ __all__ = [
     "InvalidIntervalError",
     "__version__",
 ]
+

rangeable-2.0.0/src/rangeable/_core.py

@@ -0,0 +1,532 @@
+"""Main Rangeable container."""
+
+from __future__ import annotations
+
+from typing import Generic, Hashable, Iterator, TypeVar
+
+from ._boundary_index import BoundaryIndex
+from ._disjoint_set import (
+    DisjointSet,
+    InsertResult,
+    RemoveResult,
+    intersect_disjoint_lists,
+    merge_disjoint_lists,
+    subtract_disjoint_lists,
+)
+from ._errors import InvalidIntervalError
+from ._interval import Interval
+from ._slot import Slot
+from ._transition import TransitionEvent
+
+E = TypeVar("E", bound=Hashable)
+
+_EMPTY_OBJS: tuple = ()
+
+
+class Rangeable(Generic[E]):
+    """Generic, integer-coordinate, closed-interval set container.
+
+    Pairs hashable elements with their merged disjoint integer ranges
+    and supports three query families:
+
+    * by-element via :meth:`get_range`
+    * by-position via ``r[i]`` / :meth:`active_at`
+    * by-range via :meth:`transitions`
+
+    See `RFC §3 <https://github.com/ZhgChgLi/RangeableRFC>`_ for the
+    full normative API surface.
+    """
+
+    __slots__ = (
+        "_intervals",
+        "_insertion_order",
+        "_ord",
+        "_version",
+        "_event_index",
+    )
+
+    def __init__(self) -> None:
+        self._intervals: dict[E, DisjointSet] = {}
+        self._insertion_order: list[E] = []
+        self._ord: dict[E, int] = {}
+        self._version: int = 0
+        self._event_index: BoundaryIndex[E] | None = None
+
+    @classmethod
+    def empty(cls) -> "Rangeable[E]":
+        """Sugar matching the RFC §3.1 ``Rangeable.empty()`` alias."""
+        return cls()
+
+    @property
+    def version(self) -> int:
+        return self._version
+
+    def insert(self, element: E, *, start: int, end: int) -> "Rangeable[E]":
+        """Insert ``element`` covering the closed interval ``[start, end]``.
+
+        Idempotent per RFC §3.2: re-inserting a sub-range that is already
+        fully contained leaves the container unchanged and does NOT bump
+        :attr:`version`.
+
+        Raises :class:`InvalidIntervalError` if ``start > end``.
+
+        Returns ``self`` for chaining.
+        """
+        if start > end:
+            raise InvalidIntervalError(f"start ({start}) > end ({end})")
+
+        ds = self._intervals.get(element)
+        if ds is None:
+            ds = DisjointSet()
+            self._intervals[element] = ds
+            self._insertion_order.append(element)
+            self._ord[element] = len(self._insertion_order)
+
+        result = ds.insert(start, end)
+        if result == InsertResult.MUTATED:
+            self._version += 1
+            self._event_index = None
+        return self
+
+    def __getitem__(self, i: int) -> Slot[E]:
+        """Active-element list at ``i``. RFC §3.3.
+
+        O(log |segments| + r) once the index is built. Returns an empty
+        :class:`Slot` for coordinates outside every segment.
+        """
+        self._ensure_event_index_fresh()
+        assert self._event_index is not None
+        seg = self._event_index.segment_at(i)
+        if seg is None:
+            return Slot(_EMPTY_OBJS)
+        return Slot(seg.active)
+
+    def active_at(self, *, index: int) -> Slot[E]:
+        """Same as ``self[index]``, named to match RFC §3.3."""
+        return self[index]
+
+    def get_range(self, element: E) -> list[tuple[int, int]]:
+        """Merged ranges for ``element`` as ``[(lo, hi), ...]``. RFC §3.4.
+
+        Returns an empty list when the element has never been inserted.
+        """
+        ds = self._intervals.get(element)
+        if ds is None:
+            return []
+        return ds.to_pairs()
+
+    def transitions(self, *, lo: int, hi: int | None) -> list[TransitionEvent[E]]:
+        """Open / close events within the inclusive coordinate range
+        ``[lo, hi]``. RFC §3.5.
+
+        ``hi=None`` means +∞ (include all events through the upper bound).
+
+        Raises :class:`InvalidIntervalError` if ``lo > hi`` or ``lo`` is
+        ``None``.
+        """
+        if lo is None:
+            raise InvalidIntervalError("transitions: lo must not be None")
+        if hi is not None and lo > hi:
+            raise InvalidIntervalError(f"lo ({lo}) > hi ({hi})")
+
+        self._ensure_event_index_fresh()
+        assert self._event_index is not None
+        upper = None if hi is None else hi + 1
+        return self._event_index.events_in_range(lo, upper)
+
+    def __len__(self) -> int:
+        """Number of distinct equivalence-class elements ever inserted."""
+        return len(self._insertion_order)
+
+    @property
+    def count(self) -> int:
+        return len(self._insertion_order)
+
+    @property
+    def empty(self) -> bool:
+        return not self._insertion_order
+
+    def __bool__(self) -> bool:
+        return bool(self._insertion_order)
+
+    def __iter__(self) -> Iterator[tuple[E, list[tuple[int, int]]]]:
+        """Yield ``(element, ranges)`` pairs in insertion-order ascending."""
+        for element in self._insertion_order:
+            yield element, self._intervals[element].to_pairs()
+
+    def copy(self) -> "Rangeable[E]":
+        """Deep copy. Mutation on the copy MUST NOT affect this instance,
+        and vice versa.
+        """
+        dup = Rangeable[E]()
+        for element in self._insertion_order:
+            dup._replant(element, self._intervals[element], self._ord[element])
+        dup._version = self._version
+        return dup
+
+    def __copy__(self) -> "Rangeable[E]":
+        return self.copy()
+
+    def __deepcopy__(self, memo: dict) -> "Rangeable[E]":
+        return self.copy()
+
+    def _ensure_event_index_fresh(self) -> None:
+        if self._event_index is not None and self._event_index.version == self._version:
+            return
+        v_start = self._version
+        rebuilt = BoundaryIndex.build(self._intervals, self._ord, v_start)
+        if self._version == v_start:
+            self._event_index = rebuilt
+
+    def _replant(self, element: E, source_set: DisjointSet, source_ord: int) -> None:
+        new_set = DisjointSet()
+        for iv in source_set:
+            new_set.insert(iv.lo, iv.hi)
+        self._intervals[element] = new_set
+        self._insertion_order.append(element)
+        self._ord[element] = source_ord
+
+    # ------------------------------------------------------------------ #
+    # v2 — Removal API (RFC §6.6–§6.9, §10.B)
+    # ------------------------------------------------------------------ #
+
+    def remove(self, element: E, *, start: int, end: int) -> "Rangeable[E]":
+        """Remove the closed interval ``[start, end]`` from ``R(element)``.
+
+        RFC §6.6. Idempotent per §4.10 (N3): if ``element`` is absent or
+        ``[start, end]`` does not overlap any existing interval, this is a
+        no-op and :attr:`version` MUST NOT bump.
+
+        If the removal empties ``R(element)`` it is eagerly pruned per
+        §4.10 (N1): the key is dropped from ``intervals``, removed from
+        ``insertion_order``, and surviving elements' ``ord`` are densely
+        renumbered.
+
+        Raises :class:`InvalidIntervalError` if ``start > end``. Returns
+        ``self`` for chaining.
+        """
+        if start > end:
+            raise InvalidIntervalError(f"start ({start}) > end ({end})")
+
+        ds = self._intervals.get(element)
+        if ds is None:
+            return self  # §6.6 step 2: no R(e) to subtract from.
+
+        result = ds.remove(start, end)
+        if result == RemoveResult.IDEMPOTENT:
+            return self
+        if result == RemoveResult.MUTATED_BECAME_EMPTY:
+            self._excise_element(element)
+        # Both MUTATED and MUTATED_BECAME_EMPTY paths bump version once.
+        self._version += 1
+        self._event_index = None
+        return self
+
+    def remove_element(self, element: E) -> "Rangeable[E]":
+        """Excise ``element`` and its entire ``R(element)``. RFC §6.7.
+
+        Idempotent per §4.10 (N3): no-op (no version bump) when the element
+        is absent. Returns ``self`` for chaining.
+        """
+        if element not in self._intervals:
+            return self
+        self._excise_element(element)
+        self._version += 1
+        self._event_index = None
+        return self
+
+    def __delitem__(self, key: E) -> None:
+        """``del r[e]`` is sugar for :meth:`remove_element`. RFC §6.7.
+
+        Note: ``r[i]`` is the integer-subscript probe returning a
+        :class:`Slot`, so ``del r[e]`` only makes sense when ``e`` is an
+        element instance, not an index. Mixing the two APIs is a caller
+        bug.
+        """
+        self.remove_element(key)
+
+    def clear(self) -> "Rangeable[E]":
+        """Reset to the empty container. RFC §6.8.
+
+        Idempotent per §4.10 (N3): clearing an already-empty container is
+        a no-op (no version bump). Returns ``self`` for chaining.
+        """
+        if not self._intervals:
+            return self
+        self._intervals = {}
+        self._insertion_order = []
+        self._ord = {}
+        self._version += 1
+        self._event_index = None
+        return self
+
+    def remove_ranges(self, *, start: int, end: int) -> "Rangeable[E]":
+        """Apply ``remove(e, start, end)`` for every ``e`` atomically.
+
+        RFC §6.9. A single :attr:`version` bump for the entire op; eager
+        pruning happens for every element whose ``R(e)`` becomes empty.
+
+        Raises :class:`InvalidIntervalError` if ``start > end`` BEFORE any
+        mutation. Returns ``self`` for chaining.
+        """
+        if start > end:
+            raise InvalidIntervalError(f"start ({start}) > end ({end})")
+
+        any_change = False
+        # Iterate a snapshot — we mutate `self._intervals` in the loop.
+        for element in list(self._insertion_order):
+            ds = self._intervals[element]
+            result = ds.remove(start, end)
+            if result == RemoveResult.IDEMPOTENT:
+                continue
+            any_change = True
+            if result == RemoveResult.MUTATED_BECAME_EMPTY:
+                # DEFER insertion_order / ord rebuild until the loop ends
+                # to avoid O(E^2). Just drop the intervals key here.
+                del self._intervals[element]
+
+        if not any_change:
+            return self
+
+        # Single-pass dense rebuild of insertion_order + ord (§6.9 step 4).
+        survivors = [e for e in self._insertion_order if e in self._intervals]
+        self._insertion_order = survivors
+        self._ord = {e: i + 1 for i, e in enumerate(survivors)}
+        self._version += 1
+        self._event_index = None
+        return self
+
+    def _excise_element(self, element: E) -> None:
+        """Excise ``element`` from intervals + insertion_order + ord with
+        a dense ``ord`` renumber over the survivors past its position.
+
+        Caller is responsible for the single ``version`` bump and
+        ``event_index`` invalidation that wraps the whole op.
+        """
+        del self._intervals[element]
+        idx = self._insertion_order.index(element)
+        del self._insertion_order[idx]
+        del self._ord[element]
+        # Densely renumber ord for survivors at positions >= idx.
+        for i in range(idx, len(self._insertion_order)):
+            self._ord[self._insertion_order[i]] -= 1
+
+    # ------------------------------------------------------------------ #
+    # v2 — Set Operations API (RFC §6.10–§6.13, §10.C–§10.G)
+    # ------------------------------------------------------------------ #
+
+    def union(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        """Per-element union with ``other``. RFC §6.10.
+
+        Returns a fresh :class:`Rangeable` with ``version == 0``;
+        ``self`` and ``other`` are unchanged. Insertion order: preserve
+        ``self``'s order, then tail-append keys in
+        ``keys(other) ∖ keys(self)`` in ``other``'s insertion-order order.
+        """
+        out: Rangeable[E] = Rangeable()
+        # Step 1: walk self.insertion_order — every key in self appears.
+        for element in self._insertion_order:
+            list_self = self._intervals[element]._entries
+            other_ds = other._intervals.get(element)
+            if other_ds is None:
+                merged_entries = list(list_self)
+            else:
+                merged_entries = merge_disjoint_lists(
+                    list_self, other_ds._entries
+                )
+            out._populate(element, merged_entries)
+        # Step 2: tail-append keys in other ∖ self.
+        for element in other._insertion_order:
+            if element in self._intervals:
+                continue
+            merged_entries = list(other._intervals[element]._entries)
+            out._populate(element, merged_entries)
+        return out
+
+    def intersection(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        """Per-element intersection with ``other``. RFC §6.11.
+
+        Returns a fresh :class:`Rangeable`. Empty per-element results are
+        eagerly pruned (§4.10 N1). Insertion order: ``self``'s order over
+        surviving keys with densely renumbered ``ord``.
+        """
+        out: Rangeable[E] = Rangeable()
+        for element in self._insertion_order:
+            other_ds = other._intervals.get(element)
+            if other_ds is None:
+                continue
+            intersected = intersect_disjoint_lists(
+                self._intervals[element]._entries, other_ds._entries
+            )
+            if not intersected:
+                continue  # eager prune (§4.10 N1)
+            out._populate(element, intersected)
+        return out
+
+    def difference(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        """Per-element ``self ∖ other``. RFC §6.12.
+
+        Returns a fresh :class:`Rangeable`. Empty results pruned (§4.10).
+        Insertion order: ``self``'s order over survivors, dense ``ord``.
+        """
+        out: Rangeable[E] = Rangeable()
+        for element in self._insertion_order:
+            list_self = self._intervals[element]._entries
+            other_ds = other._intervals.get(element)
+            if other_ds is None or not other_ds._entries:
+                remaining = list(list_self)
+            else:
+                remaining = subtract_disjoint_lists(
+                    list_self, other_ds._entries
+                )
+            if not remaining:
+                continue  # eager prune
+            out._populate(element, remaining)
+        return out
+
+    def symmetric_difference(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        """Per-element ``self △ other``. RFC §6.13.
+
+        Returns a fresh :class:`Rangeable`. Implemented via the algebraic
+        identity ``(self ∖ other) ∪ (other ∖ self)`` per element with
+        ``merge_disjoint_lists`` to collapse the adjacency case (§6.13
+        worked example: ``[(0,5)] △ [(6,10)] == [(0,10)]``).
+        """
+        out: Rangeable[E] = Rangeable()
+        # Step 1: self-primary keys.
+        for element in self._insertion_order:
+            list_self = self._intervals[element]._entries
+            other_ds = other._intervals.get(element)
+            if other_ds is None:
+                # b is empty; sym = a = list_self.
+                out._populate(element, list(list_self))
+                continue
+            list_other = other_ds._entries
+            a = subtract_disjoint_lists(list_self, list_other)
+            b = subtract_disjoint_lists(list_other, list_self)
+            sym = merge_disjoint_lists(a, b)
+            if not sym:
+                continue  # eager prune (§4.10 N1)
+            out._populate(element, sym)
+        # Step 2: other-only keys.
+        for element in other._insertion_order:
+            if element in self._intervals:
+                continue
+            sym = list(other._intervals[element]._entries)
+            if not sym:
+                continue  # defensive; unreachable under (I1.4)
+            out._populate(element, sym)
+        return out
+
+    # -------------------------- Mutating set ops ---------------------- #
+
+    def update(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        """In-place union (``self`` becomes ``self ∪ other``). RFC §6.10.
+
+        Idempotent: if the result is structurally equal to ``self`` the
+        version MUST NOT bump (set-naming convention; mirrors §3.2's
+        idempotence rule). Returns ``self`` for chaining.
+        """
+        result = self.union(other)
+        self._adopt_if_changed(result)
+        return self
+
+    def intersection_update(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        """In-place intersection. RFC §6.11.
+
+        No-op if result is structurally equal to ``self``. Returns ``self``.
+        """
+        result = self.intersection(other)
+        self._adopt_if_changed(result)
+        return self
+
+    def difference_update(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        """In-place ``self := self ∖ other``. RFC §6.12. Returns ``self``."""
+        result = self.difference(other)
+        self._adopt_if_changed(result)
+        return self
+
+    def symmetric_difference_update(
+        self, other: "Rangeable[E]"
+    ) -> "Rangeable[E]":
+        """In-place ``self := self △ other``. RFC §6.13. Returns ``self``."""
+        result = self.symmetric_difference(other)
+        self._adopt_if_changed(result)
+        return self
+
+    # ------------------------------- Operators ------------------------ #
+
+    def __or__(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        return self.union(other)
+
+    def __and__(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        return self.intersection(other)
+
+    def __sub__(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        return self.difference(other)
+
+    def __xor__(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        return self.symmetric_difference(other)
+
+    def __ior__(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        self.update(other)
+        return self
+
+    def __iand__(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        self.intersection_update(other)
+        return self
+
+    def __isub__(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        self.difference_update(other)
+        return self
+
+    def __ixor__(self, other: "Rangeable[E]") -> "Rangeable[E]":
+        self.symmetric_difference_update(other)
+        return self
+
+    # ---------------------- Internal helpers (set ops) ---------------- #
+
+    def _populate(self, element: E, entries: list[Interval]) -> None:
+        """Internal-only: append ``element`` with already-(I1)-canonical
+        ``entries`` to a freshly-built result container.
+
+        Bypasses :meth:`insert`'s per-call version bump and event-index
+        invalidation. ``entries`` MUST be sorted, disjoint, non-adjacent;
+        callers (set-op kernels) guarantee this via
+        ``merge_disjoint_lists`` / ``intersect_disjoint_lists`` /
+        ``subtract_disjoint_lists``.
+        """
+        ds = DisjointSet()
+        ds._entries = list(entries)
+        self._intervals[element] = ds
+        self._insertion_order.append(element)
+        self._ord[element] = len(self._insertion_order)
+
+    def _structurally_equal(self, other: "Rangeable[E]") -> bool:
+        """Structural equality test for the no-op-no-bump rule on the
+        mutating set ops (§6.10–§6.13 idempotence dual of §3.2).
+
+        Compares ``insertion_order`` (ordered) and per-element interval
+        tuples (already canonical under (I1)).
+        """
+        if self._insertion_order != other._insertion_order:
+            return False
+        for element in self._insertion_order:
+            if (
+                self._intervals[element]._entries
+                != other._intervals[element]._entries
+            ):
+                return False
+        return True
+
+    def _adopt_if_changed(self, result: "Rangeable[E]") -> None:
+        """Adopt ``result``'s state in-place when it differs structurally
+        from ``self``. Bumps version exactly once when adoption happens.
+        """
+        if self._structurally_equal(result):
+            return  # idempotent: no version bump per §3.2 dual.
+        self._intervals = result._intervals
+        self._insertion_order = result._insertion_order
+        self._ord = result._ord
+        self._version += 1
+        self._event_index = None

rangeable-2.0.0/src/rangeable/_disjoint_set.py

@@ -0,0 +1,290 @@
+"""Sorted, disjoint, non-adjacent merged-interval list for one element."""
+
+from __future__ import annotations
+
+import bisect
+from enum import Enum
+from typing import Iterator
+
+from ._errors import InvalidIntervalError
+from ._interval import Interval
+
+
+class InsertResult(Enum):
+    """Outcome of :meth:`DisjointSet.insert`. The owning :class:`Rangeable`
+    bumps its version counter only on ``MUTATED``; ``IDEMPOTENT`` means the
+    insert was absorbed and the canonical state is unchanged (RFC Test #21,
+    Lemma 6.5.B).
+    """
+
+    MUTATED = "mutated"
+    IDEMPOTENT = "idempotent"
+
+
+class RemoveResult(Enum):
+    """Outcome of :meth:`DisjointSet.remove`. The owning :class:`Rangeable`
+    bumps its version counter only on ``MUTATED`` / ``MUTATED_BECAME_EMPTY``.
+
+    ``MUTATED_BECAME_EMPTY`` additionally signals to the owner that the
+    element MUST be eagerly pruned per RFC §4.10 (N1) — the per-element list
+    is now empty and the key must be excised from ``intervals``,
+    ``insertion_order``, and ``ord``.
+    """
+
+    IDEMPOTENT = "idempotent"
+    MUTATED = "mutated"
+    MUTATED_BECAME_EMPTY = "mutated_became_empty"
+
+
+class DisjointSet:
+    """Maintains the RFC §5.1 (I1) invariant for one element:
+
+    * sorted by ``lo`` strictly ascending
+    * any two adjacent entries ``(lo1, hi1), (lo2, hi2)`` satisfy
+      ``hi1 + 1 < lo2`` (no overlap, no integer adjacency)
+    * ``lo <= hi`` for every entry
+
+    Mirrors the Ruby reference implementation line-for-line, including
+    the §6.1 cleaner-variant containment fast-path.
+    """
+
+    __slots__ = ("_entries",)
+
+    def __init__(self) -> None:
+        self._entries: list[Interval] = []
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __iter__(self) -> Iterator[Interval]:
+        return iter(self._entries)
+
+    @property
+    def empty(self) -> bool:
+        return not self._entries
+
+    def to_pairs(self) -> list[tuple[int, int]]:
+        """Snapshot the merged intervals as ``[(lo, hi), ...]``."""
+        return [(iv.lo, iv.hi) for iv in self._entries]
+
+    def insert(self, lo: int, hi: int) -> InsertResult:
+        """Insert ``[lo, hi]`` into the set, performing union-with-merge per
+        RFC §6.1.
+
+        Returns :attr:`InsertResult.MUTATED` if the canonical state changed
+        (caller should bump version), :attr:`InsertResult.IDEMPOTENT` if the
+        insert was absorbed by an existing entry (caller MUST NOT bump
+        version, per Test #21 and Lemma 6.5.B).
+        """
+        if lo > hi:
+            raise InvalidIntervalError(f"lo ({lo}) > hi ({hi})")
+
+        # Step 4 of §6.1: bsearch for the leftmost touch candidate.
+        # Predicate: ``iv.hi + 1 >= lo``. We use ``iv.hi + 1`` (not
+        # ``lo - 1``) to avoid Integer underflow at ``lo == Int.min``
+        # boundaries (§4.7 C5). Python ints are unbounded but we mirror
+        # the Ruby form for cross-language byte parity.
+        i0 = bisect.bisect_left(
+            self._entries, lo, key=lambda iv: iv.hi + 1
+        )
+
+        # Step 5: collect contiguous touch entries while
+        # ``entries[i].lo <= hi + 1``.
+        to_merge_end = i0
+        n = len(self._entries)
+        while to_merge_end < n and self._entries[to_merge_end].lo <= hi + 1:
+            to_merge_end += 1
+        merge_count = to_merge_end - i0
+
+        # Step 6: containment idempotent fast-path. If we touch exactly one
+        # existing entry that fully covers [lo, hi], this insert is a no-op.
+        # MUST NOT mutate, MUST NOT bump version.
+        if merge_count == 1:
+            existing = self._entries[i0]
+            if existing.lo <= lo and hi <= existing.hi:
+                return InsertResult.IDEMPOTENT
+
+        # Step 7: real mutation path. Compute merged bounds, splice in.
+        new_lo = lo
+        new_hi = hi
+        if merge_count > 0:
+            first = self._entries[i0]
+            last = self._entries[to_merge_end - 1]
+            if first.lo < new_lo:
+                new_lo = first.lo
+            if last.hi > new_hi:
+                new_hi = last.hi
+        merged = Interval(new_lo, new_hi)
+        self._entries[i0:to_merge_end] = [merged]
+        return InsertResult.MUTATED
+
+    def remove(self, lo: int, hi: int) -> RemoveResult:
+        """Remove the closed interval ``[lo, hi]`` per RFC §6.6.
+
+        Returns :attr:`RemoveResult.IDEMPOTENT` when no entry overlaps
+        (caller MUST NOT bump version per §4.10 N3),
+        :attr:`RemoveResult.MUTATED` when entries shrink but the list stays
+        non-empty, :attr:`RemoveResult.MUTATED_BECAME_EMPTY` when the last
+        interval is removed and the owner MUST eagerly prune the key per
+        §4.10 (N1).
+        """
+        if lo > hi:
+            raise InvalidIntervalError(f"lo ({lo}) > hi ({hi})")
+
+        n = len(self._entries)
+        # Step 3 of §6.6: bsearch for the leftmost entry with ``iv.hi >= lo``.
+        # Equivalent (under the bisect-by-key contract) to
+        # ``bisect_left(entries, lo, key=lambda iv: iv.hi + 1)`` — the same
+        # predicate used by insert (and thus the same Int.min underflow guard).
+        i = bisect.bisect_left(self._entries, lo, key=lambda iv: iv.hi + 1)
+
+        # Step 4: quick-exit when nothing in R(e) overlaps [lo, hi].
+        if i == n or self._entries[i].lo > hi:
+            return RemoveResult.IDEMPOTENT
+
+        # Step 5: sweep all overlapping entries, build replacements.
+        to_replace_start = i
+        replacements: list[Interval] = []
+        while i < n and self._entries[i].lo <= hi:
+            iv = self._entries[i]
+            # Left residual only when iv.lo < lo (guards Int.min underflow
+            # on ``lo - 1``).
+            if iv.lo < lo:
+                replacements.append(Interval(iv.lo, lo - 1))
+            # Right residual only when hi < iv.hi (guards Int.max overflow
+            # on ``hi + 1``).
+            if hi < iv.hi:
+                replacements.append(Interval(hi + 1, iv.hi))
+            i += 1
+        to_replace_end = i
+
+        # Step 6: splice. Python's slice-assign is the natural primitive.
+        self._entries[to_replace_start:to_replace_end] = replacements
+
+        # Step 7: signal eager-prune to caller when list is now empty.
+        if not self._entries:
+            return RemoveResult.MUTATED_BECAME_EMPTY
+        return RemoveResult.MUTATED
+
+    # ------------------------------------------------------------------ #
+    # List-level primitives for set operations (§6.10–§6.13).
+    # These operate on Interval lists, not on DisjointSet instances, so
+    # the union/intersection/difference/symmetric_difference paths can
+    # reuse them without per-call DisjointSet construction overhead.
+    # ------------------------------------------------------------------ #
+
+
+def _append_or_merge(out: list[Interval], iv: Interval) -> None:
+    """Two-pointer helper from RFC §6.10.
+
+    Appends ``iv`` to ``out``, collapsing into the last entry when overlap
+    or integer-adjacency (``out[-1].hi + 1 >= iv.lo``) is detected.
+    """
+    if not out or out[-1].hi + 1 < iv.lo:
+        out.append(iv)
+    else:
+        last = out[-1]
+        if iv.hi > last.hi:
+            out[-1] = Interval(last.lo, iv.hi)
+
+
+def merge_disjoint_lists(
+    list_a: list[Interval], list_b: list[Interval]
+) -> list[Interval]:
+    """Two-pointer linear merge of two (I1)-canonical lists, RFC §6.10.
+
+    O(|list_a| + |list_b|). Output is (I1)-canonical (sorted, disjoint,
+    non-adjacent) thanks to ``_append_or_merge``'s adjacency collapse.
+    """
+    out: list[Interval] = []
+    i, j = 0, 0
+    n_a, n_b = len(list_a), len(list_b)
+    while i < n_a and j < n_b:
+        if list_a[i].lo <= list_b[j].lo:
+            _append_or_merge(out, list_a[i])
+            i += 1
+        else:
+            _append_or_merge(out, list_b[j])
+            j += 1
+    while i < n_a:
+        _append_or_merge(out, list_a[i])
+        i += 1
+    while j < n_b:
+        _append_or_merge(out, list_b[j])
+        j += 1
+    return out
+
+
+def intersect_disjoint_lists(
+    list_a: list[Interval], list_b: list[Interval]
+) -> list[Interval]:
+    """Two-pointer pairwise intersection, RFC §6.11.
+
+    O(|list_a| + |list_b|). Output is (I1)-canonical without any explicit
+    adjacency-collapse step (Lemma 6.11.A): consecutive output entries
+    inherit a ≥ 2 integer gap from the inputs.
+    """
+    out: list[Interval] = []
+    i, j = 0, 0
+    n_a, n_b = len(list_a), len(list_b)
+    while i < n_a and j < n_b:
+        a_iv = list_a[i]
+        b_iv = list_b[j]
+        lo = a_iv.lo if a_iv.lo > b_iv.lo else b_iv.lo
+        hi = a_iv.hi if a_iv.hi < b_iv.hi else b_iv.hi
+        if lo <= hi:
+            out.append(Interval(lo, hi))
+        if a_iv.hi <= b_iv.hi:
+            i += 1
+        else:
+            j += 1
+    return out
+
+
+def subtract_disjoint_lists(
+    list_a: list[Interval], list_b: list[Interval]
+) -> list[Interval]:
+    """Two-pointer subtraction ``list_a ∖ list_b``, RFC §6.12.
+
+    O(|list_a| + |list_b|). Output is (I1)-canonical. Underflow / overflow
+    safe: ``L_b[j].lo - 1`` only computed when ``L_b[j].lo > current_lo``;
+    ``L_b[j].hi + 1`` only when ``L_b[j].hi < current_hi``.
+    """
+    out: list[Interval] = []
+    n_a, n_b = len(list_a), len(list_b)
+    if n_a == 0:
+        return out
+    if n_b == 0:
+        return list(list_a)
+
+    i = 0
+    j = 0
+    current_lo: int | None = None
+    current_hi: int | None = None
+    while i < n_a:
+        if current_lo is None:
+            current_lo = list_a[i].lo
+            current_hi = list_a[i].hi
+        # Skip L_b entries strictly before [current_lo, current_hi].
+        while j < n_b and list_b[j].hi < current_lo:
+            j += 1
+        if j == n_b or list_b[j].lo > current_hi:
+            # No more cuts on this entry: commit and advance.
+            out.append(Interval(current_lo, current_hi))
+            i += 1
+            current_lo = None
+            current_hi = None
+            continue
+        # list_b[j] overlaps [current_lo, current_hi]; cut.
+        if list_b[j].lo > current_lo:
+            out.append(Interval(current_lo, list_b[j].lo - 1))
+        if list_b[j].hi < current_hi:
+            # Right residual becomes the new current.
+            current_lo = list_b[j].hi + 1
+            j += 1
+        else:
+            # list_b[j] swallows the rest of the current entry.
+            i += 1
+            current_lo = None
+            current_hi = None
+    return out

rangeable-1.0.0/src/rangeable/_core.py

@@ -1,179 +0,0 @@
-"""Main Rangeable container."""
-
-from __future__ import annotations
-
-from typing import Generic, Hashable, Iterator, TypeVar
-
-from ._boundary_index import BoundaryIndex
-from ._disjoint_set import DisjointSet, InsertResult
-from ._errors import InvalidIntervalError
-from ._slot import Slot
-from ._transition import TransitionEvent
-
-E = TypeVar("E", bound=Hashable)
-
-_EMPTY_OBJS: tuple = ()
-
-
-class Rangeable(Generic[E]):
-    """Generic, integer-coordinate, closed-interval set container.
-
-    Pairs hashable elements with their merged disjoint integer ranges
-    and supports three query families:
-
-    * by-element via :meth:`get_range`
-    * by-position via ``r[i]`` / :meth:`active_at`
-    * by-range via :meth:`transitions`
-
-    See `RFC §3 <https://github.com/ZhgChgLi/RangeableRFC>`_ for the
-    full normative API surface.
-    """
-
-    __slots__ = (
-        "_intervals",
-        "_insertion_order",
-        "_ord",
-        "_version",
-        "_event_index",
-    )
-
-    def __init__(self) -> None:
-        self._intervals: dict[E, DisjointSet] = {}
-        self._insertion_order: list[E] = []
-        self._ord: dict[E, int] = {}
-        self._version: int = 0
-        self._event_index: BoundaryIndex[E] | None = None
-
-    @classmethod
-    def empty(cls) -> "Rangeable[E]":
-        """Sugar matching the RFC §3.1 ``Rangeable.empty()`` alias."""
-        return cls()
-
-    @property
-    def version(self) -> int:
-        return self._version
-
-    def insert(self, element: E, *, start: int, end: int) -> "Rangeable[E]":
-        """Insert ``element`` covering the closed interval ``[start, end]``.
-
-        Idempotent per RFC §3.2: re-inserting a sub-range that is already
-        fully contained leaves the container unchanged and does NOT bump
-        :attr:`version`.
-
-        Raises :class:`InvalidIntervalError` if ``start > end``.
-
-        Returns ``self`` for chaining.
-        """
-        if start > end:
-            raise InvalidIntervalError(f"start ({start}) > end ({end})")
-
-        ds = self._intervals.get(element)
-        if ds is None:
-            ds = DisjointSet()
-            self._intervals[element] = ds
-            self._insertion_order.append(element)
-            self._ord[element] = len(self._insertion_order)
-
-        result = ds.insert(start, end)
-        if result == InsertResult.MUTATED:
-            self._version += 1
-            self._event_index = None
-        return self
-
-    def __getitem__(self, i: int) -> Slot[E]:
-        """Active-element list at ``i``. RFC §3.3.
-
-        O(log |segments| + r) once the index is built. Returns an empty
-        :class:`Slot` for coordinates outside every segment.
-        """
-        self._ensure_event_index_fresh()
-        assert self._event_index is not None
-        seg = self._event_index.segment_at(i)
-        if seg is None:
-            return Slot(_EMPTY_OBJS)
-        return Slot(seg.active)
-
-    def active_at(self, *, index: int) -> Slot[E]:
-        """Same as ``self[index]``, named to match RFC §3.3."""
-        return self[index]
-
-    def get_range(self, element: E) -> list[tuple[int, int]]:
-        """Merged ranges for ``element`` as ``[(lo, hi), ...]``. RFC §3.4.
-
-        Returns an empty list when the element has never been inserted.
-        """
-        ds = self._intervals.get(element)
-        if ds is None:
-            return []
-        return ds.to_pairs()
-
-    def transitions(self, *, lo: int, hi: int | None) -> list[TransitionEvent[E]]:
-        """Open / close events within the inclusive coordinate range
-        ``[lo, hi]``. RFC §3.5.
-
-        ``hi=None`` means +∞ (include all events through the upper bound).
-
-        Raises :class:`InvalidIntervalError` if ``lo > hi`` or ``lo`` is
-        ``None``.
-        """
-        if lo is None:
-            raise InvalidIntervalError("transitions: lo must not be None")
-        if hi is not None and lo > hi:
-            raise InvalidIntervalError(f"lo ({lo}) > hi ({hi})")
-
-        self._ensure_event_index_fresh()
-        assert self._event_index is not None
-        upper = None if hi is None else hi + 1
-        return self._event_index.events_in_range(lo, upper)
-
-    def __len__(self) -> int:
-        """Number of distinct equivalence-class elements ever inserted."""
-        return len(self._insertion_order)
-
-    @property
-    def count(self) -> int:
-        return len(self._insertion_order)
-
-    @property
-    def empty(self) -> bool:
-        return not self._insertion_order
-
-    def __bool__(self) -> bool:
-        return bool(self._insertion_order)
-
-    def __iter__(self) -> Iterator[tuple[E, list[tuple[int, int]]]]:
-        """Yield ``(element, ranges)`` pairs in insertion-order ascending."""
-        for element in self._insertion_order:
-            yield element, self._intervals[element].to_pairs()
-
-    def copy(self) -> "Rangeable[E]":
-        """Deep copy. Mutation on the copy MUST NOT affect this instance,
-        and vice versa.
-        """
-        dup = Rangeable[E]()
-        for element in self._insertion_order:
-            dup._replant(element, self._intervals[element], self._ord[element])
-        dup._version = self._version
-        return dup
-
-    def __copy__(self) -> "Rangeable[E]":
-        return self.copy()
-
-    def __deepcopy__(self, memo: dict) -> "Rangeable[E]":
-        return self.copy()
-
-    def _ensure_event_index_fresh(self) -> None:
-        if self._event_index is not None and self._event_index.version == self._version:
-            return
-        v_start = self._version
-        rebuilt = BoundaryIndex.build(self._intervals, self._ord, v_start)
-        if self._version == v_start:
-            self._event_index = rebuilt
-
-    def _replant(self, element: E, source_set: DisjointSet, source_ord: int) -> None:
-        new_set = DisjointSet()
-        for iv in source_set:
-            new_set.insert(iv.lo, iv.hi)
-        self._intervals[element] = new_set
-        self._insertion_order.append(element)
-        self._ord[element] = source_ord

rangeable-1.0.0/src/rangeable/_disjoint_set.py

@@ -1,104 +0,0 @@
-"""Sorted, disjoint, non-adjacent merged-interval list for one element."""
-
-from __future__ import annotations
-
-import bisect
-from enum import Enum
-from typing import Iterator
-
-from ._errors import InvalidIntervalError
-from ._interval import Interval
-
-
-class InsertResult(Enum):
-    """Outcome of :meth:`DisjointSet.insert`. The owning :class:`Rangeable`
-    bumps its version counter only on ``MUTATED``; ``IDEMPOTENT`` means the
-    insert was absorbed and the canonical state is unchanged (RFC Test #21,
-    Lemma 6.5.B).
-    """
-
-    MUTATED = "mutated"
-    IDEMPOTENT = "idempotent"
-
-
-class DisjointSet:
-    """Maintains the RFC §5.1 (I1) invariant for one element:
-
-    * sorted by ``lo`` strictly ascending
-    * any two adjacent entries ``(lo1, hi1), (lo2, hi2)`` satisfy
-      ``hi1 + 1 < lo2`` (no overlap, no integer adjacency)
-    * ``lo <= hi`` for every entry
-
-    Mirrors the Ruby reference implementation line-for-line, including
-    the §6.1 cleaner-variant containment fast-path.
-    """
-
-    __slots__ = ("_entries",)
-
-    def __init__(self) -> None:
-        self._entries: list[Interval] = []
-
-    def __len__(self) -> int:
-        return len(self._entries)
-
-    def __iter__(self) -> Iterator[Interval]:
-        return iter(self._entries)
-
-    @property
-    def empty(self) -> bool:
-        return not self._entries
-
-    def to_pairs(self) -> list[tuple[int, int]]:
-        """Snapshot the merged intervals as ``[(lo, hi), ...]``."""
-        return [(iv.lo, iv.hi) for iv in self._entries]
-
-    def insert(self, lo: int, hi: int) -> InsertResult:
-        """Insert ``[lo, hi]`` into the set, performing union-with-merge per
-        RFC §6.1.
-
-        Returns :attr:`InsertResult.MUTATED` if the canonical state changed
-        (caller should bump version), :attr:`InsertResult.IDEMPOTENT` if the
-        insert was absorbed by an existing entry (caller MUST NOT bump
-        version, per Test #21 and Lemma 6.5.B).
-        """
-        if lo > hi:
-            raise InvalidIntervalError(f"lo ({lo}) > hi ({hi})")
-
-        # Step 4 of §6.1: bsearch for the leftmost touch candidate.
-        # Predicate: ``iv.hi + 1 >= lo``. We use ``iv.hi + 1`` (not
-        # ``lo - 1``) to avoid Integer underflow at ``lo == Int.min``
-        # boundaries (§4.7 C5). Python ints are unbounded but we mirror
-        # the Ruby form for cross-language byte parity.
-        i0 = bisect.bisect_left(
-            self._entries, lo, key=lambda iv: iv.hi + 1
-        )
-
-        # Step 5: collect contiguous touch entries while
-        # ``entries[i].lo <= hi + 1``.
-        to_merge_end = i0
-        n = len(self._entries)
-        while to_merge_end < n and self._entries[to_merge_end].lo <= hi + 1:
-            to_merge_end += 1
-        merge_count = to_merge_end - i0
-
-        # Step 6: containment idempotent fast-path. If we touch exactly one
-        # existing entry that fully covers [lo, hi], this insert is a no-op.
-        # MUST NOT mutate, MUST NOT bump version.
-        if merge_count == 1:
-            existing = self._entries[i0]
-            if existing.lo <= lo and hi <= existing.hi:
-                return InsertResult.IDEMPOTENT
-
-        # Step 7: real mutation path. Compute merged bounds, splice in.
-        new_lo = lo
-        new_hi = hi
-        if merge_count > 0:
-            first = self._entries[i0]
-            last = self._entries[to_merge_end - 1]
-            if first.lo < new_lo:
-                new_lo = first.lo
-            if last.hi > new_hi:
-                new_hi = last.hi
-        merged = Interval(new_lo, new_hi)
-        self._entries[i0:to_merge_end] = [merged]
-        return InsertResult.MUTATED