Skip to content

Commit 8764a6f

Browse files
bpo-29710: Clarify documentation for Bitwise binary operation (GH-1691)
Mathematically, bitwise operations on integers behave as if there were an infinite number of sign bits. Pragmatically, that gives the same answer as using one extra sign bit for the bitwise logical operations. (cherry picked from commit b4bc5ca) Co-authored-by: Sanyam Khurana <[email protected]>
1 parent 83b449d commit 8764a6f

File tree

1 file changed

+13
-7
lines changed

1 file changed

+13
-7
lines changed

Doc/library/stdtypes.rst

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -382,7 +382,7 @@ modules.
382382
.. _bitstring-ops:
383383

384384
Bitwise Operations on Integer Types
385-
--------------------------------------
385+
-----------------------------------
386386

387387
.. index::
388388
triple: operations on; integer; types
@@ -396,9 +396,9 @@ Bitwise Operations on Integer Types
396396
operator: >>
397397
operator: ~
398398

399-
Bitwise operations only make sense for integers. Negative numbers are treated
400-
as their 2's complement value (this assumes that there are enough bits so that
401-
no overflow occurs during the operation).
399+
Bitwise operations only make sense for integers. The result of bitwise
400+
operations is calculated as though carried out in two's complement with an
401+
infinite number of sign bits.
402402

403403
The priorities of the binary bitwise operations are all lower than the numeric
404404
operations and higher than the comparisons; the unary operation ``~`` has the
@@ -409,13 +409,13 @@ This table lists the bitwise operations sorted in ascending priority:
409409
+------------+--------------------------------+----------+
410410
| Operation | Result | Notes |
411411
+============+================================+==========+
412-
| ``x | y`` | bitwise :dfn:`or` of *x* and | |
412+
| ``x | y`` | bitwise :dfn:`or` of *x* and | (4) |
413413
| | *y* | |
414414
+------------+--------------------------------+----------+
415-
| ``x ^ y`` | bitwise :dfn:`exclusive or` of | |
415+
| ``x ^ y`` | bitwise :dfn:`exclusive or` of | (4) |
416416
| | *x* and *y* | |
417417
+------------+--------------------------------+----------+
418-
| ``x & y`` | bitwise :dfn:`and` of *x* and | |
418+
| ``x & y`` | bitwise :dfn:`and` of *x* and | (4) |
419419
| | *y* | |
420420
+------------+--------------------------------+----------+
421421
| ``x << n`` | *x* shifted left by *n* bits | (1)(2) |
@@ -438,6 +438,12 @@ Notes:
438438
A right shift by *n* bits is equivalent to division by ``pow(2, n)`` without
439439
overflow check.
440440

441+
(4)
442+
Performing these calculations with at least one extra sign extension bit in
443+
a finite two's complement representation (a working bit-width of
444+
``1 + max(x.bit_length(), y.bit_length()`` or more) is sufficient to get the
445+
same result as if there were an infinite number of sign bits.
446+
441447

442448
Additional Methods on Integer Types
443449
-----------------------------------

0 commit comments

Comments
 (0)