bpo-29710: Clarify documentation for Bitwise binary operation by CuriousLearner · Pull Request #1691 · python/cpython (original) (raw)

Expand Up

@@ -382,7 +382,7 @@ modules.

.. _bitstring-ops:

Bitwise Operations on Integer Types

--------------------------------------

-----------------------------------

.. index::

triple: operations on; integer; types

Expand All

@@ -396,9 +396,9 @@ Bitwise Operations on Integer Types

operator: >>

operator: ~

Bitwise operations only make sense for integers. Negative numbers are treated

as their 2's complement value (this assumes that there are enough bits so that

no overflow occurs during the operation).

Bitwise operations only make sense for integers. The result of bitwise

operations is calculated as though carried out in two's complement with an

infinite number of sign bits.

The priorities of the binary bitwise operations are all lower than the numeric

operations and higher than the comparisons; the unary operation ``~`` has the

Expand All

@@ -409,13 +409,13 @@ This table lists the bitwise operations sorted in ascending priority:

+------------+--------------------------------+----------+

| Operation | Result | Notes |

+============+================================+==========+

| ``x | y`` | bitwise :dfn:`or` of *x* and | |

| ``x | y`` | bitwise :dfn:`or` of *x* and | (4) |

| | *y* | |

+------------+--------------------------------+----------+

| ``x ^ y`` | bitwise :dfn:`exclusive or` of | |

| ``x ^ y`` | bitwise :dfn:`exclusive or` of | (4) |

| | *x* and *y* | |

+------------+--------------------------------+----------+

| ``x & y`` | bitwise :dfn:`and` of *x* and | |

| ``x & y`` | bitwise :dfn:`and` of *x* and | (4) |

| | *y* | |

+------------+--------------------------------+----------+

| ``x << n`` | *x* shifted left by *n* bits | (1)(2) |

Expand All

@@ -438,6 +438,12 @@ Notes:

A right shift by *n* bits is equivalent to division by ``pow(2, n)`` without

overflow check.

(4)

Performing these calculations with at least one extra sign extension bit in

a finite two's complement representation (a working bit-width of

``1 + max(x.bit_length(), y.bit_length()`` or more) is sufficient to get the

same result as if there were an infinite number of sign bits.

Additional Methods on Integer Types

-----------------------------------

Expand Down