Skip to content

docs/{guide,reference}: clarify semantics of a.any() vs a.bool() #1263

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 3, 2024
Merged

docs/{guide,reference}: clarify semantics of a.any() vs a.bool() #1263

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions amaranth/hdl/_ast.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -622,7 +622,8 @@ def __bool__(self):
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
-------
Expand Down Expand Up @@ -934,6 +935,9 @@ def __ror__(self, other):
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)`
Expand Down Expand Up @@ -2022,7 +2026,7 @@ def __init__(self, shape=None, *, name=None, init=None, reset=None, reset_less=F

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:
Expand Down
7 changes: 4 additions & 3 deletions docs/guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down