Index: stdtypes.rst =================================================================== --- stdtypes.rst (revision 58280) +++ stdtypes.rst (working copy) @@ -10,13 +10,6 @@ The following sections describe the standard types that are built into the interpreter. -.. note:: - - Historically (until release 2.2), Python's built-in types have differed from - user-defined types because it was not possible to use the built-in types as the - basis for object-oriented inheritance. This limitation no longer - exists. - .. index:: pair: built-in; types The principal built-in types are numerics, sequences, mappings, files, classes, @@ -173,23 +166,30 @@ pair: objects; comparing Objects of different types, except different numeric types and different string -types, never compare equal; such objects are ordered consistently but -arbitrarily (so that sorting a heterogeneous array yields a consistent result). +types, never compare equal. Furthermore, some types (for example, file objects) support only a degenerate -notion of comparison where any two objects of that type are unequal. Again, -such objects are ordered arbitrarily but consistently. The ``<``, ``<=``, ``>`` +notion of comparison where any two objects of that type are unequal. +The ``<``, ``<=``, ``>`` and ``>=`` operators will raise a :exc:`TypeError` exception when any operand is -a complex number. +a complex number, or other cases where there is no defined ordering. -.. index:: single: __cmp__() (instance method) +.. index:: + single: __eq__() (instance method) + single: __ne__() (instance method) + single: __lt__() (instance method) + single: __le__() (instance method) + single: __gt__() (instance method) + single: __ge__() (instance method) Instances of a class normally compare as non-equal unless the class defines the -:meth:`__cmp__` method. Refer to :ref:`customization`) for information on the +:meth:`__eq__` method. Refer to :ref:`customization`) for information on the use of this method to effect object comparisons. -**Implementation note:** Objects of different types except numbers are ordered -by their type names; objects of the same types that don't support proper -comparison are ordered by their address. +Instances of a class cannot be ordered with respect to other instances of the +same class, or other types of object, unless the class defines enough of the +methods :meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, and :meth:`__ge__` +(in general, :meth:`__lt__` and :meth:`__eq__` are sufficient, if you want +the conventional meanings of the comparison operators). .. index:: operator: in @@ -201,25 +201,21 @@ .. _typesnumeric: -Numeric Types --- :class:`int`, :class:`float`, :class:`long`, :class:`complex` +Numeric Types --- :class:`int`, :class:`float`, :class:`complex` =============================================================================== .. index:: object: numeric object: Boolean object: integer - object: long integer object: floating point object: complex number pair: C; language -There are four distinct numeric types: :dfn:`plain integers`, :dfn:`long -integers`, :dfn:`floating point numbers`, and :dfn:`complex numbers`. In -addition, Booleans are a subtype of plain integers. Plain integers (also just -called :dfn:`integers`) are implemented using :ctype:`long` in C, which gives -them at least 32 bits of precision (``sys.maxint`` is always set to the maximum -plain integer value for the current platform, the minimum value is -``-sys.maxint - 1``). Long integers have unlimited precision. Floating point +There are three distinct numeric types: :dfn:`integers`, +:dfn:`floating point numbers`, and :dfn:`complex numbers`. In +addition, Booleans are a subtype of plain integers. +Integers have unlimited precision. Floating point numbers are implemented using :ctype:`double` in C. All bets on their precision are off unless you happen to know the machine you are working with. @@ -230,18 +226,16 @@ .. index:: pair: numeric; literals pair: integer; literals - triple: long; integer; literals pair: floating point; literals pair: complex number; literals pair: hexadecimal; literals pair: octal; literals + pair: binary: literals Numbers are created by numeric literals or as the result of built-in functions -and operators. Unadorned integer literals (including hex and octal numbers) -yield plain integers unless the value they denote is too large to be represented -as a plain integer, in which case they yield a long integer. Integer literals -with an ``'L'`` or ``'l'`` suffix yield long integers (``'L'`` is preferred -because ``1l`` looks too much like eleven!). Numeric literals containing a +and operators. Unadorned integer literals (including hex, octal and binary numbers) +yield integers. +Numeric literals containing a decimal point or an exponent sign yield floating point numbers. Appending ``'j'`` or ``'J'`` to a numeric literal yields a complex number with a zero real part. A complex numeric literal is the sum of a real and an imaginary part. @@ -255,10 +249,10 @@ Python fully supports mixed arithmetic: when a binary arithmetic operator has operands of different numeric types, the operand with the "narrower" type is -widened to that of the other, where plain integer is narrower than long integer +widened to that of the other, where integer is narrower than floating point is narrower than complex. Comparisons between numbers of mixed type use the same rule. [#]_ The constructors :func:`int`, -:func:`long`, :func:`float`, and :func:`complex` can be used to produce numbers +:func:`float`, and :func:`complex` can be used to produce numbers of a specific type. All numeric types (except complex) support the following operations, sorted by @@ -274,12 +268,12 @@ +--------------------+---------------------------------+--------+ | ``x * y`` | product of *x* and *y* | | +--------------------+---------------------------------+--------+ -| ``x / y`` | quotient of *x* and *y* | \(1) | +| ``x / y`` | quotient of *x* and *y* | | +--------------------+---------------------------------+--------+ -| ``x // y`` | (floored) quotient of *x* and | \(5) | +| ``x // y`` | (floored) quotient of *x* and | \(4) | | | *y* | | +--------------------+---------------------------------+--------+ -| ``x % y`` | remainder of ``x / y`` | \(4) | +| ``x % y`` | remainder of ``x / y`` | \(3) | +--------------------+---------------------------------+--------+ | ``-x`` | *x* negated | | +--------------------+---------------------------------+--------+ @@ -288,9 +282,9 @@ | ``abs(x)`` | absolute value or magnitude of | | | | *x* | | +--------------------+---------------------------------+--------+ -| ``int(x)`` | *x* converted to integer | \(2) | +| ``int(x)`` | *x* converted to integer | \(1) | +--------------------+---------------------------------+--------+ -| ``long(x)`` | *x* converted to long integer | \(2) | +| ``long(x)`` | *x* converted to long integer | \(1) | +--------------------+---------------------------------+--------+ | ``float(x)`` | *x* converted to floating point | | +--------------------+---------------------------------+--------+ @@ -301,7 +295,7 @@ | ``c.conjugate()`` | conjugate of the complex number | | | | *c* | | +--------------------+---------------------------------+--------+ -| ``divmod(x, y)`` | the pair ``(x // y, x % y)`` | (3)(4) | +| ``divmod(x, y)`` | the pair ``(x // y, x % y)`` | (2)(3) | +--------------------+---------------------------------+--------+ | ``pow(x, y)`` | *x* to the power *y* | | +--------------------+---------------------------------+--------+ @@ -316,16 +310,6 @@ (1) .. index:: - pair: integer; division - triple: long; integer; division - - For (plain or long) integer division, the result is an integer. The result is - always rounded towards minus infinity: 1/2 is 0, (-1)/2 is -1, 1/(-2) is -1, and - (-1)/(-2) is 0. Note that the result is a long integer if either operand is a - long integer, regardless of the numeric value. - -(2) - .. index:: module: math single: floor() (in module math) single: ceil() (in module math) @@ -336,16 +320,14 @@ as in C; see functions :func:`floor` and :func:`ceil` in the :mod:`math` module for well-defined conversions. -(3) +(2) See :ref:`built-in-funcs` for a full description. -(4) - Complex floor division operator, modulo operator, and :func:`divmod`. - - .. deprecated:: 2.3 +(3) + Not for complex numbers. Instead convert to float using :func:`abs` if appropriate. -(5) +(4) Also referred to as integer division. The resultant value is a whole integer, though the result's type is not necessarily int. @@ -359,7 +341,7 @@ .. _bit-string-operations: -Plain and long integer types support additional operations that make sense only +Integer types support additional operations that make sense only for bit-strings. Negative numbers are treated as their 2's complement value (for long integers, this assumes a sufficiently large number of bits that no overflow occurs during the operation). @@ -453,7 +435,7 @@ Python objects in the Python/C API. -.. method:: iterator.next() +.. method:: iterator.__next__() Return the next item from the container. If there are no further items, raise the :exc:`StopIteration` exception. This method corresponds to the @@ -467,9 +449,7 @@ The intention of the protocol is that once an iterator's :meth:`__next__` method raises :exc:`StopIteration`, it will continue to do so on subsequent calls. -Implementations that do not obey this property are deemed broken. (This -constraint was added in Python 2.3; in Python 2.2, various iterators are broken -according to this rule.) +Implementations that do not obey this property are deemed broken. Python's generators provide a convenient way to implement the iterator protocol. If a container object's :meth:`__iter__` method is implemented as a generator, @@ -1140,13 +1120,9 @@ decimal point and defaults to 6. (5) - The ``%r`` conversion was added in Python 2.0. - The precision determines the maximal number of characters used. - The precision determines the maximal number of characters used. - Since Python strings have an explicit length, ``%s`` conversions do not assume that ``'\0'`` is the end of the string. @@ -1164,7 +1140,7 @@ .. _typesseq-range: -XRange Type +Range Type ----------- .. index:: object: range @@ -1174,7 +1150,7 @@ object will always take the same amount of memory, no matter the size of the range it represents. There are no consistent performance advantages. -XRange objects have very little behavior: they only support indexing, iteration, +Range objects have very little behavior: they only support indexing, iteration, and the :func:`len` function.