From 1df77689c0f1e4c08c8333e2105bd88abed89a49 Mon Sep 17 00:00:00 2001 From: CuriousLearner Date: Sun, 21 May 2017 10:02:54 +0530 Subject: [PATCH 1/5] bpo-29710: Clarify documentation for Bitwise binary operation --- Doc/library/stdtypes.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 8f0a080bd6e0482..5fa3ca10fd6df13 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -400,8 +400,7 @@ Bitwise Operations on Integer Types 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). +as their 2's complement value. The priorities of the binary bitwise operations are all lower than the numeric operations and higher than the comparisons; the unary operation ``~`` has the @@ -441,6 +440,11 @@ Notes: A right shift by *n* bits is equivalent to division by ``pow(2, n)`` without overflow check. +(4) + Bitwise binary operations are semantically equivalent to calculations + using 2's complement in a bit-width of ``1 + max(x.bit_length(), y + .bit_length()``. + Additional Methods on Integer Types ----------------------------------- From a3d60fec673abb1b80ee53691d621d43adc648d0 Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Tue, 5 Dec 2017 12:50:48 +0530 Subject: [PATCH 2/5] Address review comments; reference footnotes --- Doc/library/stdtypes.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 5fa3ca10fd6df13..e129de3c1f5268e 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -411,13 +411,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) | From 7421edf9b2adabdd8d41568f7382ffefb3840714 Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Sat, 14 Jul 2018 19:26:47 +0530 Subject: [PATCH 3/5] bpo-29710: Fix docs in stdtypes addressing review comments --- Doc/library/stdtypes.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 95fab135522427b..4480733e962bd9f 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -438,9 +438,11 @@ Notes: overflow check. (4) - Bitwise binary operations are semantically equivalent to calculations - using 2's complement in a bit-width of ``1 + max(x.bit_length(), y - .bit_length()``. + Each bitwise operation has the same result as though carried out in two's + complement with an infinite number of sign bits. In practice, performing the + calculation with one extra sign extension bit (a bit-width of + ``1 + max(x.bit_length(), y.bit_length()``) is sufficient to get the + expected result. Additional Methods on Integer Types From 73ce0102a2c298bf7bf176334ad59b882ae5db8b Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Sat, 21 Jul 2018 13:14:10 +0530 Subject: [PATCH 4/5] Address review comments --- Doc/library/stdtypes.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 4480733e962bd9f..43dc970f015eb89 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -438,11 +438,10 @@ Notes: overflow check. (4) - Each bitwise operation has the same result as though carried out in two's - complement with an infinite number of sign bits. In practice, performing the - calculation with one extra sign extension bit (a bit-width of - ``1 + max(x.bit_length(), y.bit_length()``) is sufficient to get the - expected result. + 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 From 8855467caa94a9a83fb38f5f67b77dd7f60e4418 Mon Sep 17 00:00:00 2001 From: Sanyam Khurana Date: Tue, 24 Jul 2018 00:48:52 +0530 Subject: [PATCH 5/5] Address review comments --- Doc/library/stdtypes.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 43dc970f015eb89..68134bfa2e4e672 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,8 +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. +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