# Copyright cocotb contributors
# Licensed under the Revised BSD License, see LICENSE for details.
# SPDX-License-Identifier: BSD-3-Clause
from __future__ import annotations
import copy
from collections.abc import Iterator, Sequence
from functools import cache
from typing import Any, overload
class Range(Sequence[int]):
r"""
Variant of :class:`range` with inclusive right bound.
In Python, :class:`range` and :class:`slice` have a non-inclusive right bound.
In both Verilog and VHDL, ranges and arrays have an inclusive right bound.
This type mimics Python's :class:`range` type, but implements HDL-like inclusive right bounds,
using the names :attr:`left` and :attr:`right` as replacements for ``start`` and ``stop`` to
match VHDL.
Range directionality can be specified using ``'to'`` or ``'downto'`` between the
left and right bounds.
Not specifying directionality will cause the directionality to be inferred.
.. code-block:: pycon3
>>> r = Range(-2, 3)
>>> r.left, r.right, len(r)
(-2, 3, 6)
>>> s = Range(8, "downto", 1)
>>> s.left, s.right, len(s)
(8, 1, 8)
:meth:`from_range` and :meth:`to_range` can be used to convert from and to :class:`range`.
.. code-block:: pycon3
>>> r = Range(-2, 3)
>>> r.to_range()
range(-2, 4)
:class:`Range` supports "null" ranges as seen in VHDL.
"null" ranges occur when a left bound cannot reach a right bound with the given direction.
They have a length of ``0``, but the :attr:`left`, :attr:`right`, and :attr:`direction` values remain as given.
.. code-block:: pycon3
>>> r = Range(1, "to", 0) # no way to count from 1 'to' 0
>>> r.left, r.direction, r.right
(1, 'to', 0)
>>> len(r)
0
.. note::
This is only possible when specifying the direction.
Ranges also support all the features of :class:`range` including, but not limited to:
- ``value in range`` to see if a value is in the range,
- ``range.index(value)`` to see what position in the range the value is,
The typical use case of this type is in conjunction with :class:`~cocotb.types.Array`.
Args:
left: Leftmost bound of range.
direction: ``'to'`` if values are ascending, ``'downto'`` if descending.
right: Rightmost bound of range (inclusive).
"""
@overload
def __init__(self, left: int, direction: int) -> None: ...
@overload
def __init__(self, left: int, direction: str, right: int) -> None: ...
@overload
def __init__(self, left: int, *, right: int) -> None: ...
def __init__(
self,
left: int,
direction: int | str | None = None,
right: int | None = None,
) -> None:
start = left
stop: int
step: int
if isinstance(direction, int) and right is None:
step = _guess_step(left, direction)
stop = direction + step
elif isinstance(direction, str) and isinstance(right, int):
step = _direction_to_step(direction)
stop = right + step
elif direction is None and isinstance(right, int):
step = _guess_step(left, right)
stop = right + step
else:
raise TypeError("invalid arguments")
self._range = range(start, stop, step)
[docs]
@classmethod
def from_range(cls, range: range) -> Range:
"""Convert :class:`range` to :class:`Range`."""
return cls(
left=range.start,
direction=_step_to_direction(range.step),
right=(range.stop - range.step),
)
[docs]
def to_range(self) -> range:
"""Convert Range to :class:`range`."""
return self._range
@property
def left(self) -> int:
"""Leftmost value in a Range."""
return self._range.start
@property
def direction(self) -> str:
"""``'to'`` if Range is ascending, ``'downto'`` otherwise."""
return _step_to_direction(self._range.step)
@property
def right(self) -> int:
"""Rightmost value in a Range."""
return self._range.stop - self._range.step
def __len__(self) -> int:
return len(self._range)
@overload
def __getitem__(self, item: int) -> int: ...
@overload
def __getitem__(self, item: slice) -> Range: ...
def __getitem__(self, item: int | slice) -> int | Range:
if isinstance(item, int):
return self._range[item]
elif isinstance(item, slice):
return type(self).from_range(self._range[item])
raise TypeError(
f"indices must be integers or slices, not {type(item).__name__}"
)
def __contains__(self, item: object) -> bool:
return item in self._range
def __iter__(self) -> Iterator[int]:
return iter(self._range)
def __reversed__(self) -> Iterator[int]:
return reversed(self._range)
def __eq__(self, other: object) -> bool:
if isinstance(other, type(self)):
return self._range == other._range
return NotImplemented # must not be in a type narrowing context to be ignored properly
def __hash__(self) -> int:
return hash(self._range)
def __repr__(self) -> str:
return f"{type(self).__qualname__}({self.left!r}, {self.direction!r}, {self.right!r})"
def index(
self, value: Any, start: int | None = None, stop: int | None = None, /
) -> int:
if start is not None or stop is not None:
if start is None:
start = self._range.start
if stop is None:
stop = self._range.stop
return super().index(value, start, stop)
return self._range.index(value)
def __copy__(self) -> Range:
return Range.from_range(self._range)
def __deepcopy__(self, memo: dict[int, Any]) -> Range:
return Range.from_range(copy.deepcopy(self._range, memo=memo))
def _guess_step(left: int, right: int) -> int:
if left <= right:
return 1
return -1
@cache
def _direction_to_step(direction: str) -> int:
direction = direction.lower()
if direction == "to":
return 1
elif direction == "downto":
return -1
raise ValueError("direction must be 'to' or 'downto'")
def _step_to_direction(step: int) -> str:
if step == 1:
return "to"
elif step == -1:
return "downto"
raise ValueError("step must be 1 or -1")
