PageRenderTime 826ms CodeModel.GetById 184ms app.highlight 362ms RepoModel.GetById 153ms app.codeStats 0ms

/Doc/library/stdtypes.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 2723 lines | 1927 code | 796 blank | 0 comment | 0 complexity | b712e452ec171c361e2db790d841e54a MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1.. XXX: reference/datamodel and this have quite a few overlaps!
   2
   3
   4.. _bltin-types:
   5
   6**************
   7Built-in Types
   8**************
   9
  10The following sections describe the standard types that are built into the
  11interpreter.
  12
  13.. note::
  14
  15   Historically (until release 2.2), Python's built-in types have differed from
  16   user-defined types because it was not possible to use the built-in types as the
  17   basis for object-oriented inheritance. This limitation no longer
  18   exists.
  19
  20.. index:: pair: built-in; types
  21
  22The principal built-in types are numerics, sequences, mappings, files, classes,
  23instances and exceptions.
  24
  25.. index:: statement: print
  26
  27Some operations are supported by several object types; in particular,
  28practically all objects can be compared, tested for truth value, and converted
  29to a string (with the :func:`repr` function or the slightly different
  30:func:`str` function).  The latter function is implicitly used when an object is
  31written by the :func:`print` function.
  32
  33
  34.. _truth:
  35
  36Truth Value Testing
  37===================
  38
  39.. index::
  40   statement: if
  41   statement: while
  42   pair: truth; value
  43   pair: Boolean; operations
  44   single: false
  45
  46Any object can be tested for truth value, for use in an :keyword:`if` or
  47:keyword:`while` condition or as operand of the Boolean operations below. The
  48following values are considered false:
  49
  50  .. index:: single: None (Built-in object)
  51
  52* ``None``
  53
  54  .. index:: single: False (Built-in object)
  55
  56* ``False``
  57
  58* zero of any numeric type, for example, ``0``, ``0L``, ``0.0``, ``0j``.
  59
  60* any empty sequence, for example, ``''``, ``()``, ``[]``.
  61
  62* any empty mapping, for example, ``{}``.
  63
  64* instances of user-defined classes, if the class defines a :meth:`__nonzero__`
  65  or :meth:`__len__` method, when that method returns the integer zero or
  66  :class:`bool` value ``False``. [#]_
  67
  68.. index:: single: true
  69
  70All other values are considered true --- so objects of many types are always
  71true.
  72
  73.. index::
  74   operator: or
  75   operator: and
  76   single: False
  77   single: True
  78
  79Operations and built-in functions that have a Boolean result always return ``0``
  80or ``False`` for false and ``1`` or ``True`` for true, unless otherwise stated.
  81(Important exception: the Boolean operations ``or`` and ``and`` always return
  82one of their operands.)
  83
  84
  85.. _boolean:
  86
  87Boolean Operations --- :keyword:`and`, :keyword:`or`, :keyword:`not`
  88====================================================================
  89
  90.. index:: pair: Boolean; operations
  91
  92These are the Boolean operations, ordered by ascending priority:
  93
  94+-------------+---------------------------------+-------+
  95| Operation   | Result                          | Notes |
  96+=============+=================================+=======+
  97| ``x or y``  | if *x* is false, then *y*, else | \(1)  |
  98|             | *x*                             |       |
  99+-------------+---------------------------------+-------+
 100| ``x and y`` | if *x* is false, then *x*, else | \(2)  |
 101|             | *y*                             |       |
 102+-------------+---------------------------------+-------+
 103| ``not x``   | if *x* is false, then ``True``, | \(3)  |
 104|             | else ``False``                  |       |
 105+-------------+---------------------------------+-------+
 106
 107.. index::
 108   operator: and
 109   operator: or
 110   operator: not
 111
 112Notes:
 113
 114(1)
 115   This is a short-circuit operator, so it only evaluates the second
 116   argument if the first one is :const:`False`.
 117
 118(2)
 119   This is a short-circuit operator, so it only evaluates the second
 120   argument if the first one is :const:`True`.
 121
 122(3)
 123   ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is
 124   interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error.
 125
 126
 127.. _stdcomparisons:
 128
 129Comparisons
 130===========
 131
 132.. index:: pair: chaining; comparisons
 133
 134Comparison operations are supported by all objects.  They all have the same
 135priority (which is higher than that of the Boolean operations). Comparisons can
 136be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and
 137y <= z``, except that *y* is evaluated only once (but in both cases *z* is not
 138evaluated at all when ``x < y`` is found to be false).
 139
 140This table summarizes the comparison operations:
 141
 142+------------+-------------------------+-------+
 143| Operation  | Meaning                 | Notes |
 144+============+=========================+=======+
 145| ``<``      | strictly less than      |       |
 146+------------+-------------------------+-------+
 147| ``<=``     | less than or equal      |       |
 148+------------+-------------------------+-------+
 149| ``>``      | strictly greater than   |       |
 150+------------+-------------------------+-------+
 151| ``>=``     | greater than or equal   |       |
 152+------------+-------------------------+-------+
 153| ``==``     | equal                   |       |
 154+------------+-------------------------+-------+
 155| ``!=``     | not equal               | \(1)  |
 156+------------+-------------------------+-------+
 157| ``is``     | object identity         |       |
 158+------------+-------------------------+-------+
 159| ``is not`` | negated object identity |       |
 160+------------+-------------------------+-------+
 161
 162.. index::
 163   pair: operator; comparison
 164   operator: ==
 165   operator: <
 166   operator: <=
 167   operator: >
 168   operator: >=
 169   operator: !=
 170   operator: is
 171   operator: is not
 172
 173Notes:
 174
 175(1)
 176    ``!=`` can also be written ``<>``, but this is an obsolete usage
 177    kept for backwards compatibility only. New code should always use
 178    ``!=``.
 179
 180.. index::
 181   pair: object; numeric
 182   pair: objects; comparing
 183
 184Objects of different types, except different numeric types and different string
 185types, never compare equal; such objects are ordered consistently but
 186arbitrarily (so that sorting a heterogeneous array yields a consistent result).
 187Furthermore, some types (for example, file objects) support only a degenerate
 188notion of comparison where any two objects of that type are unequal.  Again,
 189such objects are ordered arbitrarily but consistently. The ``<``, ``<=``, ``>``
 190and ``>=`` operators will raise a :exc:`TypeError` exception when any operand is
 191a complex number.
 192
 193.. index:: single: __cmp__() (instance method)
 194
 195Instances of a class normally compare as non-equal unless the class defines the
 196:meth:`__cmp__` method.  Refer to :ref:`customization`) for information on the
 197use of this method to effect object comparisons.
 198
 199**Implementation note:** Objects of different types except numbers are ordered
 200by their type names; objects of the same types that don't support proper
 201comparison are ordered by their address.
 202
 203.. index::
 204   operator: in
 205   operator: not in
 206
 207Two more operations with the same syntactic priority, ``in`` and ``not in``, are
 208supported only by sequence types (below).
 209
 210
 211.. _typesnumeric:
 212
 213Numeric Types --- :class:`int`, :class:`float`, :class:`long`, :class:`complex`
 214===============================================================================
 215
 216.. index::
 217   object: numeric
 218   object: Boolean
 219   object: integer
 220   object: long integer
 221   object: floating point
 222   object: complex number
 223   pair: C; language
 224
 225There are four distinct numeric types: :dfn:`plain integers`, :dfn:`long
 226integers`,  :dfn:`floating point numbers`, and :dfn:`complex numbers`. In
 227addition, Booleans are a subtype of plain integers. Plain integers (also just
 228called :dfn:`integers`) are implemented using :ctype:`long` in C, which gives
 229them at least 32 bits of precision (``sys.maxint`` is always set to the maximum
 230plain integer value for the current platform, the minimum value is
 231``-sys.maxint - 1``).  Long integers have unlimited precision. Floating point
 232numbers are implemented using :ctype:`double` in C. All bets on their precision
 233are off unless you happen to know the machine you are working with.
 234
 235Complex numbers have a real and imaginary part, which are each implemented using
 236:ctype:`double` in C.  To extract these parts from a complex number *z*, use
 237``z.real`` and ``z.imag``.
 238
 239.. index::
 240   pair: numeric; literals
 241   pair: integer; literals
 242   triple: long; integer; literals
 243   pair: floating point; literals
 244   pair: complex number; literals
 245   pair: hexadecimal; literals
 246   pair: octal; literals
 247
 248Numbers are created by numeric literals or as the result of built-in functions
 249and operators.  Unadorned integer literals (including binary, hex, and octal
 250numbers) yield plain integers unless the value they denote is too large to be
 251represented as a plain integer, in which case they yield a long integer.
 252Integer literals with an ``'L'`` or ``'l'`` suffix yield long integers (``'L'``
 253is preferred because ``1l`` looks too much like eleven!).  Numeric literals
 254containing a decimal point or an exponent sign yield floating point numbers.
 255Appending ``'j'`` or ``'J'`` to a numeric literal yields a complex number with a
 256zero real part. A complex numeric literal is the sum of a real and an imaginary
 257part.
 258
 259.. index::
 260   single: arithmetic
 261   builtin: int
 262   builtin: long
 263   builtin: float
 264   builtin: complex
 265
 266Python fully supports mixed arithmetic: when a binary arithmetic operator has
 267operands of different numeric types, the operand with the "narrower" type is
 268widened to that of the other, where plain integer is narrower than long integer
 269is narrower than floating point is narrower than complex. Comparisons between
 270numbers of mixed type use the same rule. [#]_ The constructors :func:`int`,
 271:func:`long`, :func:`float`, and :func:`complex` can be used to produce numbers
 272of a specific type.
 273
 274All builtin numeric types support the following operations. See
 275:ref:`power` and later sections for the operators' priorities.
 276
 277+--------------------+---------------------------------+--------+
 278| Operation          | Result                          | Notes  |
 279+====================+=================================+========+
 280| ``x + y``          | sum of *x* and *y*              |        |
 281+--------------------+---------------------------------+--------+
 282| ``x - y``          | difference of *x* and *y*       |        |
 283+--------------------+---------------------------------+--------+
 284| ``x * y``          | product of *x* and *y*          |        |
 285+--------------------+---------------------------------+--------+
 286| ``x / y``          | quotient of *x* and *y*         | \(1)   |
 287+--------------------+---------------------------------+--------+
 288| ``x // y``         | (floored) quotient of *x* and   | (4)(5) |
 289|                    | *y*                             |        |
 290+--------------------+---------------------------------+--------+
 291| ``x % y``          | remainder of ``x / y``          | \(4)   |
 292+--------------------+---------------------------------+--------+
 293| ``-x``             | *x* negated                     |        |
 294+--------------------+---------------------------------+--------+
 295| ``+x``             | *x* unchanged                   |        |
 296+--------------------+---------------------------------+--------+
 297| ``abs(x)``         | absolute value or magnitude of  | \(3)   |
 298|                    | *x*                             |        |
 299+--------------------+---------------------------------+--------+
 300| ``int(x)``         | *x* converted to integer        | \(2)   |
 301+--------------------+---------------------------------+--------+
 302| ``long(x)``        | *x* converted to long integer   | \(2)   |
 303+--------------------+---------------------------------+--------+
 304| ``float(x)``       | *x* converted to floating point | \(6)   |
 305+--------------------+---------------------------------+--------+
 306| ``complex(re,im)`` | a complex number with real part |        |
 307|                    | *re*, imaginary part *im*.      |        |
 308|                    | *im* defaults to zero.          |        |
 309+--------------------+---------------------------------+--------+
 310| ``c.conjugate()``  | conjugate of the complex number |        |
 311|                    | *c*. (Identity on real numbers) |        |
 312+--------------------+---------------------------------+--------+
 313| ``divmod(x, y)``   | the pair ``(x // y, x % y)``    | (3)(4) |
 314+--------------------+---------------------------------+--------+
 315| ``pow(x, y)``      | *x* to the power *y*            | (3)(7) |
 316+--------------------+---------------------------------+--------+
 317| ``x ** y``         | *x* to the power *y*            | \(7)   |
 318+--------------------+---------------------------------+--------+
 319
 320.. index::
 321   triple: operations on; numeric; types
 322   single: conjugate() (complex number method)
 323
 324Notes:
 325
 326(1)
 327   .. index::
 328      pair: integer; division
 329      triple: long; integer; division
 330
 331   For (plain or long) integer division, the result is an integer. The result is
 332   always rounded towards minus infinity: 1/2 is 0, (-1)/2 is -1, 1/(-2) is -1, and
 333   (-1)/(-2) is 0.  Note that the result is a long integer if either operand is a
 334   long integer, regardless of the numeric value.
 335
 336(2)
 337   .. index::
 338      module: math
 339      single: floor() (in module math)
 340      single: ceil() (in module math)
 341      single: trunc() (in module math)
 342      pair: numeric; conversions
 343
 344   Conversion from floats using :func:`int` or :func:`long` truncates toward
 345   zero like the related function, :func:`math.trunc`.  Use the function
 346   :func:`math.floor` to round downward and :func:`math.ceil` to round
 347   upward.
 348
 349(3)
 350   See :ref:`built-in-funcs` for a full description.
 351
 352(4)
 353   Complex floor division operator, modulo operator, and :func:`divmod`.
 354
 355   .. deprecated:: 2.3
 356      Instead convert to float using :func:`abs` if appropriate.
 357
 358(5)
 359   Also referred to as integer division.  The resultant value is a whole integer,
 360   though the result's type is not necessarily int.
 361
 362(6)
 363   float also accepts the strings "nan" and "inf" with an optional prefix "+"
 364   or "-" for Not a Number (NaN) and positive or negative infinity.
 365
 366   .. versionadded:: 2.6
 367
 368(7)
 369   Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for
 370   programming languages.
 371
 372All :class:`numbers.Real` types (:class:`int`, :class:`long`, and
 373:class:`float`) also include the following operations:
 374
 375+--------------------+------------------------------------+--------+
 376| Operation          | Result                             | Notes  |
 377+====================+====================================+========+
 378| ``math.trunc(x)``  | *x* truncated to Integral          |        |
 379+--------------------+------------------------------------+--------+
 380| ``round(x[, n])``  | *x* rounded to n digits,           |        |
 381|                    | rounding half to even. If n is     |        |
 382|                    | omitted, it defaults to 0.         |        |
 383+--------------------+------------------------------------+--------+
 384| ``math.floor(x)``  | the greatest integral float <= *x* |        |
 385+--------------------+------------------------------------+--------+
 386| ``math.ceil(x)``   | the least integral float >= *x*    |        |
 387+--------------------+------------------------------------+--------+
 388
 389.. XXXJH exceptions: overflow (when? what operations?) zerodivision
 390
 391
 392.. _bitstring-ops:
 393
 394Bit-string Operations on Integer Types
 395--------------------------------------
 396
 397.. _bit-string-operations:
 398
 399Plain and long integer types support additional operations that make sense only
 400for bit-strings.  Negative numbers are treated as their 2's complement value
 401(for long integers, this assumes a sufficiently large number of bits that no
 402overflow occurs during the operation).
 403
 404The priorities of the binary bitwise operations are all lower than the numeric
 405operations and higher than the comparisons; the unary operation ``~`` has the
 406same priority as the other unary numeric operations (``+`` and ``-``).
 407
 408This table lists the bit-string operations sorted in ascending priority:
 409
 410+------------+--------------------------------+----------+
 411| Operation  | Result                         | Notes    |
 412+============+================================+==========+
 413| ``x | y``  | bitwise :dfn:`or` of *x* and   |          |
 414|            | *y*                            |          |
 415+------------+--------------------------------+----------+
 416| ``x ^ y``  | bitwise :dfn:`exclusive or` of |          |
 417|            | *x* and *y*                    |          |
 418+------------+--------------------------------+----------+
 419| ``x & y``  | bitwise :dfn:`and` of *x* and  |          |
 420|            | *y*                            |          |
 421+------------+--------------------------------+----------+
 422| ``x << n`` | *x* shifted left by *n* bits   | (1)(2)   |
 423+------------+--------------------------------+----------+
 424| ``x >> n`` | *x* shifted right by *n* bits  | (1)(3)   |
 425+------------+--------------------------------+----------+
 426| ``~x``     | the bits of *x* inverted       |          |
 427+------------+--------------------------------+----------+
 428
 429.. index::
 430   triple: operations on; integer; types
 431   pair: bit-string; operations
 432   pair: shifting; operations
 433   pair: masking; operations
 434
 435Notes:
 436
 437(1)
 438   Negative shift counts are illegal and cause a :exc:`ValueError` to be raised.
 439
 440(2)
 441   A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)``.  A
 442   long integer is returned if the result exceeds the range of plain integers.
 443
 444(3)
 445   A right shift by *n* bits is equivalent to division by ``pow(2, n)``.
 446
 447
 448Additional Methods on Float
 449---------------------------
 450
 451The float type has some additional methods.
 452
 453.. method:: float.as_integer_ratio()
 454
 455    Return a pair of integers whose ratio is exactly equal to the
 456    original float and with a positive denominator.  Raises
 457    :exc:`OverflowError` on infinities and a :exc:`ValueError` on
 458    NaNs.
 459
 460    .. versionadded:: 2.6
 461
 462Two methods support conversion to
 463and from hexadecimal strings.  Since Python's floats are stored
 464internally as binary numbers, converting a float to or from a
 465*decimal* string usually involves a small rounding error.  In
 466contrast, hexadecimal strings allow exact representation and
 467specification of floating-point numbers.  This can be useful when
 468debugging, and in numerical work.
 469
 470
 471.. method:: float.hex()
 472
 473   Return a representation of a floating-point number as a hexadecimal
 474   string.  For finite floating-point numbers, this representation
 475   will always include a leading ``0x`` and a trailing ``p`` and
 476   exponent.
 477
 478   .. versionadded:: 2.6
 479
 480
 481.. method:: float.fromhex(s)
 482
 483   Class method to return the float represented by a hexadecimal
 484   string *s*.  The string *s* may have leading and trailing
 485   whitespace.
 486
 487   .. versionadded:: 2.6
 488
 489
 490Note that :meth:`float.hex` is an instance method, while
 491:meth:`float.fromhex` is a class method.
 492
 493A hexadecimal string takes the form::
 494
 495   [sign] ['0x'] integer ['.' fraction] ['p' exponent]
 496
 497where the optional ``sign`` may by either ``+`` or ``-``, ``integer``
 498and ``fraction`` are strings of hexadecimal digits, and ``exponent``
 499is a decimal integer with an optional leading sign.  Case is not
 500significant, and there must be at least one hexadecimal digit in
 501either the integer or the fraction.  This syntax is similar to the
 502syntax specified in section 6.4.4.2 of the C99 standard, and also to
 503the syntax used in Java 1.5 onwards.  In particular, the output of
 504:meth:`float.hex` is usable as a hexadecimal floating-point literal in
 505C or Java code, and hexadecimal strings produced by C's ``%a`` format
 506character or Java's ``Double.toHexString`` are accepted by
 507:meth:`float.fromhex`.
 508
 509
 510Note that the exponent is written in decimal rather than hexadecimal,
 511and that it gives the power of 2 by which to multiply the coefficient.
 512For example, the hexadecimal string ``0x3.a7p10`` represents the
 513floating-point number ``(3 + 10./16 + 7./16**2) * 2.0**10``, or
 514``3740.0``::
 515
 516   >>> float.fromhex('0x3.a7p10')
 517   3740.0
 518
 519
 520Applying the reverse conversion to ``3740.0`` gives a different
 521hexadecimal string representing the same number::
 522
 523   >>> float.hex(3740.0)
 524   '0x1.d380000000000p+11'
 525
 526
 527.. _typeiter:
 528
 529Iterator Types
 530==============
 531
 532.. versionadded:: 2.2
 533
 534.. index::
 535   single: iterator protocol
 536   single: protocol; iterator
 537   single: sequence; iteration
 538   single: container; iteration over
 539
 540Python supports a concept of iteration over containers.  This is implemented
 541using two distinct methods; these are used to allow user-defined classes to
 542support iteration.  Sequences, described below in more detail, always support
 543the iteration methods.
 544
 545One method needs to be defined for container objects to provide iteration
 546support:
 547
 548.. XXX duplicated in reference/datamodel!
 549
 550.. method:: container.__iter__()
 551
 552   Return an iterator object.  The object is required to support the iterator
 553   protocol described below.  If a container supports different types of
 554   iteration, additional methods can be provided to specifically request
 555   iterators for those iteration types.  (An example of an object supporting
 556   multiple forms of iteration would be a tree structure which supports both
 557   breadth-first and depth-first traversal.)  This method corresponds to the
 558   :attr:`tp_iter` slot of the type structure for Python objects in the Python/C
 559   API.
 560
 561The iterator objects themselves are required to support the following two
 562methods, which together form the :dfn:`iterator protocol`:
 563
 564
 565.. method:: iterator.__iter__()
 566
 567   Return the iterator object itself.  This is required to allow both containers
 568   and iterators to be used with the :keyword:`for` and :keyword:`in` statements.
 569   This method corresponds to the :attr:`tp_iter` slot of the type structure for
 570   Python objects in the Python/C API.
 571
 572
 573.. method:: iterator.next()
 574
 575   Return the next item from the container.  If there are no further items, raise
 576   the :exc:`StopIteration` exception.  This method corresponds to the
 577   :attr:`tp_iternext` slot of the type structure for Python objects in the
 578   Python/C API.
 579
 580Python defines several iterator objects to support iteration over general and
 581specific sequence types, dictionaries, and other more specialized forms.  The
 582specific types are not important beyond their implementation of the iterator
 583protocol.
 584
 585The intention of the protocol is that once an iterator's :meth:`next` method
 586raises :exc:`StopIteration`, it will continue to do so on subsequent calls.
 587Implementations that do not obey this property are deemed broken.  (This
 588constraint was added in Python 2.3; in Python 2.2, various iterators are broken
 589according to this rule.)
 590
 591Python's :term:`generator`\s provide a convenient way to implement the iterator
 592protocol.  If a container object's :meth:`__iter__` method is implemented as a
 593generator, it will automatically return an iterator object (technically, a
 594generator object) supplying the :meth:`__iter__` and :meth:`next` methods.
 595
 596
 597.. _typesseq:
 598
 599Sequence Types --- :class:`str`, :class:`unicode`, :class:`list`, :class:`tuple`, :class:`buffer`, :class:`xrange`
 600==================================================================================================================
 601
 602There are six sequence types: strings, Unicode strings, lists, tuples, buffers,
 603and xrange objects.
 604
 605For other containers see the built in :class:`dict` and :class:`set` classes,
 606and the :mod:`collections` module.
 607
 608
 609.. index::
 610   object: sequence
 611   object: string
 612   object: Unicode
 613   object: tuple
 614   object: list
 615   object: buffer
 616   object: xrange
 617
 618String literals are written in single or double quotes: ``'xyzzy'``,
 619``"frobozz"``.  See :ref:`strings` for more about string literals.
 620Unicode strings are much like strings, but are specified in the syntax
 621using a preceding ``'u'`` character: ``u'abc'``, ``u"def"``. In addition
 622to the functionality described here, there are also string-specific
 623methods described in the :ref:`string-methods` section. Lists are
 624constructed with square brackets, separating items with commas: ``[a, b, c]``.
 625Tuples are constructed by the comma operator (not within square
 626brackets), with or without enclosing parentheses, but an empty tuple
 627must have the enclosing parentheses, such as ``a, b, c`` or ``()``.  A
 628single item tuple must have a trailing comma, such as ``(d,)``.
 629
 630Buffer objects are not directly supported by Python syntax, but can be created
 631by calling the builtin function :func:`buffer`.  They don't support
 632concatenation or repetition.
 633
 634Objects of type xrange are similar to buffers in that there is no specific syntax to
 635create them, but they are created using the :func:`xrange` function.  They don't
 636support slicing, concatenation or repetition, and using ``in``, ``not in``,
 637:func:`min` or :func:`max` on them is inefficient.
 638
 639Most sequence types support the following operations.  The ``in`` and ``not in``
 640operations have the same priorities as the comparison operations.  The ``+`` and
 641``*`` operations have the same priority as the corresponding numeric operations.
 642[#]_ Additional methods are provided for :ref:`typesseq-mutable`.
 643
 644This table lists the sequence operations sorted in ascending priority
 645(operations in the same box have the same priority).  In the table, *s* and *t*
 646are sequences of the same type; *n*, *i* and *j* are integers:
 647
 648+------------------+--------------------------------+----------+
 649| Operation        | Result                         | Notes    |
 650+==================+================================+==========+
 651| ``x in s``       | ``True`` if an item of *s* is  | \(1)     |
 652|                  | equal to *x*, else ``False``   |          |
 653+------------------+--------------------------------+----------+
 654| ``x not in s``   | ``False`` if an item of *s* is | \(1)     |
 655|                  | equal to *x*, else ``True``    |          |
 656+------------------+--------------------------------+----------+
 657| ``s + t``        | the concatenation of *s* and   | \(6)     |
 658|                  | *t*                            |          |
 659+------------------+--------------------------------+----------+
 660| ``s * n, n * s`` | *n* shallow copies of *s*      | \(2)     |
 661|                  | concatenated                   |          |
 662+------------------+--------------------------------+----------+
 663| ``s[i]``         | *i*'th item of *s*, origin 0   | \(3)     |
 664+------------------+--------------------------------+----------+
 665| ``s[i:j]``       | slice of *s* from *i* to *j*   | (3)(4)   |
 666+------------------+--------------------------------+----------+
 667| ``s[i:j:k]``     | slice of *s* from *i* to *j*   | (3)(5)   |
 668|                  | with step *k*                  |          |
 669+------------------+--------------------------------+----------+
 670| ``len(s)``       | length of *s*                  |          |
 671+------------------+--------------------------------+----------+
 672| ``min(s)``       | smallest item of *s*           |          |
 673+------------------+--------------------------------+----------+
 674| ``max(s)``       | largest item of *s*            |          |
 675+------------------+--------------------------------+----------+
 676
 677Sequence types also support comparisons. In particular, tuples and lists
 678are compared lexicographically by comparing corresponding
 679elements. This means that to compare equal, every element must compare
 680equal and the two sequences must be of the same type and have the same
 681length. (For full details see :ref:`comparisons` in the language
 682reference.)
 683
 684.. index::
 685   triple: operations on; sequence; types
 686   builtin: len
 687   builtin: min
 688   builtin: max
 689   pair: concatenation; operation
 690   pair: repetition; operation
 691   pair: subscript; operation
 692   pair: slice; operation
 693   pair: extended slice; operation
 694   operator: in
 695   operator: not in
 696
 697Notes:
 698
 699(1)
 700   When *s* is a string or Unicode string object the ``in`` and ``not in``
 701   operations act like a substring test.  In Python versions before 2.3, *x* had to
 702   be a string of length 1. In Python 2.3 and beyond, *x* may be a string of any
 703   length.
 704
 705(2)
 706   Values of *n* less than ``0`` are treated as ``0`` (which yields an empty
 707   sequence of the same type as *s*).  Note also that the copies are shallow;
 708   nested structures are not copied.  This often haunts new Python programmers;
 709   consider:
 710
 711      >>> lists = [[]] * 3
 712      >>> lists
 713      [[], [], []]
 714      >>> lists[0].append(3)
 715      >>> lists
 716      [[3], [3], [3]]
 717
 718   What has happened is that ``[[]]`` is a one-element list containing an empty
 719   list, so all three elements of ``[[]] * 3`` are (pointers to) this single empty
 720   list.  Modifying any of the elements of ``lists`` modifies this single list.
 721   You can create a list of different lists this way:
 722
 723      >>> lists = [[] for i in range(3)]
 724      >>> lists[0].append(3)
 725      >>> lists[1].append(5)
 726      >>> lists[2].append(7)
 727      >>> lists
 728      [[3], [5], [7]]
 729
 730(3)
 731   If *i* or *j* is negative, the index is relative to the end of the string:
 732   ``len(s) + i`` or ``len(s) + j`` is substituted.  But note that ``-0`` is still
 733   ``0``.
 734
 735(4)
 736   The slice of *s* from *i* to *j* is defined as the sequence of items with index
 737   *k* such that ``i <= k < j``.  If *i* or *j* is greater than ``len(s)``, use
 738   ``len(s)``.  If *i* is omitted or ``None``, use ``0``.  If *j* is omitted or
 739   ``None``, use ``len(s)``.  If *i* is greater than or equal to *j*, the slice is
 740   empty.
 741
 742(5)
 743   The slice of *s* from *i* to *j* with step *k* is defined as the sequence of
 744   items with index  ``x = i + n*k`` such that ``0 <= n < (j-i)/k``.  In other words,
 745   the indices are ``i``, ``i+k``, ``i+2*k``, ``i+3*k`` and so on, stopping when
 746   *j* is reached (but never including *j*).  If *i* or *j* is greater than
 747   ``len(s)``, use ``len(s)``.  If *i* or *j* are omitted or ``None``, they become
 748   "end" values (which end depends on the sign of *k*).  Note, *k* cannot be zero.
 749   If *k* is ``None``, it is treated like ``1``.
 750
 751(6)
 752   If *s* and *t* are both strings, some Python implementations such as CPython can
 753   usually perform an in-place optimization for assignments of the form ``s=s+t``
 754   or ``s+=t``.  When applicable, this optimization makes quadratic run-time much
 755   less likely.  This optimization is both version and implementation dependent.
 756   For performance sensitive code, it is preferable to use the :meth:`str.join`
 757   method which assures consistent linear concatenation performance across versions
 758   and implementations.
 759
 760   .. versionchanged:: 2.4
 761      Formerly, string concatenation never occurred in-place.
 762
 763
 764.. _string-methods:
 765
 766String Methods
 767--------------
 768
 769.. index:: pair: string; methods
 770
 771Below are listed the string methods which both 8-bit strings and Unicode objects
 772support. Note that none of these methods take keyword arguments.
 773
 774In addition, Python's strings support the sequence type methods
 775described in the :ref:`typesseq` section. To output formatted strings
 776use template strings or the ``%`` operator described in the
 777:ref:`string-formatting` section. Also, see the :mod:`re` module for
 778string functions based on regular expressions.
 779
 780.. method:: str.capitalize()
 781
 782   Return a copy of the string with only its first character capitalized.
 783
 784   For 8-bit strings, this method is locale-dependent.
 785
 786
 787.. method:: str.center(width[, fillchar])
 788
 789   Return centered in a string of length *width*. Padding is done using the
 790   specified *fillchar* (default is a space).
 791
 792   .. versionchanged:: 2.4
 793      Support for the *fillchar* argument.
 794
 795
 796.. method:: str.count(sub[, start[, end]])
 797
 798   Return the number of non-overlapping occurrences of substring *sub* in the
 799   range [*start*, *end*].  Optional arguments *start* and *end* are
 800   interpreted as in slice notation.
 801
 802
 803.. method:: str.decode([encoding[, errors]])
 804
 805   Decodes the string using the codec registered for *encoding*. *encoding*
 806   defaults to the default string encoding.  *errors* may be given to set a
 807   different error handling scheme.  The default is ``'strict'``, meaning that
 808   encoding errors raise :exc:`UnicodeError`.  Other possible values are
 809   ``'ignore'``, ``'replace'`` and any other name registered via
 810   :func:`codecs.register_error`, see section :ref:`codec-base-classes`.
 811
 812   .. versionadded:: 2.2
 813
 814   .. versionchanged:: 2.3
 815      Support for other error handling schemes added.
 816
 817
 818.. method:: str.encode([encoding[,errors]])
 819
 820   Return an encoded version of the string.  Default encoding is the current
 821   default string encoding.  *errors* may be given to set a different error
 822   handling scheme.  The default for *errors* is ``'strict'``, meaning that
 823   encoding errors raise a :exc:`UnicodeError`.  Other possible values are
 824   ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``, ``'backslashreplace'`` and
 825   any other name registered via :func:`codecs.register_error`, see section
 826   :ref:`codec-base-classes`. For a list of possible encodings, see section
 827   :ref:`standard-encodings`.
 828
 829   .. versionadded:: 2.0
 830
 831   .. versionchanged:: 2.3
 832      Support for ``'xmlcharrefreplace'`` and ``'backslashreplace'`` and other error
 833      handling schemes added.
 834
 835
 836.. method:: str.endswith(suffix[, start[, end]])
 837
 838   Return ``True`` if the string ends with the specified *suffix*, otherwise return
 839   ``False``.  *suffix* can also be a tuple of suffixes to look for.  With optional
 840   *start*, test beginning at that position.  With optional *end*, stop comparing
 841   at that position.
 842
 843   .. versionchanged:: 2.5
 844      Accept tuples as *suffix*.
 845
 846
 847.. method:: str.expandtabs([tabsize])
 848
 849   Return a copy of the string where all tab characters are replaced by one or
 850   more spaces, depending on the current column and the given tab size.  The
 851   column number is reset to zero after each newline occurring in the string.
 852   If *tabsize* is not given, a tab size of ``8`` characters is assumed.  This
 853   doesn't understand other non-printing characters or escape sequences.
 854
 855
 856.. method:: str.find(sub[, start[, end]])
 857
 858   Return the lowest index in the string where substring *sub* is found, such that
 859   *sub* is contained in the range [*start*, *end*].  Optional arguments *start*
 860   and *end* are interpreted as in slice notation.  Return ``-1`` if *sub* is not
 861   found.
 862
 863
 864.. method:: str.format(format_string, *args, **kwargs)
 865
 866   Perform a string formatting operation.  The *format_string* argument can
 867   contain literal text or replacement fields delimited by braces ``{}``.  Each
 868   replacement field contains either the numeric index of a positional argument,
 869   or the name of a keyword argument.  Returns a copy of *format_string* where
 870   each replacement field is replaced with the string value of the corresponding
 871   argument.
 872
 873      >>> "The sum of 1 + 2 is {0}".format(1+2)
 874      'The sum of 1 + 2 is 3'
 875
 876   See :ref:`formatstrings` for a description of the various formatting options
 877   that can be specified in format strings.
 878
 879   This method of string formatting is the new standard in Python 3.0, and
 880   should be preferred to the ``%`` formatting described in
 881   :ref:`string-formatting` in new code.
 882
 883   .. versionadded:: 2.6
 884
 885
 886.. method:: str.index(sub[, start[, end]])
 887
 888   Like :meth:`find`, but raise :exc:`ValueError` when the substring is not found.
 889
 890
 891.. method:: str.isalnum()
 892
 893   Return true if all characters in the string are alphanumeric and there is at
 894   least one character, false otherwise.
 895
 896   For 8-bit strings, this method is locale-dependent.
 897
 898
 899.. method:: str.isalpha()
 900
 901   Return true if all characters in the string are alphabetic and there is at least
 902   one character, false otherwise.
 903
 904   For 8-bit strings, this method is locale-dependent.
 905
 906
 907.. method:: str.isdigit()
 908
 909   Return true if all characters in the string are digits and there is at least one
 910   character, false otherwise.
 911
 912   For 8-bit strings, this method is locale-dependent.
 913
 914
 915.. method:: str.islower()
 916
 917   Return true if all cased characters in the string are lowercase and there is at
 918   least one cased character, false otherwise.
 919
 920   For 8-bit strings, this method is locale-dependent.
 921
 922
 923.. method:: str.isspace()
 924
 925   Return true if there are only whitespace characters in the string and there is
 926   at least one character, false otherwise.
 927
 928   For 8-bit strings, this method is locale-dependent.
 929
 930
 931.. method:: str.istitle()
 932
 933   Return true if the string is a titlecased string and there is at least one
 934   character, for example uppercase characters may only follow uncased characters
 935   and lowercase characters only cased ones.  Return false otherwise.
 936
 937   For 8-bit strings, this method is locale-dependent.
 938
 939
 940.. method:: str.isupper()
 941
 942   Return true if all cased characters in the string are uppercase and there is at
 943   least one cased character, false otherwise.
 944
 945   For 8-bit strings, this method is locale-dependent.
 946
 947
 948.. method:: str.join(seq)
 949
 950   Return a string which is the concatenation of the strings in the sequence *seq*.
 951   The separator between elements is the string providing this method.
 952
 953
 954.. method:: str.ljust(width[, fillchar])
 955
 956   Return the string left justified in a string of length *width*. Padding is done
 957   using the specified *fillchar* (default is a space).  The original string is
 958   returned if *width* is less than ``len(s)``.
 959
 960   .. versionchanged:: 2.4
 961      Support for the *fillchar* argument.
 962
 963
 964.. method:: str.lower()
 965
 966   Return a copy of the string converted to lowercase.
 967
 968   For 8-bit strings, this method is locale-dependent.
 969
 970
 971.. method:: str.lstrip([chars])
 972
 973   Return a copy of the string with leading characters removed.  The *chars*
 974   argument is a string specifying the set of characters to be removed.  If omitted
 975   or ``None``, the *chars* argument defaults to removing whitespace.  The *chars*
 976   argument is not a prefix; rather, all combinations of its values are stripped:
 977
 978      >>> '   spacious   '.lstrip()
 979      'spacious   '
 980      >>> 'www.example.com'.lstrip('cmowz.')
 981      'example.com'
 982
 983   .. versionchanged:: 2.2.2
 984      Support for the *chars* argument.
 985
 986
 987.. method:: str.partition(sep)
 988
 989   Split the string at the first occurrence of *sep*, and return a 3-tuple
 990   containing the part before the separator, the separator itself, and the part
 991   after the separator.  If the separator is not found, return a 3-tuple containing
 992   the string itself, followed by two empty strings.
 993
 994   .. versionadded:: 2.5
 995
 996
 997.. method:: str.replace(old, new[, count])
 998
 999   Return a copy of the string with all occurrences of substring *old* replaced by
1000   *new*.  If the optional argument *count* is given, only the first *count*
1001   occurrences are replaced.
1002
1003
1004.. method:: str.rfind(sub [,start [,end]])
1005
1006   Return the highest index in the string where substring *sub* is found, such that
1007   *sub* is contained within s[start,end].  Optional arguments *start* and *end*
1008   are interpreted as in slice notation.  Return ``-1`` on failure.
1009
1010
1011.. method:: str.rindex(sub[, start[, end]])
1012
1013   Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is not
1014   found.
1015
1016
1017.. method:: str.rjust(width[, fillchar])
1018
1019   Return the string right justified in a string of length *width*. Padding is done
1020   using the specified *fillchar* (default is a space). The original string is
1021   returned if *width* is less than ``len(s)``.
1022
1023   .. versionchanged:: 2.4
1024      Support for the *fillchar* argument.
1025
1026
1027.. method:: str.rpartition(sep)
1028
1029   Split the string at the last occurrence of *sep*, and return a 3-tuple
1030   containing the part before the separator, the separator itself, and the part
1031   after the separator.  If the separator is not found, return a 3-tuple containing
1032   two empty strings, followed by the string itself.
1033
1034   .. versionadded:: 2.5
1035
1036
1037.. method:: str.rsplit([sep [,maxsplit]])
1038
1039   Return a list of the words in the string, using *sep* as the delimiter string.
1040   If *maxsplit* is given, at most *maxsplit* splits are done, the *rightmost*
1041   ones.  If *sep* is not specified or ``None``, any whitespace string is a
1042   separator.  Except for splitting from the right, :meth:`rsplit` behaves like
1043   :meth:`split` which is described in detail below.
1044
1045   .. versionadded:: 2.4
1046
1047
1048.. method:: str.rstrip([chars])
1049
1050   Return a copy of the string with trailing characters removed.  The *chars*
1051   argument is a string specifying the set of characters to be removed.  If omitted
1052   or ``None``, the *chars* argument defaults to removing whitespace.  The *chars*
1053   argument is not a suffix; rather, all combinations of its values are stripped:
1054
1055      >>> '   spacious   '.rstrip()
1056      '   spacious'
1057      >>> 'mississippi'.rstrip('ipz')
1058      'mississ'
1059
1060   .. versionchanged:: 2.2.2
1061      Support for the *chars* argument.
1062
1063
1064.. method:: str.split([sep[, maxsplit]])
1065
1066   Return a list of the words in the string, using *sep* as the delimiter
1067   string.  If *maxsplit* is given, at most *maxsplit* splits are done (thus,
1068   the list will have at most ``maxsplit+1`` elements).  If *maxsplit* is not
1069   specified, then there is no limit on the number of splits (all possible
1070   splits are made).
1071
1072   If *sep* is given, consecutive delimiters are not grouped together and are
1073   deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns
1074   ``['1', '', '2']``).  The *sep* argument may consist of multiple characters
1075   (for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``).
1076   Splitting an empty string with a specified separator returns ``['']``.
1077
1078   If *sep* is not specified or is ``None``, a different splitting algorithm is
1079   applied: runs of consecutive whitespace are regarded as a single separator,
1080   and the result will contain no empty strings at the start or end if the
1081   string has leading or trailing whitespace.  Consequently, splitting an empty
1082   string or a string consisting of just whitespace with a ``None`` separator
1083   returns ``[]``.
1084
1085   For example, ``' 1  2   3  '.split()`` returns ``['1', '2', '3']``, and
1086   ``'  1  2   3  '.split(None, 1)`` returns ``['1', '2   3  ']``.
1087
1088
1089.. method:: str.splitlines([keepends])
1090
1091   Return a list of the lines in the string, breaking at line boundaries.  Line
1092   breaks are not included in the resulting list unless *keepends* is given and
1093   true.
1094
1095
1096.. method:: str.startswith(prefix[, start[, end]])
1097
1098   Return ``True`` if string starts with the *prefix*, otherwise return ``False``.
1099   *prefix* can also be a tuple of prefixes to look for.  With optional *start*,
1100   test string beginning at that position.  With optional *end*, stop comparing
1101   string at that position.
1102
1103   .. versionchanged:: 2.5
1104      Accept tuples as *prefix*.
1105
1106
1107.. method:: str.strip([chars])
1108
1109   Return a copy of the string with the leading and trailing characters removed.
1110   The *chars* argument is a string specifying the set of characters to be removed.
1111   If omitted or ``None``, the *chars* argument defaults to removing whitespace.
1112   The *chars* argument is not a prefix or suffix; rather, all combinations of its
1113   values are stripped:
1114
1115      >>> '   spacious   '.strip()
1116      'spacious'
1117      >>> 'www.example.com'.strip('cmowz.')
1118      'example'
1119
1120   .. versionchanged:: 2.2.2
1121      Support for the *chars* argument.
1122
1123
1124.. method:: str.swapcase()
1125
1126   Return a copy of the string with uppercase characters converted to lowercase and
1127   vice versa.
1128
1129   For 8-bit strings, this method is locale-dependent.
1130
1131
1132.. method:: str.title()
1133
1134   Return a titlecased version of the string where words start with an uppercase
1135   character and the remaining characters are lowercase.
1136
1137   The algorithm uses a simple language-independent definition of a word as
1138   groups of consecutive letters.  The definition works in many contexts but
1139   it means that apostrophes in contractions and possessives form word
1140   boundaries, which may not be the desired result::
1141
1142        >>> "they're bill's friends from the UK".title()
1143        "They'Re Bill'S Friends From The Uk"
1144
1145   A workaround for apostrophes can be constructed using regular expressions::
1146
1147        >>> import re
1148        >>> def titlecase(s):
1149                return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
1150                              lambda mo: mo.group(0)[0].upper() +
1151                                         mo.group(0)[1:].lower(),
1152                              s)
1153
1154        >>> titlecase("they're bill's friends.")
1155        "They're Bill's Friends."
1156
1157   For 8-bit strings, this method is locale-dependent.
1158
1159
1160.. method:: str.translate(table[, deletechars])
1161
1162   Return a copy of the string where all characters occurring in the optional
1163   argument *deletechars* are removed, and the remaining characters have been
1164   mapped through the given translation table, which must be a string of length
1165   256.
1166
1167   You can use the :func:`maketrans` helper function in the :mod:`string` module to
1168   create a translation table. For string objects, set the *table* argument to
1169   ``None`` for translations that only delete characters:
1170
1171      >>> 'read this short text'.translate(None, 'aeiou')
1172      'rd ths shrt txt'
1173
1174   .. versionadded:: 2.6
1175      Support for a ``None`` *table* argument.
1176
1177   For Unicode objects, the :meth:`translate` method does not accept the optional
1178   *deletechars* argument.  Instead, it returns a copy of the *s* where all
1179   characters have been mapped through the given translation table which must be a
1180   mapping of Unicode ordinals to Unicode ordinals, Unicode strings or ``None``.
1181   Unmapped characters are left untouched. Characters mapped to ``None`` are
1182   deleted.  Note, a more flexible approach is to create a custom character mapping
1183   codec using the :mod:`codecs` module (see :mod:`encodings.cp1251` for an
1184   example).
1185
1186
1187.. method:: str.upper()
1188
1189   Return a copy of the string converted to uppercase.
1190
1191   For 8-bit strings, this method is locale-dependent.
1192
1193
1194.. method:: str.zfill(width)
1195
1196   Return the numeric string left filled with zeros in a string of length
1197   *width*.  A sign prefix is handled correctly.  The original string is
1198   returned if *width* is less than ``len(s)``.
1199
1200
1201   .. versionadded:: 2.2.2
1202
1203The following methods are present only on unicode objects:
1204
1205.. method:: unicode.isnumeric()
1206
1207   Return ``True`` if there are only numeric characters in S, ``False``
1208   otherwise. Numeric characters include digit characters, and all characters
1209   that have the Unicode numeric value property, e.g. U+2155,
1210   VULGAR FRACTION ONE FIFTH.
1211
1212.. method:: unicode.isdecimal()
1213
1214   Return ``True`` if there are only decimal characters in S, ``False``
1215   otherwise. Decimal characters include digit characters, and all characters
1216   that that can be used to form decimal-radix numbers, e.g. U+0660,
1217   ARABIC-INDIC DIGIT ZERO.
1218
1219
1220.. _string-formatting:
1221
1222String Formatting Operations
1223----------------------------
1224
1225.. index::
1226   single: formatting, string (%)
1227   single: interpolation, string (%)
1228   single: string; formatting
1229   single: string; interpolation
1230   single: printf-style formatting
1231   single: sprintf-style formatting
1232   single: % formatting
1233   single: % interpolation
1234
1235String and Unicode objects have one unique built-in operation: the ``%``
1236operator (modulo).  This is also known as the string *formatting* or
1237*interpolation* operator.  Given ``format % values`` (where *format* is a string
1238or Unicode object), ``%`` conversion specifications in *format* are replaced
1239with zero or more elements of *values*.  The effect is similar to the using
1240:cfunc:`sprintf` in the C language.  If *format* is a Unicode object, or if any
1241of the objects being converted using the ``%s`` conversion are Unicode objects,
1242the result will also be a Unicode object.
1243
1244If *format* requires a single argument, *values* may be a single non-tuple
1245object. [#]_  Otherwise, *values* must be a tuple with exactly the number of
1246items specified by the format string, or a single mapping object (for example, a
1247dictionary).
1248
1249A conversion specifier contains two or more characters and has the following
1250components, which must occur in this order:
1251
1252#. The ``'%'`` character, which marks the start of the specifier.
1253
1254#. Mapping key (optional), consisting of a parenthesised sequence of characters
1255   (for example, ``(somename)``).
1256
1257#. Conversion flags (optional), which affect the result of some conversion
1258   types.
1259
1260#. Minimum field width (optional).  If specified as an ``'*'`` (asterisk), the
1261   actual width is read from the next element of the tuple in *values*, and the
1262   object to convert comes after the minimum field width and optional precision.
1263
1264#. Precision (optional), given as a ``'.'`` (dot) followed by the precision.  If
1265   specified as ``'*'`` (an asterisk), the actual width is read from the next
1266   element of the tuple in *values*, and the value to convert comes after the
1267   precision.
1268
1269#. Length modifier (optional).
1270
1271#. Conversion type.
1272
1273When the right argument is a dictionary (or other mapping type), then the
1274formats in the string *must* include a parenthesised mapping key into that
1275dictionary inserted immediately after the ``'%'`` character. The mapping key
1276selects the value to be formatted from the mapping.  For example:
1277
1278   >>> print '%(language)s has %(#)03d quote types.' % \
1279   ...       {'language': "Python", "#": 2}
1280   Python has 002 quote types.
1281
1282In this case no ``*`` specifiers may occur in a format (since they require a
1283sequential parameter list).
1284
1285The conversion flag characters are:
1286
1287+---------+---------------------------------------------------------------------+
1288| Flag    | Meaning                                                             |
1289+=========+=====================================================================+
1290| ``'#'`` | The value conversion will use the "alternate form" (where defined   |
1291|         | below).                                                             |
1292+---------+---------------------------------------------------------------------+
1293| ``'0'`` | The conversion will be zero padded for numeric values.              |
1294+---------+---------------------------------------------------------------------+
1295| ``'-'`` | The converted value is left adjusted (overrides the ``'0'``         |
1296|         | conversion if both are given).                                      |
1297+---------+---------------------------------------------------------------------+
1298| ``' '`` | (a space) A blank should be left before a positiv…

Large files files are truncated, but you can click here to view the full file