[Python-checkins] r63055 - in python/trunk/Doc: library/exceptions.rst library/stdtypes.rst reference/datamodel.rst reference/expressions.rst

[georg.brandl]

Author: georg.brandl
Date: Sun May 11 12:55:59 2008
New Revision: 63055

Log:
#2147: PEP 237 changes to overflow behavior.


Modified:
   python/trunk/Doc/library/exceptions.rst
   python/trunk/Doc/library/stdtypes.rst
   python/trunk/Doc/reference/datamodel.rst
   python/trunk/Doc/reference/expressions.rst

Modified: python/trunk/Doc/library/exceptions.rst
==============================================================================
--- python/trunk/Doc/library/exceptions.rst	(original)
+++ python/trunk/Doc/library/exceptions.rst	Sun May 11 12:55:59 2008
@@ -254,11 +254,10 @@
 
    Raised when the result of an arithmetic operation is too large to be
    represented.  This cannot occur for long integers (which would rather raise
-   :exc:`MemoryError` than give up).  Because of the lack of standardization of
-   floating point exception handling in C, most floating point operations also
-   aren't checked.  For plain integers, all operations that can overflow are
-   checked except left shift, where typical applications prefer to drop bits than
-   raise an exception.
+   :exc:`MemoryError` than give up) and for most operations with plain integers,
+   which return a long integer instead.  Because of the lack of standardization
+   of floating point exception handling in C, most floating point operations
+   also aren't checked.
 
 
 .. exception:: ReferenceError

Modified: python/trunk/Doc/library/stdtypes.rst
==============================================================================
--- python/trunk/Doc/library/stdtypes.rst	(original)
+++ python/trunk/Doc/library/stdtypes.rst	Sun May 11 12:55:59 2008
@@ -406,8 +406,7 @@
 operations and higher than the comparisons; the unary operation ``~`` has the
 same priority as the other unary numeric operations (``+`` and ``-``).
 
-This table lists the bit-string operations sorted in ascending priority
-(operations in the same box have the same priority):
+This table lists the bit-string operations sorted in ascending priority:
 
 +------------+--------------------------------+----------+
 | Operation  | Result                         | Notes    |
@@ -440,12 +439,11 @@
    Negative shift counts are illegal and cause a :exc:`ValueError` to be raised.
 
 (2)
-   A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)``
-   without overflow check.
+   A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)``.  A
+   long integer is returned if the result exceeds the range of plain integers.
 
 (3)
-   A right shift by *n* bits is equivalent to division by ``pow(2, n)`` without
-   overflow check.
+   A right shift by *n* bits is equivalent to division by ``pow(2, n)``.
 
 
 .. _typeiter:

Modified: python/trunk/Doc/reference/datamodel.rst
==============================================================================
--- python/trunk/Doc/reference/datamodel.rst	(original)
+++ python/trunk/Doc/reference/datamodel.rst	Sun May 11 12:55:59 2008
@@ -175,23 +175,24 @@
             object: plain integer
             single: OverflowError (built-in exception)
 
-         These represent numbers in the range -2147483648 through 2147483647. (The range
-         may be larger on machines with a larger natural word size, but not smaller.)
-         When the result of an operation would fall outside this range, the result is
-         normally returned as a long integer (in some cases, the exception
-         :exc:`OverflowError` is raised instead). For the purpose of shift and mask
-         operations, integers are assumed to have a binary, 2's complement notation using
-         32 or more bits, and hiding no bits from the user (i.e., all 4294967296
-         different bit patterns correspond to different values).
+         These represent numbers in the range -2147483648 through 2147483647.
+         (The range may be larger on machines with a larger natural word size,
+         but not smaller.)  When the result of an operation would fall outside
+         this range, the result is normally returned as a long integer (in some
+         cases, the exception :exc:`OverflowError` is raised instead).  For the
+         purpose of shift and mask operations, integers are assumed to have a
+         binary, 2's complement notation using 32 or more bits, and hiding no
+         bits from the user (i.e., all 4294967296 different bit patterns
+         correspond to different values).
 
       Long integers
          .. index:: object: long integer
 
-         These represent numbers in an unlimited range, subject to available (virtual)
-         memory only.  For the purpose of shift and mask operations, a binary
-         representation is assumed, and negative numbers are represented in a variant of
-         2's complement which gives the illusion of an infinite string of sign bits
-         extending to the left.
+         These represent numbers in an unlimited range, subject to available
+         (virtual) memory only.  For the purpose of shift and mask operations, a
+         binary representation is assumed, and negative numbers are represented
+         in a variant of 2's complement which gives the illusion of an infinite
+         string of sign bits extending to the left.
 
       Booleans
          .. index::
@@ -199,20 +200,22 @@
             single: False
             single: True
 
-         These represent the truth values False and True.  The two objects representing
-         the values False and True are the only Boolean objects. The Boolean type is a
-         subtype of plain integers, and Boolean values behave like the values 0 and 1,
-         respectively, in almost all contexts, the exception being that when converted to
-         a string, the strings ``"False"`` or ``"True"`` are returned, respectively.
+         These represent the truth values False and True.  The two objects
+         representing the values False and True are the only Boolean objects.
+         The Boolean type is a subtype of plain integers, and Boolean values
+         behave like the values 0 and 1, respectively, in almost all contexts,
+         the exception being that when converted to a string, the strings
+         ``"False"`` or ``"True"`` are returned, respectively.
 
       .. index:: pair: integer; representation
 
-      The rules for integer representation are intended to give the most meaningful
-      interpretation of shift and mask operations involving negative integers and the
-      least surprises when switching between the plain and long integer domains.  Any
-      operation except left shift, if it yields a result in the plain integer domain
-      without causing overflow, will yield the same result in the long integer domain
-      or when using mixed operands.
+      The rules for integer representation are intended to give the most
+      meaningful interpretation of shift and mask operations involving negative
+      integers and the least surprises when switching between the plain and long
+      integer domains.  Any operation, if it yields a result in the plain
+      integer domain, will yield the same result in the long integer domain or
+      when using mixed operands.  The switch between domains is transparent to
+      the programmer.
 
    :class:`numbers.Real` (:class:`float`)
       .. index::

Modified: python/trunk/Doc/reference/expressions.rst
==============================================================================
--- python/trunk/Doc/reference/expressions.rst	(original)
+++ python/trunk/Doc/reference/expressions.rst	Sun May 11 12:55:59 2008
@@ -944,11 +944,9 @@
 
 .. index:: exception: ValueError
 
-A right shift by *n* bits is defined as division by ``pow(2,n)``.  A left shift
-by *n* bits is defined as multiplication with ``pow(2,n)``; for plain integers
-there is no overflow check so in that case the operation drops bits and flips
-the sign if the result is not less than ``pow(2,31)`` in absolute value.
-Negative shift counts raise a :exc:`ValueError` exception.
+A right shift by *n* bits is defined as division by ``pow(2, n)``.  A left shift
+by *n* bits is defined as multiplication with ``pow(2, n)``.  Negative shift
+counts raise a :exc:`ValueError` exception.
 
 
 .. _bitwise: