From 967dabc2fe3015ed965e7e1c24b06e030a50e1fa Mon Sep 17 00:00:00 2001 From: Catherine Date: Wed, 3 Apr 2024 08:39:45 +0000 Subject: [PATCH] docs/{guide,reference}: clarify semantics of `a.any()` vs `a.bool()`. --- amaranth/hdl/_ast.py | 8 ++++++-- docs/guide.rst | 7 ++++--- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/amaranth/hdl/_ast.py b/amaranth/hdl/_ast.py index 4bfa39a..9358072 100644 --- a/amaranth/hdl/_ast.py +++ b/amaranth/hdl/_ast.py @@ -622,7 +622,8 @@ class Value(metaclass=ABCMeta): def bool(self): """Conversion to boolean. - Performs the same operation as :meth:`any`. + Returns the same value as :meth:`any`, but should be used where :py:`self` is semantically + a number. Returns ------- @@ -934,6 +935,9 @@ class Value(metaclass=ABCMeta): def any(self): """Reduction OR; is any bit :py:`1`? + Performs the same operation as :meth:`bool`, but should be used where :py:`self` is + semantically a bit sequence. + Returns ------- :class:`Value`, :py:`unsigned(1)` @@ -2072,7 +2076,7 @@ class Signal(Value, DUID, metaclass=_SignalMeta): if decoder is not None: # The value representation is specified explicitly. Since we do not expose `hdl._repr`, - # this is the only way to add a custom filter to the signal right now. + # this is the only way to add a custom filter to the signal right now. if isinstance(decoder, type) and issubclass(decoder, Enum): self._value_repr = (_repr.Repr(_repr.FormatEnum(decoder), self),) else: diff --git a/docs/guide.rst b/docs/guide.rst index 6bb5f41..efa0372 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -610,13 +610,14 @@ The following table lists the reduction operations provided by Amaranth: Operation Description Notes ============ ============================================= ====== ``a.all()`` reduction AND; are all bits set? [#opR1]_ -``a.any()`` reduction OR; is any bit set? [#opR1]_ +``a.any()`` reduction OR; is any bit set? [#opR1]_ [#opR3]_ ``a.xor()`` reduction XOR; is an odd number of bits set? -``a.bool()`` conversion to boolean; is non-zero? [#opR2]_ +``a.bool()`` conversion to boolean; is non-zero? [#opR2]_ [#opR3]_ ============ ============================================= ====== .. [#opR1] Conceptually the same as applying the Python :func:`all` or :func:`any` function to the value viewed as a collection of bits. -.. [#opR2] Conceptually the same as applying the Python :func:`bool` function to the value viewed as an integer. +.. [#opR2] Conceptually the same as applying the Python :class:`bool` function to the value viewed as an integer. +.. [#opR3] While the :meth:`Value.any()` and :meth:`Value.bool` operators return the same value, the use of ``a.any()`` implies that ``a`` is semantically a bit sequence, and the use of ``a.bool()`` implies that ``a`` is semantically a number. .. _lang-logicops: