[Python-checkins] bpo-29710: Clarify documentation for Bitwise binary operation (GH-1691)

Miss Islington (bot) webhook-mailer at python.org
Sat Jul 28 12:52:35 EDT 2018


https://github.com/python/cpython/commit/3100b7e710dccdcfbc6991ea7e8985a1881d42e6
commit: 3100b7e710dccdcfbc6991ea7e8985a1881d42e6
branch: 3.6
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2018-07-28T09:52:31-07:00
summary:

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 b4bc5cab82e6855e4ebc33ba0b669ddffad30fb3)

Co-authored-by: Sanyam Khurana <8039608+CuriousLearner at users.noreply.github.com>

files:
M Doc/library/stdtypes.rst

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 1df2148cbb9e..d740688d88a2 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -382,7 +382,7 @@ modules.
 .. _bitstring-ops:
 
 Bitwise Operations on Integer Types
---------------------------------------
+-----------------------------------
 
 .. index::
    triple: operations on; integer; types
@@ -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
@@ -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)   |
@@ -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
 -----------------------------------



More information about the Python-checkins mailing list