Skip to content

bpo-29710: Clarify documentation for Bitwise binary operation #1691

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 6 commits into from
Jul 28, 2018
Merged

bpo-29710: Clarify documentation for Bitwise binary operation #1691

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1df7768
bpo-29710: Clarify documentation for Bitwise binary operation
CuriousLearner May 21, 2017
a3d60fe
Address review comments; reference footnotes
CuriousLearner Dec 5, 2017
11c1706
Merge branch 'master' into bitwise_docs
CuriousLearner Jul 14, 2018
7421edf
bpo-29710: Fix docs in stdtypes addressing review comments
CuriousLearner Jul 14, 2018
73ce010
Address review comments
CuriousLearner Jul 21, 2018
8855467
Address review comments
CuriousLearner Jul 23, 2018
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
20 changes: 13 additions & 7 deletions Doc/library/stdtypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Forgot to add references to the new footnote?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vadmium How should I reference it? Is this what is required?

index 5fa3ca10fd..40129f0037 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -400,7 +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.
+as their 2's complement value (4).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you are trying to follow Nick’s suggestion (move the note about negative numbers to a numbered footnote in the table), I think he was suggesting adding (4) to the table that the other three footnotes relate to, specifically to each of the first three rows for x | y, x ^ y, and x & y. These are bitwise binary operations and they define x and y.

However I am not enthusiastic about the new text; see my comments in the bug thread.

Copy link
Member Author

@CuriousLearner CuriousLearner Dec 10, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, what do you think about Nick's suggestion, where he included Mark's suggestion as well:

Each bitwise operation has the same result as though carried out in two's complement using a bit-width that's large enough to represent the inputs. ("Large enough" for this purpose is ``1 + max(x.bit_length(), y .bit_length()``, with the extra bit being needed to handle sign extension appropriately)

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