dyce package reference

class H(Mapping[_T_co, int], Iterable[_T_co], HableT[_T_co]):  # type: ignore[type-var] # ty: ignore[invalid-generic-class]
    r"""
    <!-- BEGIN MONKEY PATCH --
    For typing.

        >>> import sympy.abc  # type: ignore[import-untyped]

      -- END MONKEY PATCH -->

    An immutable mapping for use as a histogram which supports arithmetic operations.
    This is useful for modeling discrete outcomes, like individual dice.
    `H` objects encode finite discrete probability distributions as integer counts without any denominator.

    !!! info

        The lack of an explicit denominator is intentional and has two benefits.
        First, a denominator is redundant.
        Without it, one never has to worry about probabilities summing to one (e.g., via miscalculation, floating point error, etc.).
        Second (and perhaps more importantly), sometimes one wants to have an insight into non-reduced counts, not just probabilities.
        If needed, probabilities can always be derived, as shown below.
        While a rational abstraction (e.g., `fractions.Fraction`) could have been used, `int`s typically perform better under most circumstances.

    The [initializer][dyce.H.__init__] takes a single argument, *init_val*.
    In its most explicit form, *init_val* maps outcome values to counts.

    Modeling a single six-sided die (`1d6`) can be expressed as:

        >>> from dyce import H
        >>> d6 = H({1: 1, 2: 1, 3: 1, 4: 1, 5: 1, 6: 1})

    Two shorthands are provided.
    If *init_val* is an operable of numbers, counts of 1 are assumed and outcomes are sorted.

        >>> H(range(6, 0, -1))
        H({1: 1, 2: 1, 3: 1, 4: 1, 5: 1, 6: 1})

    Repeated items are accumulated, as one would expect.

        >>> lo_var_d6 = H((5, 4, 4, 3, 3, 2))
        >>> lo_var_d6
        H({2: 1, 3: 2, 4: 2, 5: 1})

    If *init_val* is an `int` (and ***only*** an `int`), it is shorthand for creating a sequential range `#!math \left[ {1} .. {init\_val} \right]` (or `#!math \left[ {init\_val} .. {-1} \right]` if *init_val* is negative).

        >>> H(8)
        H({1: 1, 2: 1, 3: 1, 4: 1, 5: 1, 6: 1, 7: 1, 8: 1})
        >>> H(0)
        H({})
        >>> H(-4.0)  # type: ignore[call-overload]
        Traceback (most recent call last):
          ...
        TypeError: scalar init_val must be int; use explicit Mapping or Iterable for 'float' outcomes

    !!! note "A work-around"

        You can usually find a way to coerce the shorthand into the correct type, if needed:

            >>> import sympy.abc
            >>> (H(-4) + 0.0) * sympy.abc.x
            H({-1.0*x: 1, -2.0*x: 1, -3.0*x: 1, -4.0*x: 1})

    Histograms are maps, so they can interact with other map types.

        >>> lo_var_d6 == {2: 1, 3: 2, 4: 2, 5: 1}
        True
        >>> lo_var_d6 != {}
        True
        >>> from collections import Counter
        >>> lo_var_d6 == Counter(lo_var_d6)
        True

    Simple indices can be used to look up an outcome’s count.

        >>> lo_var_d6[3]
        2

    Most arithmetic operators are supported and do what one would expect.
    If the operand is a number, the operator applies to the outcomes.

        >>> d6 + 4
        H({5: 1, 6: 1, 7: 1, 8: 1, 9: 1, 10: 1})

        >>> d6 * -1
        H({-6: 1, -5: 1, -4: 1, -3: 1, -2: 1, -1: 1})
        >>> d6 * -1 == -d6
        True
        >>> d6 * -1 == H(-6)
        True

    If the operand is another histogram, the operator applies to the Cartesian product of the outcomes in each histogram, and respective counts are multiplied.
    Modeling the sum of two six-sided dice (`2d6`) can be expressed as:

        >>> d6 + d6
        H({2: 1, 3: 2, 4: 3, 5: 4, 6: 5, 7: 6, 8: 5, 9: 4, 10: 3, 11: 2, 12: 1})
        >>> print((d6 + d6).format(width=65))
        avg |    7.00
        std |    2.42
          2 |   2.78% |#
          3 |   5.56% |##
          4 |   8.33% |####
          5 |  11.11% |#####
          6 |  13.89% |######
          7 |  16.67% |########
          8 |  13.89% |######
          9 |  11.11% |#####
         10 |   8.33% |####
         11 |   5.56% |##
         12 |   2.78% |#

    To sum `#!math {n}` identical histograms, the matrix multiplication operator (`@`) provides a shorthand.

        >>> 3 @ d6 == d6 + d6 + d6
        True

    Unary operators are also supported:

        >>> ~d6
        H({-7: 1, -6: 1, -5: 1, -4: 1, -3: 1, -2: 1})
        >>> abs(-d6) == d6
        True

    The `len` built-in function can be used to show the number of distinct outcomes.

        >>> len(2 @ d6)
        11

    The [`total` property][dyce.H.total] can be used to compute the total number of combinations and each outcome’s probability.

        >>> from fractions import Fraction
        >>> (2 @ d6).total
        36
        >>> [
        ...     (outcome, Fraction(count, (2 @ d6).total))
        ...     for outcome, count in (2 @ d6).items()
        ... ]
        [(2, Fraction(1, 36)), (3, Fraction(1, 18)), (4, Fraction(1, 12)), (5, Fraction(1, 9)), (6, Fraction(5, 36)), (7, Fraction(1, 6)), ..., (12, Fraction(1, 36))]

    Histograms provide common comparators (e.g., [`eq`][dyce.H.eq] [`ne`][dyce.H.ne], etc.).
    One way to count how often a first six-sided die shows a different face than a second is:

        >>> d6.ne(d6)
        H({False: 6, True: 30})
        >>> print(d6.ne(d6).format(width=65))
          avg |    0.83
          std |    0.37
        False |  16.67% |########
         True |  83.33% |########################################

    Or, how often a first six-sided die shows a face less than a second is:

        >>> d6.lt(d6)
        H({False: 21, True: 15})
        >>> print(d6.lt(d6).format(width=65))
          avg |    0.42
          std |    0.49
        False |  58.33% |############################
         True |  41.67% |####################

    Or how often at least one `2` will show when rolling four six-sided dice:

        >>> d6_eq2 = d6.eq(2)
        >>> d6_eq2  # how often a 2 shows on a single six-sided die
        H({False: 5, True: 1})
        >>> 4 @ d6_eq2  # number of 2s showing among 4d6
        H({0: 625, 1: 500, 2: 150, 3: 20, 4: 1})
        >>> (4 @ d6_eq2).ge(1)  # how often at least one 2 shows on 4d6
        H({False: 625, True: 671})
        >>> print((4 @ d6_eq2).ge(1).format(width=65))
          avg |    0.52
          std |    0.50
        False |  48.23% |#######################
         True |  51.77% |########################

    !!! bug "Mind your parentheses"

        Parentheses are often necessary to enforce the desired order of operations.
        This is most often an issue with the `@` operator, because it behaves differently than the `d` operator in most dedicated grammars.
        More specifically, in Python, `@` has a [lower precedence](https://docs.python.org/3/reference/expressions.html#operator-precedence) than `.` and `[…]`.

            >>> 2 @ d6[7]  # type: ignore
            Traceback (most recent call last):
              ...
            KeyError: 7
            >>> 2 @ d6.le(7)  # probably not what was intended
            H({2: 36})
            >>> 2 @ d6.le(7) == 2 @ (d6.le(7))
            True

            >>> (2 @ d6)[7]
            6
            >>> (2 @ d6).le(7)
            H({False: 15, True: 21})
            >>> 2 @ d6.le(7) == (2 @ d6).le(7)
            False

    Counts are generally accumulated without reduction.
    To reduce, call the [`lowest_terms` method][dyce.H.lowest_terms].

        >>> d6.ge(4)
        H({False: 3, True: 3})
        >>> d6.ge(4).lowest_terms()
        H({False: 1, True: 1})

    Testing equivalence implicitly performs reductions of operands.

        >>> d6.ge(4) == d6.ge(4).lowest_terms()
        True
    """

    __slots__ = (
        "_h",
        "_hash",
        "_order_stat_funcs_by_n",
        "_total",
    )

    @overload
    def __init__(
        self: "H[Never]", init_val: Mapping[Never, SupportsInt], /
    ) -> None: ...
    @overload
    def __init__(self: "H[_T]", init_val: Mapping[_T, SupportsInt], /) -> None: ...
    @overload
    def __init__(self: "H[Never]", init_val: Iterable[Never], /) -> None: ...
    @overload
    def __init__(self: "H[_T]", init_val: Iterable[_T], /) -> None: ...
    @overload
    def __init__(self: "H[Never]", init_val: Literal[0, False], /) -> None: ...
    @overload
    def __init__(self: "H[int]", init_val: int, /) -> None: ...
    def __init__(self, init_val: Any, /) -> None:  # ruff: ignore[complex-structure]
        r"""
        Constructs an [`H`][dyce.H] from *init_val*, which can be a mapping, iterable, or an integer shorthand.
        """
        self._h: dict[_T_co, int]
        self._hash: int | None = None
        self._order_stat_funcs_by_n: dict[int, Callable[[int], H[Any]]] = {}
        self._total: int | None = None

        @nobeartype  # not decoratable by beartype (avoids warning)
        def _sorted_items_iter(
            items: Sequence[tuple[Any, SupportsInt]],
        ) -> Iterator[tuple[Any, int]]:
            sorted_items = [(k, lossless_int(v)) for k, v in items]
            try:
                sorted_items.sort()
            except TypeError:
                sorted_items.sort(key=lambda item: natural_key(item[0]))
            for outcome, count in sorted_items:
                if count < 0:
                    raise ValueError(f"count for {outcome} cannot be negative")
                yield (outcome, count)

        if isinstance(init_val, Iterable):
            if isinstance(init_val, Mapping):
                self._h = dict(_sorted_items_iter(list(init_val.items())))
            else:
                c: Counter[_T_co] = Counter(init_val)
                self._h = dict(_sorted_items_iter(list(c.items())))
        elif isinstance(init_val, int):
            n = abs(init_val)
            if init_val > 0:
                self._h = dict(_sorted_items_iter([(i, 1) for i in range(1, n + 1)]))
            elif init_val < 0:
                self._h = dict(_sorted_items_iter([(i, 1) for i in range(-n, 0)]))
            else:
                self._h = {}
        else:
            raise TypeError(
                f"scalar init_val must be int; use explicit Mapping or Iterable "
                f"for {type(init_val).__qualname__!r} outcomes"
            )
        cur_ctxt = _quantize_ctxt.get()
        if cur_ctxt.bit_width:
            self._h = cast(
                "dict[_T_co, int]",
                _quantize_counts(
                    self._h,
                    cur_ctxt.bit_width,
                    preserve_zero_counts=cur_ctxt.preserve_zero_counts,
                ),
            )

    # ---- Class methods ---------------------------------------------------------------

    @classmethod
    def from_counts(
        cls,
        *sources: Mapping[_T, SupportsInt] | Iterable[tuple[_T, SupportsInt]],
        preserve_zero_counts: bool = False,
    ) -> "H[_T]":
        r"""
        Constructs an [`H`][dyce.H] by accumulating counts from one or more *sources*.

        Each source may be a mapping of outcomes to counts, or an iterable of `(outcome, count)` pairs.
        Counts for the same outcome across all sources are summed.

            >>> H.from_counts([(1, 3), (2, 2), (1, 1)])
            H({1: 4, 2: 2})
            >>> H.from_counts({1: 2, 2: 3}, [(1, 1), (3, 4)])
            H({1: 3, 2: 3, 3: 4})

        With a single mapping source this is equivalent to [`H`][dyce.H] construction, but multiple sources are accumulated rather than raising on duplicate keys.

            >>> H.from_counts(H(6), H(6))
            H({1: 2, 2: 2, 3: 2, 4: 2, 5: 2, 6: 2})

        If *preserve_zero_counts* is `True`, entries with zero counts make it into the final `H` object.
        Otherwise, they are omitted.

            >>> H.from_counts([(2, 2), (1, 1), (3, 0)], H({1: 0, 64: 0}))
            H({1: 1, 2: 2})
            >>> H.from_counts(
            ...     [(2, 2), (1, 1), (3, 0)],
            ...     {1: 0, 64: 0},
            ...     preserve_zero_counts=True,
            ... )
            H({1: 1, 2: 2, 3: 0, 64: 0})
        """
        c: Counter[_T] = Counter()
        for source in sources:
            if isinstance(source, Mapping):
                # The cast is necessary because isinstance only narrows on Mapping, but
                # Iterable[tuple[_T, SupportsInt]] > Mapping[tuple[_T, SupportsInt],
                # Any], so type checkers rightly include that as the inferred return
                # type for source.items()
                source = cast("ItemsView[_T, SupportsInt]", source.items())  # ruff: ignore[redefined-loop-name]
            for outcome, count in source:
                if count or preserve_zero_counts:
                    c[outcome] += lossless_int(count)
        return cast("H[_T]", cls(c))  # pyright: ignore[reportArgumentType,reportCallIssue]

    # ---- Overrides -------------------------------------------------------------------

    def __hash__(self) -> int:
        if self._hash is None:
            self._hash = hash((type(self), *self.lowest_terms().items()))
        return self._hash

    def __repr__(self) -> str:
        return f"{type(self).__name__}({self._h!r})"

    def __eq__(self, other: object) -> bool:
        if isinstance(other, H):
            return bool(self.lowest_terms()._h == other.lowest_terms()._h)
        if isinstance(other, HableOpsMixin):
            return self.__eq__(other.h())
        return super().__eq__(other)

    # ---- Mapping abstract methods ----------------------------------------------------

    def __bool__(self) -> bool:
        return bool(self.total)

    def __getitem__(self, key: object, /) -> int:
        return self._h[key]  # type: ignore[index] # ty: ignore[invalid-argument-type]

    def __iter__(self) -> Iterator[_T_co]:
        return iter(self._h)

    def __len__(self) -> int:
        return len(self._h)

    def counts(self) -> ValuesView[int]:
        r"""A more descriptive synonym for the `values` mapping method."""
        return self._h.values()

    def outcomes(self: "H[_T]") -> KeysView[_T]:
        r"""A more descriptive synonym for the `keys` mapping method."""
        return self._h.keys()

    # ---- HableT abstract methods -----------------------------------------------------

    def h(self: "H[_T]") -> "H[_T]":
        r"""Returns `self`."""
        return self

    # ---- Forward operators -----------------------------------------------------------

    @overload
    def __matmul__(self: "H[Never]", rhs: SupportsInt) -> "H[Never]": ...
    @overload
    def __matmul__(self: "H[Any]", rhs: Literal[0]) -> "H[Never]": ...
    @overload
    # See <https://github.com/jorenham/optype/discussions/574>
    def __matmul__(self: "H[ot.CanAdd[int, int]]", rhs: SupportsInt) -> "H[int]": ...
    @overload
    def __matmul__(self: "H[_CanAddSameT]", rhs: SupportsInt) -> "H[_CanAddSameT]": ...
    # Keep the narrower Literal[1] case first so all type checkers preserve the
    # concrete HableOpsMixin subtype.
    @overload
    def __matmul__(
        self: "H[_HableOpsMixinT]", rhs: Literal[1]
    ) -> "H[_HableOpsMixinT]": ...
    @overload
    def __matmul__(
        self: "H[HableOpsMixin[_CanAddSameT]]", rhs: SupportsInt
    ) -> "H[HableOpsMixin[_CanAddSameT] | H[_CanAddSameT]]": ...
    @overload
    def __matmul__(self: "H[_T]", rhs: Literal[1]) -> "H[_T]": ...
    def __matmul__(self: "H[Any]", rhs: SupportsInt) -> "H[Any]":
        n = lossless_int_or_not_implemented(rhs)
        if n is NotImplemented:
            return NotImplemented
        if n < 0:
            raise ValueError(
                f"{type(self).__name__} requires non-negative operand for @ operator (found {n!r})"
            )
        result = _convolve(self._h, n)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __add__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanRAddHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __add__(
        self: "H[HableOpsMixin[ot.CanAdd[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __add__(self: "H[int]", rhs: "H[int]") -> "H[int]": ...
    @overload
    # See <https://github.com/astral-sh/ty/issues/3234>.
    def __add__(self: "H[float]", rhs: "H[float]") -> "H[float]": ...
    @overload
    def __add__(
        self: "H[ot.CanAdd[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __add__(
        self: "H[ot.CanAdd[_OtherT, _ResultT]]", rhs: "HableOpsMixin[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __add__(
        self: "H[ot.CanAdd[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __add__(self: "H[_T]", rhs: "H[ot.CanAdd[_T, _ResultT]]") -> "H[_ResultT]": ...
    @overload
    def __add__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanAdd[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __add__(self: "H[_T]", rhs: ot.CanAdd[_T, _ResultT]) -> "H[_ResultT]": ...
    def __add__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(lhs, "__add__", "__radd__", rhs),
            )
        else:
            result = _map_opname_fwd(self._h, "__add__", "__radd__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __sub__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanRSubHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __sub__(
        self: "H[HableOpsMixin[ot.CanSub[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __sub__(self: "H[int]", rhs: "H[int]") -> "H[int]": ...
    @overload
    # See <https://github.com/astral-sh/ty/issues/3234>.
    def __sub__(self: "H[float]", rhs: "H[float]") -> "H[float]": ...
    @overload
    def __sub__(
        self: "H[ot.CanSub[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __sub__(
        self: "H[ot.CanSub[_OtherT, _ResultT]]", rhs: "HableOpsMixin[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __sub__(
        self: "H[ot.CanSub[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __sub__(self: "H[_T]", rhs: "H[ot.CanSub[_T, _ResultT]]") -> "H[_ResultT]": ...
    @overload
    def __sub__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanSub[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __sub__(self: "H[_T]", rhs: ot.CanSub[_T, _ResultT]) -> "H[_ResultT]": ...
    def __sub__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(lhs, "__sub__", "__rsub__", rhs),
            )
        else:
            result = _map_opname_fwd(self._h, "__sub__", "__rsub__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __mul__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanRMulHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __mul__(
        self: "H[HableOpsMixin[ot.CanMul[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __mul__(
        self: "H[ot.CanMul[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __mul__(
        self: "H[ot.CanMul[_OtherT, _ResultT]]", rhs: "HableOpsMixin[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __mul__(
        self: "H[ot.CanMul[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __mul__(self: "H[_T]", rhs: "H[ot.CanMul[_T, _ResultT]]") -> "H[_ResultT]": ...
    @overload
    def __mul__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanMul[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __mul__(self: "H[_T]", rhs: ot.CanMul[_T, _ResultT]) -> "H[_ResultT]": ...
    def __mul__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(lhs, "__mul__", "__rmul__", rhs),
            )
        else:
            result = _map_opname_fwd(self._h, "__mul__", "__rmul__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __truediv__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanRTruedivHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __truediv__(
        self: "H[HableOpsMixin[ot.CanTruediv[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __truediv__(
        self: "H[ot.CanTruediv[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __truediv__(
        self: "H[ot.CanTruediv[_OtherT, _ResultT]]",
        rhs: "HableOpsMixin[_OtherT]",
    ) -> "H[_ResultT]": ...
    @overload
    def __truediv__(
        self: "H[ot.CanTruediv[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __truediv__(
        self: "H[_T]", rhs: "H[ot.CanTruediv[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __truediv__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanTruediv[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __truediv__(
        self: "H[_T]", rhs: ot.CanTruediv[_T, _ResultT]
    ) -> "H[_ResultT]": ...
    def __truediv__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(lhs, "__truediv__", "__rtruediv__", rhs),
            )
        else:
            result = _map_opname_fwd(self._h, "__truediv__", "__rtruediv__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __floordiv__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanRFloordivHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __floordiv__(
        self: "H[HableOpsMixin[ot.CanFloordiv[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __floordiv__(
        self: "H[ot.CanFloordiv[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __floordiv__(
        self: "H[ot.CanFloordiv[_OtherT, _ResultT]]",
        rhs: "HableOpsMixin[_OtherT]",
    ) -> "H[_ResultT]": ...
    @overload
    def __floordiv__(
        self: "H[ot.CanFloordiv[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __floordiv__(
        self: "H[_T]", rhs: "H[ot.CanFloordiv[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __floordiv__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanFloordiv[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __floordiv__(
        self: "H[_T]", rhs: ot.CanFloordiv[_T, _ResultT]
    ) -> "H[_ResultT]": ...
    def __floordiv__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(
                    lhs, "__floordiv__", "__rfloordiv__", rhs
                ),
            )
        else:
            result = _map_opname_fwd(self._h, "__floordiv__", "__rfloordiv__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __mod__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanRModHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __mod__(
        self: "H[HableOpsMixin[ot.CanMod[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __mod__(
        self: "H[ot.CanMod[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __mod__(
        self: "H[ot.CanMod[_OtherT, _ResultT]]", rhs: "HableOpsMixin[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __mod__(
        self: "H[ot.CanMod[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __mod__(self: "H[_T]", rhs: "H[ot.CanMod[_T, _ResultT]]") -> "H[_ResultT]": ...
    @overload
    def __mod__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanMod[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __mod__(self: "H[_T]", rhs: ot.CanMod[_T, _ResultT]) -> "H[_ResultT]": ...
    def __mod__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(lhs, "__mod__", "__rmod__", rhs),
            )
        else:
            result = _map_opname_fwd(self._h, "__mod__", "__rmod__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __pow__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanRPowHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __pow__(
        self: "H[HableOpsMixin[ot.CanPow2[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __pow__(
        self: "H[ot.CanPow2[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __pow__(
        self: "H[ot.CanPow2[_OtherT, _ResultT]]", rhs: "HableOpsMixin[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __pow__(
        self: "H[ot.CanPow2[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __pow__(self: "H[_T]", rhs: "H[ot.CanPow2[_T, _ResultT]]") -> "H[_ResultT]": ...
    @overload
    def __pow__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanPow2[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __pow__(self: "H[_T]", rhs: ot.CanPow2[_T, _ResultT]) -> "H[_ResultT]": ...
    def __pow__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(lhs, "__pow__", "__rpow__", rhs),
            )
        else:
            result = _map_opname_fwd(self._h, "__pow__", "__rpow__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __lshift__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanRLshiftHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __lshift__(
        self: "H[HableOpsMixin[ot.CanLshift[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __lshift__(
        self: "H[ot.CanLshift[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __lshift__(
        self: "H[ot.CanLshift[_OtherT, _ResultT]]", rhs: "HableOpsMixin[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __lshift__(
        self: "H[ot.CanLshift[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __lshift__(
        self: "H[_T]", rhs: "H[ot.CanLshift[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __lshift__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanLshift[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __lshift__(self: "H[_T]", rhs: ot.CanLshift[_T, _ResultT]) -> "H[_ResultT]": ...
    def __lshift__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(lhs, "__lshift__", "__rlshift__", rhs),
            )
        else:
            result = _map_opname_fwd(self._h, "__lshift__", "__rlshift__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __rshift__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanRRshiftHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __rshift__(
        self: "H[HableOpsMixin[ot.CanRshift[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __rshift__(
        self: "H[ot.CanRshift[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __rshift__(
        self: "H[ot.CanRshift[_OtherT, _ResultT]]", rhs: "HableOpsMixin[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __rshift__(
        self: "H[ot.CanRshift[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __rshift__(
        self: "H[_T]", rhs: "H[ot.CanRshift[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __rshift__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanRshift[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __rshift__(self: "H[_T]", rhs: ot.CanRshift[_T, _ResultT]) -> "H[_ResultT]": ...
    def __rshift__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(lhs, "__rshift__", "__rrshift__", rhs),
            )
        else:
            result = _map_opname_fwd(self._h, "__rshift__", "__rrshift__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __and__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanRAndHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __and__(
        self: "H[HableOpsMixin[ot.CanAnd[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __and__(
        self: "H[ot.CanAnd[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __and__(
        self: "H[ot.CanAnd[_OtherT, _ResultT]]", rhs: "HableOpsMixin[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __and__(
        self: "H[ot.CanAnd[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __and__(self: "H[_T]", rhs: "H[ot.CanAnd[_T, _ResultT]]") -> "H[_ResultT]": ...
    @overload
    def __and__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanAnd[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __and__(self: "H[_T]", rhs: ot.CanAnd[_T, _ResultT]) -> "H[_ResultT]": ...
    def __and__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(lhs, "__and__", "__rand__", rhs),
            )
        else:
            result = _map_opname_fwd(self._h, "__and__", "__rand__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __or__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanROrHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __or__(
        self: "H[HableOpsMixin[ot.CanOr[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __or__(
        self: "H[ot.CanOr[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __or__(
        self: "H[ot.CanOr[_OtherT, _ResultT]]", rhs: "HableOpsMixin[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __or__(
        self: "H[ot.CanOr[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __or__(self: "H[_T]", rhs: "H[ot.CanOr[_T, _ResultT]]") -> "H[_ResultT]": ...
    @overload
    def __or__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanOr[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __or__(self: "H[_T]", rhs: ot.CanOr[_T, _ResultT]) -> "H[_ResultT]": ...
    def __or__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(lhs, "__or__", "__ror__", rhs),
            )
        else:
            result = _map_opname_fwd(self._h, "__or__", "__ror__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __xor__(  # type: ignore[overload-overlap]
        self: "H[_T]", rhs: _CanRXorHableOpsOptOut["H[_T]", _ResultT]
    ) -> _ResultT: ...
    @overload
    def __xor__(
        self: "H[HableOpsMixin[ot.CanXor[_OtherT, _ResultT]]]",
        rhs: "H[HableOpsMixin[_OtherT]]",
    ) -> "H[H[_ResultT]]": ...
    @overload
    def __xor__(
        self: "H[ot.CanXor[_OtherT, _ResultT]]", rhs: "H[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __xor__(
        self: "H[ot.CanXor[_OtherT, _ResultT]]", rhs: "HableOpsMixin[_OtherT]"
    ) -> "H[_ResultT]": ...
    @overload
    def __xor__(
        self: "H[ot.CanXor[_OtherT, _ResultT]]", rhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __xor__(self: "H[_T]", rhs: "H[ot.CanXor[_T, _ResultT]]") -> "H[_ResultT]": ...
    @overload
    def __xor__(
        self: "H[_T]", rhs: "HableOpsMixin[ot.CanXor[_T, _ResultT]]"
    ) -> "H[_ResultT]": ...
    @overload
    def __xor__(self: "H[_T]", rhs: ot.CanXor[_T, _ResultT]) -> "H[_ResultT]": ...
    def __xor__(self, rhs: object) -> object:
        if _should_defer_hable_operator(rhs):
            return NotImplemented
        rhs = _flatten_to_h(rhs)
        if isinstance(rhs, H):
            result = _h_binary_callable(
                self._h,
                rhs._h,
                lambda lhs, rhs: _apply_opname(lhs, "__xor__", "__rxor__", rhs),
            )
        else:
            result = _map_opname_fwd(self._h, "__xor__", "__rxor__", rhs)
        return NotImplemented if result is NotImplemented else H(result)

    # ---- Reflected operators ---------------------------------------------------------

    @overload
    def __rmatmul__(self: "H[Never]", lhs: SupportsInt) -> "H[Never]": ...
    @overload
    def __rmatmul__(self: "H[Any]", lhs: Literal[0]) -> "H[Never]": ...
    @overload
    # See <https://github.com/jorenham/optype/discussions/574>
    def __rmatmul__(self: "H[ot.CanAdd[int, int]]", lhs: SupportsInt) -> "H[int]": ...
    @overload
    def __rmatmul__(self: "H[_CanAddSameT]", lhs: SupportsInt) -> "H[_CanAddSameT]": ...
    # Keep the narrower Literal[1] case first so all type checkers preserve the
    # concrete HableOpsMixin subtype.
    @overload
    def __rmatmul__(
        self: "H[_HableOpsMixinT]", lhs: Literal[1]
    ) -> "H[_HableOpsMixinT]": ...
    @overload
    def __rmatmul__(
        self: "H[HableOpsMixin[_CanAddSameT]]", lhs: SupportsInt
    ) -> "H[HableOpsMixin[_CanAddSameT] | H[_CanAddSameT]]": ...
    @overload
    def __rmatmul__(self: "H[_T]", lhs: Literal[1]) -> "H[_T]": ...
    def __rmatmul__(self: "H[Any]", lhs: SupportsInt) -> "H[Any]":
        return self.__matmul__(lhs)

    @overload
    def __radd__(
        self: "H[ot.CanRAdd[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __radd__(self: "H[_T]", lhs: ot.CanRAdd[_T, _ResultT]) -> "H[_ResultT]": ...
    def __radd__(self, lhs: object) -> object:
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__add__", "__radd__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __rsub__(
        self: "H[ot.CanRSub[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __rsub__(self: "H[_T]", lhs: ot.CanRSub[_T, _ResultT]) -> "H[_ResultT]": ...
    def __rsub__(self, lhs: object) -> "H[object]":
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__sub__", "__rsub__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __rmul__(
        self: "H[ot.CanRMul[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __rmul__(self: "H[_T]", lhs: ot.CanRMul[_T, _ResultT]) -> "H[_ResultT]": ...
    def __rmul__(self, lhs: object) -> "H[object]":
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__mul__", "__rmul__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __rtruediv__(
        self: "H[ot.CanRTruediv[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __rtruediv__(
        self: "H[_T]", lhs: ot.CanRTruediv[_T, _ResultT]
    ) -> "H[_ResultT]": ...
    def __rtruediv__(self, lhs: object) -> "H[object]":
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__truediv__", "__rtruediv__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __rfloordiv__(
        self: "H[ot.CanRFloordiv[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __rfloordiv__(
        self: "H[_T]", lhs: ot.CanRFloordiv[_T, _ResultT]
    ) -> "H[_ResultT]": ...
    def __rfloordiv__(self, lhs: object) -> "H[object]":
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__floordiv__", "__rfloordiv__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __rmod__(
        self: "H[ot.CanRMod[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __rmod__(self: "H[_T]", lhs: ot.CanRMod[_T, _ResultT]) -> "H[_ResultT]": ...
    def __rmod__(self, lhs: object) -> "H[object]":
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__mod__", "__rmod__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __rpow__(
        self: "H[ot.CanRPow[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __rpow__(self: "H[_T]", lhs: ot.CanRPow[_T, _ResultT]) -> "H[_ResultT]": ...
    def __rpow__(self, lhs: object) -> "H[object]":
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__pow__", "__rpow__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __rlshift__(
        self: "H[ot.CanRLshift[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __rlshift__(
        self: "H[_T]", lhs: ot.CanRLshift[_T, _ResultT]
    ) -> "H[_ResultT]": ...
    def __rlshift__(self, lhs: object) -> "H[object]":
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__lshift__", "__rlshift__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __rrshift__(
        self: "H[ot.CanRRshift[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __rrshift__(
        self: "H[_T]", lhs: ot.CanRRshift[_T, _ResultT]
    ) -> "H[_ResultT]": ...
    def __rrshift__(self, lhs: object) -> "H[object]":
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__rshift__", "__rrshift__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __rand__(
        self: "H[ot.CanRAnd[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __rand__(self: "H[_T]", lhs: ot.CanRAnd[_T, _ResultT]) -> "H[_ResultT]": ...
    def __rand__(self, lhs: object) -> "H[object]":
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__and__", "__rand__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __ror__(
        self: "H[ot.CanROr[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __ror__(self: "H[_T]", lhs: ot.CanROr[_T, _ResultT]) -> "H[_ResultT]": ...
    def __ror__(self, lhs: object) -> "H[object]":
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__or__", "__ror__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def __rxor__(
        self: "H[ot.CanRXor[_OtherT, _ResultT]]", lhs: _OtherT
    ) -> "H[_ResultT]": ...
    @overload
    def __rxor__(self: "H[_T]", lhs: ot.CanRXor[_T, _ResultT]) -> "H[_ResultT]": ...
    def __rxor__(self, lhs: object) -> "H[object]":
        if _should_defer_hable_operator(lhs):
            return NotImplemented
        result = _map_opname_ref(self._h, "__xor__", "__rxor__", lhs)
        return NotImplemented if result is NotImplemented else H(result)

    @overload
    def lt(self: "H[ot.CanLt[_OtherT, bool]]", rhs: "H[_OtherT]") -> "H[bool]": ...
    @overload
    def lt(self: "H[ot.CanLt[_OtherT, bool]]", rhs: _OtherT) -> "H[bool]": ...
    def lt(self, rhs: "H[object] | object") -> "H[bool]":
        r"""
        Shorthand for `self.apply(optype.do_lt, rhs)`.

            >>> H(20).lt(10)
            H({False: 11, True: 9})
            >>> H(6).lt(H(10)).lowest_terms()
            H({False: 7, True: 13})
        """
        return self.apply(ot.do_lt, rhs)  # pyright: ignore[reportArgumentType,reportCallIssue] # ty: ignore[no-matching-overload] # zuban: ignore[arg-type]

    @overload
    def le(self: "H[ot.CanLe[_OtherT, bool]]", rhs: "H[_OtherT]") -> "H[bool]": ...
    @overload
    def le(self: "H[ot.CanLe[_OtherT, bool]]", rhs: _OtherT) -> "H[bool]": ...
    def le(self, rhs: "H[object] | object") -> "H[bool]":
        r"""
        Shorthand for `self.apply(optype.do_le, rhs)`.

            >>> H(20).le(10)
            H({False: 10, True: 10})
            >>> H(6).le(H(10)).lowest_terms()
            H({False: 1, True: 3})
        """
        return self.apply(ot.do_le, rhs)  # pyright: ignore[reportArgumentType,reportCallIssue] # ty: ignore[no-matching-overload] # zuban: ignore[arg-type]

    @overload
    def eq(self: "H[ot.CanEq[_OtherT, bool]]", rhs: "H[_OtherT]") -> "H[bool]": ...
    @overload
    def eq(self: "H[ot.CanEq[_OtherT, bool]]", rhs: _OtherT) -> "H[bool]": ...
    def eq(self, rhs: "H[object] | object") -> "H[bool]":
        r"""
        Shorthand for `self.apply(optype.do_eq, rhs)`.

            >>> H(20).eq(10)
            H({False: 19, True: 1})
            >>> H(6).eq(H(10)).lowest_terms()
            H({False: 9, True: 1})
        """
        return self.apply(ot.do_eq, rhs)

    @overload
    def ne(self: "H[ot.CanNe[_OtherT, bool]]", rhs: "H[_OtherT]") -> "H[bool]": ...
    @overload
    def ne(self: "H[ot.CanNe[_OtherT, bool]]", rhs: _OtherT) -> "H[bool]": ...
    def ne(self, rhs: "H[object] | object") -> "H[bool]":
        r"""
        Shorthand for `self.apply(optype.do_ne, rhs)`.

            >>> H(20).ne(10)
            H({False: 1, True: 19})
            >>> H(6).ne(H(10)).lowest_terms()
            H({False: 1, True: 9})
        """
        return self.apply(ot.do_ne, rhs)

    @overload
    def ge(self: "H[ot.CanGe[_OtherT, bool]]", rhs: "H[_OtherT]") -> "H[bool]": ...
    @overload
    def ge(self: "H[ot.CanGe[_OtherT, bool]]", rhs: _OtherT) -> "H[bool]": ...
    def ge(self, rhs: "H[object] | object") -> "H[bool]":
        r"""
        Shorthand for `self.apply(optype.do_ge, rhs)`.

            >>> H(20).ge(10)
            H({False: 9, True: 11})
            >>> H(6).ge(H(10)).lowest_terms()
            H({False: 13, True: 7})
        """
        return self.apply(ot.do_ge, rhs)  # pyright: ignore[reportArgumentType,reportCallIssue] # ty: ignore[no-matching-overload] # zuban: ignore[arg-type]

    @overload
    def gt(self: "H[ot.CanGt[_OtherT, bool]]", rhs: "H[_OtherT]") -> "H[bool]": ...
    @overload
    def gt(self: "H[ot.CanGt[_OtherT, bool]]", rhs: _OtherT) -> "H[bool]": ...
    def gt(self, rhs: "H[object] | object") -> "H[bool]":
        r"""
        Shorthand for `self.apply(optype.do_gt, rhs)`.

            >>> H(20).gt(10)
            H({False: 10, True: 10})
            >>> H(6).gt(H(10)).lowest_terms()
            H({False: 3, True: 1})
        """
        return self.apply(ot.do_gt, rhs)  # pyright: ignore[reportArgumentType,reportCallIssue] # ty: ignore[no-matching-overload] # zuban: ignore[arg-type]

    # ---- Unary operators -------------------------------------------------------------

    def __neg__(self: "H[ot.CanNeg[_ResultT]]") -> "H[_ResultT]":
        result = _h_unary_opname(self._h, "__neg__")
        if result is NotImplemented:
            raise TypeError(
                f"bad operand type for unary -: {type(next(iter(self._h))).__qualname__!r}"
            )
        return H(result)

    def __pos__(self: "H[ot.CanPos[_ResultT]]") -> "H[_ResultT]":
        result = _h_unary_opname(self._h, "__pos__")
        if result is NotImplemented:
            raise TypeError(
                f"bad operand type for unary +: {type(next(iter(self._h))).__qualname__!r}"
            )
        return H(result)

    def __abs__(self: "H[ot.CanAbs[_ResultT]]") -> "H[_ResultT]":
        result = _h_unary_opname(self._h, "__abs__")
        if result is NotImplemented:
            raise TypeError(
                f"bad operand type for abs(): {type(next(iter(self._h))).__qualname__!r}"
            )
        return H(result)

    def __invert__(self: "H[ot.CanInvert[_ResultT]]") -> "H[_ResultT]":
        result = _h_unary_opname(self._h, "__invert__")
        if result is NotImplemented:
            raise TypeError(
                f"bad operand type for unary ~: {type(next(iter(self._h))).__qualname__!r}"
            )
        return H(result)

    # ---- Properties ------------------------------------------------------------------

    @property
    def total(self) -> int:
        r"""
        Equivalent to `sum(self.counts())`.

        The result is cached to avoid redundant computation with multiple accesses.

            >>> H({4: 2, 5: 3, 6: 1}).total
            6
            >>> H({}).total
            0
        """
        if self._total is None:
            self._total = sum(self._h.values())
        return self._total

    # ---- Methods ---------------------------------------------------------------------

    @overload
    def apply(
        self: "H[_T]",
        func: Callable[[_T], _ResultT],
    ) -> "H[_ResultT]": ...
    @overload
    def apply(
        self: "H[_T]",
        func: Callable[[_T, _OtherT], _ResultT],
        other: "H[_OtherT]",
    ) -> "H[_ResultT]": ...
    @overload
    def apply(
        self: "H[_T]",
        func: Callable[[_T, _OtherT], _ResultT],
        other: _OtherT,
    ) -> "H[_ResultT]": ...
    def apply(
        self: "H[_T]",
        func: Callable[[_T], _ResultT] | Callable[[_T, _OtherT], _ResultT],
        other: "H[_OtherT] | _OtherT | SentinelT" = Sentinel,
    ) -> "H[_ResultT]":
        r"""
        Returns a new [`H`][dyce.H] by applying *func* to outcomes.

        If *other* is provided, *func* should have two parameters, otherwise it should have one.
        If *other* is an [`H`][dyce.H], take the Cartesian product of both histograms’ items: call `func(h_outcome, other_outcome)` for each pair and accumulate `h_count * other_count`.
        If *other* is a scalar, call `func(outcome, other)` for each outcome, passing counts through unchanged.

        Resulting counts for duplicate outcomes are summed.

            >>> import operator
            >>> H({10: 1, 20: 1}).apply(operator.sub, 10)
            H({0: 1, 10: 1})
            >>> H({10: 1, 20: 1}).apply(operator.sub, H({1: 1, 2: 1}))
            H({8: 1, 9: 1, 18: 1, 19: 1})

            >>> # optype provides reflected operator functions as do_r*
            >>> import optype as ot

            >>> H({10: 1, 20: 1}).apply(ot.do_rsub, 10)
            H({-10: 1, 0: 1})

            >>> H({10: 1, 20: 1}).apply(ot.do_rsub, H({1: 1, 2: 1}))
            H({-19: 1, -18: 1, -9: 1, -8: 1})

        One way to compute how often a six-sided die “beats” an eight-sided die rolled together:

            >>> from enum import IntEnum

            >>> class Versus(IntEnum):
            ...     LOSS = -1
            ...     DRAW = 0
            ...     WIN = 1

            >>> d6 = H(6)
            >>> d8 = H(8)
            >>> vs = lambda h_outcome, other_outcome: (
            ...     Versus.LOSS
            ...     if h_outcome < other_outcome
            ...     else Versus.WIN
            ...     if h_outcome > other_outcome
            ...     else Versus.DRAW
            ... )
            >>> d6.apply(vs, d8)
            H({<Versus.LOSS: -1>: 27, <Versus.DRAW: 0>: 6, <Versus.WIN: 1>: 15})

        Omitting *other* allows examination of just the histogram.
        One way to determine *Apocalypse World* mechanic outcomes with a modifier:

            >>> class PBTA(IntEnum):
            ...     MISS = 0
            ...     WEAK_HIT = 1
            ...     STRONG_HIT = 2

            >>> mod = +1
            >>> pbta_result = (2 @ H(6) + mod).apply(
            ...     lambda outcome: (
            ...         PBTA.MISS
            ...         if outcome <= 6
            ...         else PBTA.WEAK_HIT
            ...         if 7 <= outcome <= 9
            ...         else PBTA.STRONG_HIT
            ...     )
            ... )
            >>> pbta_result
            H({<PBTA.MISS: 0>: 10, <PBTA.WEAK_HIT: 1>: 16, <PBTA.STRONG_HIT: 2>: 10})

        One way to count how often summing outcomes comes out even on 2d3:

            >>> d3_2 = 2 @ H(3)
            >>> d3_2
            H({2: 1, 3: 2, 4: 3, 5: 2, 6: 1})
            >>> d3_2_is_even = d3_2.apply(lambda outcome: outcome % 2 == 0)
            >>> d3_2_is_even
            H({False: 4, True: 5})
            >>> (d3_2 % 2).eq(0) == d3_2_is_even
            True
            >>> ((d3_2 + 1) % 2) == d3_2_is_even
            True
        """
        if other is Sentinel:
            result: dict[_ResultT, int] = {}
            func = cast("Callable[[_T], _ResultT]", func)
            for outcome, count in self._h.items():
                new_outcome = func(outcome)
                result[new_outcome] = result.get(new_outcome, 0) + count
            return H(result)

        func = cast("Callable[[_T, _OtherT], _ResultT]", func)
        if isinstance(other, H):
            return H(
                cast("dict[_ResultT, int]", _h_binary_callable(self._h, other._h, func))  # ruff: ignore[private-member-access]
            )
        else:
            return H(
                cast(
                    "dict[_ResultT, int]", _h_binary_callable(self._h, {other: 1}, func)
                )
            )

    @experimental
    def exactly_k_times_in_n(
        self: "H[_T]",
        outcome: _T,
        n: SupportsInt,
        k: SupportsInt,
    ) -> int:
        r"""
        Computes and returns (in constant time) the number of ways *outcome* appears exactly *k* times among *n* like histograms.

        Uses the binomial coefficient as a more efficient alternative to `(n @ self.eq(outcome))[k]`.

            >>> H(6).exactly_k_times_in_n(outcome=5, n=4, k=2)
            150
            >>> H((2, 3, 3, 4, 4, 5)).exactly_k_times_in_n(outcome=2, n=3, k=3)
            1
            >>> H((2, 3, 3, 4, 4, 5)).exactly_k_times_in_n(outcome=4, n=3, k=3)
            8

        !!! note "Counts, not probabilities"

            This returns a *count* of ways, not a probability, and may not be in lowest terms.
            (See [`lowest_terms`][dyce.H.lowest_terms].)
            Divide by `self.total ** n` to get a probability.
            (See [`total`][dyce.H.total].)

                >>> from fractions import Fraction
                >>> h = H((2, 3, 3, 4, 4, 5))
                >>> n, k = 3, 2
                >>> (n @ h).total == h.total**n
                True
                >>> Fraction(h.exactly_k_times_in_n(outcome=3, n=n, k=k), h.total**n)
                Fraction(2, 9)
                >>> h_not_lowest_terms = H.from_counts(h, h)
                >>> h == h_not_lowest_terms
                True
                >>> h_not_lowest_terms
                H({2: 2, 3: 4, 4: 4, 5: 2})
                >>> h_not_lowest_terms.exactly_k_times_in_n(outcome=3, n=n, k=k)
                384
                >>> Fraction(
                ...     h_not_lowest_terms.exactly_k_times_in_n(outcome=3, n=n, k=k),
                ...     h_not_lowest_terms.total**n,
                ... )
                Fraction(2, 9)
        """
        n = lossless_int(n)
        k = lossless_int(k)

        if k > n:
            raise ValueError(f"k ({k!r}) must be less than or equal to n ({n!r})")

        c_outcome = self.get(outcome, 0)
        return math.comb(n, k) * c_outcome**k * (self.total - c_outcome) ** (n - k)  # type: ignore[no-any-return]

    def format(
        self,
        *,
        precision: int = DEFAULT_PRECISION,
        scaled: bool = False,
        tick: str = "#",
        width: int = _ROW_WIDTH,
    ) -> str:
        r"""
        Returns a formatted string representation of the histogram.

        *precision* is the number of decimal places to use and defaults to `2`.
        *tick* is used as the bar character and defaults to `"#"`.
        *width* must be positive and is the maximum width of the horizontal bar ASCII graph.

            >>> print(
            ...     H.from_counts(
            ...         (2 @ H(6)),
            ...         dict.fromkeys(range(1, 21), 0),
            ...         preserve_zero_counts=True,
            ...     ).format(precision=4, tick="@", width=65)
            ... )
            avg |    7.0000
            std |    2.4152
              1 |   0.0000% |
              2 |   2.7778% |@
              3 |   5.5556% |@@
              4 |   8.3333% |@@@@
              5 |  11.1111% |@@@@@
              6 |  13.8889% |@@@@@@
              7 |  16.6667% |@@@@@@@@
              8 |  13.8889% |@@@@@@
              9 |  11.1111% |@@@@@
             10 |   8.3333% |@@@@
             11 |   5.5556% |@@
             12 |   2.7778% |@
             13 |   0.0000% |
             14 |   0.0000% |
             15 |   0.0000% |
             16 |   0.0000% |
             17 |   0.0000% |
             18 |   0.0000% |
             19 |   0.0000% |
             20 |   0.0000% |

        If *scaled* is `True`, horizontal bars are scaled to *width*.

            >>> h_ge = (2 @ H(6)).ge(7)
            >>> print(f"{' 65 chars wide -->|':->65}")
            ---------------------------------------------- 65 chars wide -->|
            >>> print(H(1).format(scaled=False, width=65))
            avg |    1.00
            std |    0.00
              1 | 100.00% |##################################################
            >>> print(h_ge.format(scaled=False, width=65))
              avg |    0.58
              std |    0.49
            False |  41.67% |####################
             True |  58.33% |############################
            >>> print(h_ge.format(scaled=True, width=65))
              avg |    0.58
              std |    0.49
            False |  41.67% |##################################
             True |  58.33% |################################################
        """
        # Get the length of the fixed-width column " | {<var>:7.2%} |" for computing the
        # available tick space
        prob_width = 5 + precision
        prob_len = len(f" | {0.0:{prob_width}.{precision}%} |")
        try:
            mu: float | None = self.mean()  # type: ignore[misc] # ty: ignore[invalid-argument-type]
            std: float | None = self.stdev()  # type: ignore[misc] # ty: ignore[invalid-argument-type]
        except Exception as exc:  # ruff: ignore[blind-except]
            # Broad catch is intentional: format() is a display method that should
            # always produce output. Any failure to compute statistics (including from
            # runtime type checkers like beartype) is treated as "stats not available"
            # rather than an error.
            warnings.warn(f"{exc!s}", stacklevel=2)
            mu = None
            std = None

        def _lines() -> Iterator[str]:
            # First pass: collect (outcome_str, probability) pairs and find the widest
            # outcome representation. We need max_outcome_len before we can emit
            # anything, because the stats header must align with it.
            pairs: list[tuple[str, Fraction]] = []
            max_outcome_len = 3  # minimum column width
            for outcome, probability in self.probability_items():
                outcome_str = repr(outcome)
                max_outcome_len = max(max_outcome_len, len(outcome_str))
                pairs.append((outcome_str, probability))

            # Stats header (emitted before outcome rows)
            if mu is not None:
                yield f"{'avg': >{max_outcome_len}} | {mu:{prob_width}.{precision}f}"
            if std is not None:
                yield f"{'std': >{max_outcome_len}} | {std:{prob_width}.{precision}f}"

            if pairs:
                tick_scale = max(self.counts()) / self.total if scaled else 1.0
                max_num_ticks = (width - max_outcome_len - prob_len) // len(tick)
                for outcome_str, probability in pairs:
                    ticks = tick * int(max_num_ticks * float(probability) / tick_scale)
                    yield f"{outcome_str: >{max_outcome_len}} | {float(probability):{prob_width}.{precision}%} |{ticks}"

        return os.linesep.join(_lines())

    def format_short(
        self,
        *,
        include_avg: bool = True,
        precision: int = DEFAULT_PRECISION,
    ) -> str:
        r"""
        Returns a short-form formatted string representation of the histogram.

            >>> print(H(6).format_short())
            {avg: 3.50, 1: 16.67%, 2: 16.67%, 3: 16.67%, 4: 16.67%, 5: 16.67%, 6: 16.67%}
            >>> print(
            ...     H(6).format_short(
            ...         include_avg=False,
            ...         precision=3,  # decimal places
            ...     )
            ... )
            {1: 16.667%, 2: 16.667%, 3: 16.667%, 4: 16.667%, 5: 16.667%, 6: 16.667%}
        """
        prob_width = 5 + precision
        mu: float | None = None
        if include_avg:
            try:
                mu = self.mean()  # type: ignore[misc] # ty: ignore[invalid-argument-type]
            except Exception as exc:  # ruff: ignore[blind-except]
                # See format() for rationale
                warnings.warn(f"{exc!s}", stacklevel=2)

        def _parts() -> Iterator[str]:
            if mu is not None:
                yield f"avg: {mu:.2f}"
            yield from (
                f"{outcome!r}:{float(probability):{prob_width}.{precision}%}"
                for outcome, probability in self.probability_items()
            )

        return f"{{{', '.join(_parts())}}}"

    def lowest_terms(self: "H[_T]", *, preserve_zero_counts: bool = False) -> "H[_T]":
        r"""
        Returns a new [`H`][dyce.H] with zero-count outcomes removed and all counts divided by their GCD.

            >>> H({1: 2, 2: 4, 3: 6, 4: 0}).lowest_terms()
            H({1: 1, 2: 2, 3: 3})
            >>> H({1: 3, 2: 0, 3: 6}).lowest_terms()
            H({1: 1, 3: 2})
            >>> H({}).lowest_terms()
            H({})

        If *preserve_zero_counts* is `True`, counts are reduced, but zero counts are kept.

            >>> H({1: 2, 2: 4, 3: 6, 4: 0}).lowest_terms(preserve_zero_counts=True)
            H({1: 1, 2: 2, 3: 3, 4: 0})
        """
        counts = tuple(count for count in self._h.values() if count)
        if not counts:
            return H({})
        g = math.gcd(*counts)
        return H(
            {
                outcome: count // g
                for outcome, count in self._h.items()
                if count or preserve_zero_counts
            }
        )

    def mean(self: "H[SupportsFloat]") -> float:
        r"""
        Returns the mean (expected value) of the weighted outcomes.

        Raises `ValueError` if the histogram is empty.

            >>> H(6).mean()
            3.5
            >>> H({1: 1, 3: 1}).mean()
            2.0
        """
        if not self._h:
            raise ValueError("mean of empty histogram is undefined")
        weighted_outcomes = (
            outcome * count  # type: ignore[operator] # ty: ignore[unsupported-operator]
            for outcome, count in self.items()
        )
        return float(reduce(operator.add, weighted_outcomes) / self.total)

    def merge(
        self: "H[_T]", other: "H[_T] | Mapping[_T, SupportsInt] | Iterable[_T]"
    ) -> "H[_T]":
        r"""
        Merges counts.

            >>> H(4).merge(H(6))
            H({1: 2, 2: 2, 3: 2, 4: 2, 5: 1, 6: 1})
        """
        result: dict[_T, int] = dict(self)
        other_h = other if isinstance(other, H) else H(other)
        for outcome, count in other_h.items():
            result[outcome] = result.get(outcome, 0) + count
        return H(result)

    @experimental
    def order_stat_for_n_at_pos(
        self: "H[_T]",
        n: SupportsInt,
        pos: SupportsInt,
    ) -> "H[_T]":
        r"""
        Computes the probability distribution for each outcome appearing at *pos* among *n* like histograms sorted least-to-greatest.

        *pos* is a zero-based index analogous to `#!math k` in the `#!math k`th order statistic this method implements.

            >>> d6avg = H((2, 3, 3, 4, 4, 5))
            >>> d6avg.order_stat_for_n_at_pos(5, 3)
            H({2: 26, 3: 1432, 4: 4792, 5: 1526})

        The results show that, when rolling five averaging dice and sorting each roll, there are 26 ways where `2` appears at the fourth (index `3`) position, 1,432 ways where `3` appears at the fourth position, etc.

        Negative values for *pos* follow Python index semantics:

            >>> d6 = H(6)
            >>> d6.order_stat_for_n_at_pos(6, 0) == d6.order_stat_for_n_at_pos(6, -6)
            True
            >>> d6.order_stat_for_n_at_pos(6, 5) == d6.order_stat_for_n_at_pos(6, -1)
            True

        This method caches the beta values for *n* so they can be reused for varying values of *pos* in subsequent calls.
        """
        n = lossless_int(n)
        pos = lossless_int(pos)
        if not (-n <= pos < n):
            raise ValueError(f"pos ({pos!r}) must be in range [{-n}, {n})")

        if n not in self._order_stat_funcs_by_n:
            self._order_stat_funcs_by_n[n] = self._order_stat_func_for_n(n)
        if pos < 0:
            pos = n + pos
        return self._order_stat_funcs_by_n[n](pos)

    @overload
    def probability_items(
        self: "H[_T]", rational_t: None = ...
    ) -> Iterator[tuple[_T, Fraction]]: ...
    @overload
    def probability_items(
        self: "H[_T]", rational_t: Callable[[int, int], _OtherT]
    ) -> Iterator[tuple[_T, _OtherT]]: ...
    def probability_items(
        self: "H[_T]", rational_t: Callable[[int, int], _OtherT] | None = None
    ) -> Iterator[tuple[_T, _OtherT]]:
        r"""
        Yields `(outcome, probability)` pairs where each probability is computed as `rational_t(count, total)`.

        *rational_t* defaults to `fractions.Fraction`, giving exact rational probabilities.
        Pass any two-argument callable to get a different representation (e.g. `float` division via `lambda n, d: n / d`).

        Yields nothing if the histogram is empty (total is zero).

            >>> list(H({1: 1, 2: 2, 3: 1}).probability_items())
            [(1, Fraction(1, 4)), (2, Fraction(1, 2)), (3, Fraction(1, 4))]
            >>> from operator import truediv
            >>> list(H({1: 1, 2: 2, 3: 1}).probability_items(truediv))
            [(1, 0.25), (2, 0.5), (3, 0.25)]
            >>> list(H({}).probability_items())
            []
        """
        if rational_t is None:
            rational_t = cast("Callable[[int, int], _OtherT]", Fraction)
        t = self.total
        if not t:
            return
        for outcome, count in self._h.items():
            yield outcome, rational_t(count, t)

    @experimental
    def quantile(self: "H[_T]", numerator: SupportsInt, denominator: SupportsInt) -> _T:
        r"""
        Returns the smallest outcome whose cumulative probability (i.e., including all smaller weighted outcomes) is at least *numerator* / *denominator*.

        It matches NumPy's [`numpy.quantile(outcomes, numerator / denominator, weights=counts, method="inverted_cdf")`](https://numpy.org/doc/stable/reference/generated/numpy.quantile.html) (the step-function quantile appropriate to a discrete distribution), but stays integer-exact rather than rounding through `float`.
        Raises `ValueError` if the histogram is empty, if *denominator* is not positive, or if *numerator* / *denominator* lies outside the closed interval $\left[ 0, 1 \right]$.

            >>> (2 @ H(10)).quantile(1, 3)
            9
            >>> H(6).quantile(0, 1)
            1
            >>> H(6).quantile(1, 2)
            3
            >>> H(6).quantile(1, 1)
            6
        """
        if not self._h:
            raise ValueError("quantile of empty histogram is undefined")
        numerator = lossless_int(numerator)
        denominator = lossless_int(denominator)
        if denominator <= 0:
            raise ValueError(f"denominator ({denominator!r}) must be positive")
        if not 0 <= numerator <= denominator:
            raise ValueError(
                f"numerator / denominator ({numerator}/{denominator}) must be in the interval [0, 1]"
            )
        # `cumulative / total >= numerator / denominator` cross-multiplies to
        # `cumulative * denominator >= numerator * total` for `denominator > 0 and total
        # > 0` (i.e., no sign flip)
        scaled_target = numerator * self.total
        cumulative = 0
        for outcome, count in self.items():
            cumulative += count
            if cumulative * denominator >= scaled_target:
                return outcome
        raise AssertionError(
            "unreachable: cumulative reaches total"
        )  # pragma: no cover

    @overload
    def quantize_counts(
        self: "H[Never]",
        bit_width: int = ...,
        *,
        preserve_zero_counts: bool = False,
    ) -> "H[Never]": ...
    @overload
    def quantize_counts(
        self: "H[_T]",
        bit_width: int = ...,
        *,
        preserve_zero_counts: bool = False,
    ) -> "H[_T]": ...
    @experimental
    def quantize_counts(
        self,
        bit_width: int = DEFAULT_QUANTIZATION_BIT_WIDTH,
        *,
        preserve_zero_counts: bool = False,
    ) -> "H[Any]":
        r"""
        Constructs an [`H`][dyce.H] by “quantizing” its counts such that no count occupies more than *bit_width* bits.

        Proportions are approximated.
        If *preserve_zero_counts* is `True`, outcomes are retained even if their counts are reduced to `0`.

            >>> H.quantize_counts(
            ...     H({1: 0x100, 2: 0x400, 3: 0x200, 4: 0x80, 5: 0xFFFF, 6: 0x7F}),
            ...     bit_width=8,
            ... )
            H({1: 1, 2: 4, 3: 2, 4: 1, 5: 255})
            >>> H.quantize_counts(
            ...     H({1: 0x400, 2: 0x1000, 3: 0xF, 4: 0x10, 5: 0}),
            ...     bit_width=8,
            ...     preserve_zero_counts=True,
            ... )
            H({1: 32, 2: 128, 3: 0, 4: 1, 5: 0})
        """
        quantized = _quantize_counts(
            self, bit_width, preserve_zero_counts=preserve_zero_counts
        )
        return self if quantized is self else type(self)(quantized)

    @experimental
    def sample(self: "H[_T]") -> _T:
        r"""
        <!-- BEGIN MONKEY PATCH --
        For deterministic outcomes.

        >>> import random
        >>> from dyce import rng
        >>> rng.RNG = random.Random(1774583876)

          -- END MONKEY PATCH -->

        Returns a (weighted) random outcome.

            >>> d6 = H(6)
            >>> [d6.sample() for _ in range(10)]
            [2, 6, 1, 2, 4, 5, 1, 4, 2, 5]
        """
        from . import rng

        if not self:
            raise ValueError("no outcomes in an empty histogram")
        return rng.RNG.choices(
            population=tuple(self.outcomes()),
            weights=tuple(self.counts()),
            k=1,
        )[0]

    def stdev(self: "H[SupportsFloat]") -> float:
        r"""
        Returns the standard deviation of the weighted outcomes as a `float`.

        Raises `ValueError` if the histogram is empty.

            >>> H(6).stdev()
            1.707825...
            >>> H({1: 1, 3: 1}).stdev()
            1.0
        """
        return math.sqrt(self.variance())

    def variance(self: "H[SupportsFloat]") -> float:
        r"""
        Returns the variance of the weighted outcomes as a `float`.

        Raises `ValueError` if the histogram is empty.

            >>> H(6).variance()
            2.916666...
            >>> H({1: 1, 3: 1}).variance()
            1.0
        """
        return (
            sum(
                (
                    count / self.total * float(outcome) ** 2
                    for outcome, count in self._h.items()
                ),
                start=0.0,
            )
            - self.mean() ** 2
        )

    def _order_stat_func_for_n(self: "H[_T]", n: int) -> "Callable[[int], H[_T]]":
        cumulative = 0
        betas: list[tuple[_T, int, int]] = []
        total = self.total
        for outcome, count in self.items():
            c_lt = cumulative
            c_le = cumulative + count
            betas.append((outcome, c_lt, c_le))
            cumulative = c_le

        def _order_stat_at_pos(pos: int) -> "H[_T]":
            # Two endpoint fast paths reduce the inner binomial sum to a single
            # closed-form term per outcome. Both also carry `prev_term` across
            # iterations so each outcome does ONE pow operation rather than two.
            #
            # pos == n - 1 (max): only k == n contributes; the sum is just `c_le^n`.
            # Difference between adjacent outcomes is `cur_term - prev_term`.
            #
            # pos == 0 (min): the n-term sum from k == 1 to k == n collapses via the
            # binomial theorem -- `(c + (T-c))^n` minus the k == 0 term `(T-c)^n` -- to
            # `T^n - (T-c)^n`. Two adjacent outcomes' difference is `(T-c_lt)^n -
            # (T-c_le)^n`. Empirically this is ~280x faster than the general path for `n
            # == 100`, `num_outcomes == 100`.
            if pos == n - 1:
                # k_range -> range(n, n+1) -> (n,)
                # math.comb(n, n)  # -> 1  # ruff: ignore[commented-out-code]
                # * c_le**n
                # * (total - c_le) ** (n-n)  # -> 1  # ruff: ignore[commented-out-code]
                counts: dict[_T, int] = {}
                prev_term = 0  # 0^n == 0 for n >= 1
                for outcome, _c_lt, c_le in betas:
                    cur_term = c_le**n
                    counts[outcome] = cur_term - prev_term
                    prev_term = cur_term
                return H(counts)
            elif pos == 0:
                # k_range -> range(1) -> (0,)
                # math.comb(n, 0)  # -> 1  # ruff: ignore[commented-out-code]
                # * c_le**0  # -> 1
                # * (total - c_le) ** (n-0)  # ruff: ignore[commented-out-code]
                counts = {}
                prev_term = total**n  # (T-0)^n
                for outcome, _c_lt, c_le in betas:
                    cur_term = (total - c_le) ** n
                    counts[outcome] = prev_term - cur_term
                    prev_term = cur_term
                return H(counts)
            # General middle-position fallback. Two equivalent formulations differ only
            # in which side of the binomial sum gets evaluated:
            #
            #   direct (n - pos terms):     Σ_{k=pos+1}^{n} C(n,k) c^k (T-c)^(n-k)
            #
            #   complement (pos + 1 terms): T^n - Σ_{k=0}^{pos} C(n,k) c^k (T-c)^(n-k)
            #
            # The `T^n` cancels in the c_le-vs-c_lt subtraction, so the complement form
            # just swaps which sum is subtracted from which. Pick whichever has fewer
            # terms.
            elif pos + 1 < n - pos:
                k_range = range(pos + 1)
                return H(
                    {
                        # For each outcome-beta
                        outcome: (
                            # This first sum (with c_lt^k * (T-c_lt)^(n-k)): counts the
                            # n-tuples where AT MOST pos of the n rolls are strictly
                            # less than outcome x.
                            #
                            # Each term C(n,k) * c_lt^k * (T-c_lt)^(n-k) is: "choose
                            # which k positions hold a roll < x (there are c_lt ways per
                            # position), and the remaining n-k positions hold rolls ≥ x
                            # (there are T - c_lt ways per position)." Sum over k from 0
                            # to pos.
                            sum(
                                # The number of ways to choose k items from a set of n
                                # items (n choose k)
                                math.comb(n, k)
                                # The cumulative count of outcomes less than this one to
                                # the kth power
                                * c_lt**k
                                # The remaining counts taken to the power of the
                                # remaining positions
                                * (total - c_lt) ** (n - k)
                                # Summed for all positions [0, k]
                                for k in k_range
                            )
                            -
                            # This second sum (with c_le^k * (total - c_le)^(n-k)):
                            # counts n-tuples where AT MOST pos of the rolls are less
                            # than or equal to x.
                            sum(
                                # n choose k (computed again)
                                math.comb(n, k)
                                # The cumulative count of outcomes including this one to
                                # the kth power
                                * c_le**k
                                # The remaining counts taken to the power of the
                                # remaining positions
                                * (total - c_le) ** (n - k)
                                # Summed for all positions [0, k]
                                for k in k_range
                            )
                            # This difference captures "x is at position pos" precisely
                            # because:
                            #
                            # - "x is at position pos in the sorted list" is the joint
                            #   event:
                            #   - At MOST pos rolls are strictly less than x (otherwise
                            #     something < x would push x to a later position), AND
                            #   - At LEAST pos + 1 rolls are less than or equal to x
                            #     (otherwise x couldn't even be present at position
                            #     pos).
                            # - "At most pos rolls < x" MINUS "at most pos rolls ≤ x" =
                            #   "at most pos rolls < x AND more than pos rolls ≤ x" =
                            #   exactly the joint event above. The rolls that are ≤ x
                            #   but not < x are rolls equal to x — so the difference
                            #   counts configurations where enough rolls equal x to push
                            #   x into position pos.
                        )
                        for outcome, c_lt, c_le in betas
                    }
                )
            else:  # pos + 1 >= n - pos
                k_range = range(pos + 1, n + 1)
                return H(
                    {
                        outcome: (
                            sum(
                                math.comb(n, k) * c_le**k * (total - c_le) ** (n - k)
                                for k in k_range
                            )
                            - sum(
                                math.comb(n, k) * c_lt**k * (total - c_lt) ** (n - k)
                                for k in k_range
                            )
                        )
                        for outcome, c_lt, c_le in betas
                    }
                )

        return _order_stat_at_pos