usb-tools/amaranth
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs/reference: finish Value section.

Browse source
This commit is contained in:
Catherine 2024-03-25 15:48:41 +00:00
parent cd51e02de2
commit 3d5c36a606
2 changed files with 30 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
amaranth/hdl/_ast.py
View file

@ -466,7 +466,7 @@ class Value(metaclass=ABCMeta):
value-castable objects, and the Amaranth standard library provides several built-in ones: value-castable objects, and the Amaranth standard library provides several built-in ones:
* :mod:`amaranth.lib.enum` classes are a drop-in replacement for the standard Python * :mod:`amaranth.lib.enum` classes are a drop-in replacement for the standard Python
:class:`enum` classes that can be defined with an Amaranth shape; :mod:`enum` classes that can be defined with an Amaranth shape;
* :mod:`amaranth.lib.data` classes allow defining complex data structures such as structures * :mod:`amaranth.lib.data` classes allow defining complex data structures such as structures
and unions. and unions.
@ -1087,22 +1087,35 @@ class Value(metaclass=ABCMeta):
def __getitem__(self, key): def __getitem__(self, key):
"""Bit slicing. """Bit slicing.
.. todo:: Selects a constant-width, constant-offset part of :py:`self`. All three slicing syntaxes
(:py:`self[i]`, :py:`self[i:j]`, and :py:`self[i:j:k]`) as well as negative indices are
supported. Like with other Python containers, out-of-bounds indices are trimmed to
the bounds of :py:`self`.
Describe this operation. To select a variable-offset part of :py:`self`, use :meth:`bit_select` or
:meth:`word_select` instead.
Returns
-------
:class:`Value`, :py:`unsigned(1)`, :ref:`assignable <lang-assignable>`
If :py:`key` is an :class:`int`.
:class:`Value`, :py:`unsigned(j - i)`, :ref:`assignable <lang-assignable>`
If :py:`key` is a slice :py:`i:j` where :py:`i` and :py:`j` are :class:`int`\\ s.
:class:`Value`, :py:`unsigned(len(range(*slice(i, j, k).indices(len(self)))))`, :ref:`assignable <lang-assignable>`
If :py:`key` is a slice :py:`i:j:k` where :py:`i`, :py:`j`, and :py:`k` are :class:`int`\\ s.
""" """
n = len(self) length = len(self)
if isinstance(key, int): if isinstance(key, int):
if key not in range(-n, n): if key not in range(-length, length):
raise IndexError(f"Index {key} is out of bounds for a {n}-bit value") raise IndexError(f"Index {key} is out of bounds for a {length}-bit value")
if key < 0: if key < 0:
key += n key += length
return Slice(self, key, key + 1, src_loc_at=1) return Slice(self, key, key + 1, src_loc_at=1)
elif isinstance(key, slice): elif isinstance(key, slice):
if isinstance(key.start, Value) or isinstance(key.stop, Value): if isinstance(key.start, Value) or isinstance(key.stop, Value):
raise TypeError(f"Cannot slice value with a value; use Value.bit_select() or " raise TypeError(f"Cannot slice value with a value; use Value.bit_select() or "
f"Value.word_select() instead") f"Value.word_select() instead")
start, stop, step = key.indices(n) start, stop, step = key.indices(length)
if step != 1: if step != 1:
return Cat(self[i] for i in range(start, stop, step)) return Cat(self[i] for i in range(start, stop, step))
return Slice(self, start, stop, src_loc_at=1) return Slice(self, start, stop, src_loc_at=1)
@ -1220,14 +1233,19 @@ class Value(metaclass=ABCMeta):
"""Pattern matching. """Pattern matching.
Matches against a set of patterns, recognizing the same grammar as :py:`with m.Case()`. Matches against a set of patterns, recognizing the same grammar as :py:`with m.Case()`.
The pattern syntax is described in the :ref:`language guide <lang-matchop>`.
.. todo:: Each of the :py:`patterns` may be a :class:`str` or a :ref:`constant-castable object
<lang-constcasting>`.
Describe the pattern language in detail.
Returns Returns
------- -------
:class:`Value`, :py:`unsigned(1)` :class:`Value`, :py:`unsigned(1)`
Raises
------
:exc:`SyntaxError`
If a pattern has invalid syntax.
""" """
matches = [] matches = []
# This code should accept exactly the same patterns as `with m.Case(...):`. # This code should accept exactly the same patterns as `with m.Case(...):`.