Skip to content

Commit

Permalink
Merged revisions 82455,82457,82459 via svnmerge from
Browse files Browse the repository at this point in the history 
svn+ssh://[email protected]/python/trunk

........
  r82455 | eric.smith | 2010-07-03 00:44:16 +0300 (Sat, 03 Jul 2010) | 1 line

  Moved period outside paren, where it belongs.
........
  r82457 | ezio.melotti | 2010-07-03 01:17:29 +0300 (Sat, 03 Jul 2010) | 1 line

  #9139: Add examples for str.format().
........
  r82459 | ezio.melotti | 2010-07-03 01:50:39 +0300 (Sat, 03 Jul 2010) | 1 line

  #9139: the thousands separator is new in 2.7.  Also add a missing variable in the example.
........
  • Loading branch information
@ezio-melotti
ezio-melotti committed Jul 2, 2010
1 parent 8315fd1 commit d2191e0
Showing 1 changed file with 155 additions and 24 deletions.
179 changes: 155 additions & 24 deletions Doc/library/string.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ implementation as the built-in :meth:`format` method.
.. method:: convert_field(value, conversion)

Converts the value (returned by :meth:`get_field`) given a conversion type
(as in the tuple returned by the :meth:`parse` method.) The default
(as in the tuple returned by the :meth:`parse` method). The default
version understands 'r' (repr) and 's' (str) conversion types.


Expand All @@ -185,7 +185,7 @@ Format String Syntax

The :meth:`str.format` method and the :class:`Formatter` class share the same
syntax for format strings (although in the case of :class:`Formatter`,
subclasses can define their own format string syntax.)
subclasses can define their own format string syntax).

Format strings contain "replacement fields" surrounded by curly braces ``{}``.
Anything that is not contained in braces is considered literal text, which is
Expand All @@ -211,6 +211,8 @@ The *field_name* is optionally followed by a *conversion* field, which is
preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded
by a colon ``':'``. These specify a non-default format for the replacement value.

See also the :ref:`formatspec` section.

The *field_name* itself begins with an *arg_name* that is either either a number or a
keyword. If it's a number, it refers to a positional argument, and if it's a keyword,
it refers to a named keyword argument. If the numerical arg_names in a format string
Expand All @@ -221,6 +223,10 @@ attribute expressions. An expression of the form ``'.name'`` selects the named
attribute using :func:`getattr`, while an expression of the form ``'[index]'``
does an index lookup using :func:`__getitem__`.

.. versionchanged:: 3.1
The positional argument specifiers can be omitted, so ``'{} {}'`` is
equivalent to ``'{0} {1}'``.

Some simple format string examples::

"First, thou shalt count to {0}" # References first positional argument
Expand Down Expand Up @@ -261,26 +267,7 @@ and format specifications are not allowed. The replacement fields within the
format_spec are substituted before the *format_spec* string is interpreted.
This allows the formatting of a value to be dynamically specified.

For example, suppose you wanted to have a replacement field whose field width is
determined by another variable::

"A man with two {0:{1}}".format("noses", 10)

This would first evaluate the inner replacement field, making the format string
effectively::

"A man with two {0:10}"

Then the outer replacement field would be evaluated, producing::

"noses "

Which is substituted into the string, yielding::

"A man with two noses "

(The extra space is because we specified a field width of 10, and because left
alignment is the default for strings.)
See the :ref:`formatexamples` section for some examples.


.. _formatspec:
Expand All @@ -290,7 +277,7 @@ Format Specification Mini-Language

"Format specifications" are used within replacement fields contained within a
format string to define how individual values are presented (see
:ref:`formatstrings`.) They can also be passed directly to the built-in
:ref:`formatstrings`). They can also be passed directly to the built-in
:func:`format` function. Each formattable type may define how the format
specification is to be interpreted.

Expand Down Expand Up @@ -324,7 +311,7 @@ The meaning of the various alignment options is as follows:
| Option | Meaning |
+=========+==========================================================+
| ``'<'`` | Forces the field to be left-aligned within the available |
| | space (This is the default.) |
| | space (this is the default). |
+---------+----------------------------------------------------------+
| ``'>'`` | Forces the field to be right-aligned within the |
| | available space. |
Expand Down Expand Up @@ -366,6 +353,9 @@ The ``','`` option signals the use of a comma for a thousands separator.
For a locale aware separator, use the ``'n'`` integer presentation type
instead.

.. versionchanged:: 3.1
Added the ``','`` option (see also :pep:`378`).

*width* is a decimal integer defining the minimum field width. If not
specified, then the field width will be determined by the content.

Expand Down Expand Up @@ -484,6 +474,147 @@ The available presentation types for floating point and decimal values are:
+---------+----------------------------------------------------------+


.. _formatexamples:

Format examples
^^^^^^^^^^^^^^^

This section contains examples of the new format syntax and comparison with
the old ``%``-formatting.

In most of the cases the syntax is similar to the old ``%``-formatting, with the
addition of the ``{}`` and with ``:`` used instead of ``%``.
For example, ``'%03.2f'`` can be translated to ``'{:03.2f}'``.

The new format syntax also supports new and different options, shown in the
follow examples.

Accessing arguments by position::

>>> '{0}, {1}, {2}'.format('a', 'b', 'c')
'a, b, c'
>>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only
'a, b, c'
>>> '{2}, {1}, {0}'.format('a', 'b', 'c')
'c, b, a'
>>> '{2}, {1}, {0}'.format(*'abc') # unpacking argument sequence
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad') # arguments' indices can be repeated
'abracadabra'

Accessing arguments by name::

>>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
'Coordinates: 37.24N, -115.81W'
>>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
>>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
'Coordinates: 37.24N, -115.81W'

Accessing arguments' attributes::

>>> c = 3-5j
>>> ('The complex number {0} is formed from the real part {0.real} '
... 'and the imaginary part {0.imag}.').format(c)
'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
>>> class Point:
... def __init__(self, x, y):
... self.x, self.y = x, y
... def __str__(self):
... return 'Point({self.x}, {self.y})'.format(self=self)
...
>>> str(Point(4, 2))
'Point(4, 2)'

Accessing arguments' items::

>>> coord = (3, 5)
>>> 'X: {0[0]}; Y: {0[1]}'.format(coord)
'X: 3; Y: 5'

Replacing ``%s`` and ``%r``::

>>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"

Aligning the text and specifying a width::

>>> '{:<30}'.format('left aligned')
'left aligned '
>>> '{:>30}'.format('right aligned')
' right aligned'
>>> '{:^30}'.format('centered')
' centered '
>>> '{:*^30}'.format('centered') # use '*' as a fill char
'***********centered***********'

Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign::

>>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it always
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14) # show a space for positive numbers
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the minus -- same as '{:f}; {:f}'
'3.140000; -3.140000'

Replacing ``%x`` and ``%o`` and converting the value to different bases::

>>> # format also supports binary numbers
>>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}".format(42)
'int: 42; hex: 2a; oct: 52; bin: 101010'
>>> # with 0x, 0o, or 0b as prefix:
>>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42)
'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'

Using the comma as a thousands separator::

>>> '{:,}'.format(1234567890)
'1,234,567,890'

Expressing a percentage::

>>> points = 19
>>> total = 22
>>> 'Correct answers: {:.2%}.'.format(points/total)
'Correct answers: 86.36%'

Using type-specific formatting::

>>> import datetime
>>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
>>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
'2010-07-04 12:15:58'

Nesting arguments and more complex examples::

>>> for align, text in zip('<^>', ['left', 'center', 'right']):
... '{0:{align}{fill}16}'.format(text, fill=align, align=align)
...
'left<<<<<<<<<<<<'
'^^^^^center^^^^^'
'>>>>>>>>>>>right'
>>>
>>> octets = [192, 168, 0, 1]
>>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
'C0A80001'
>>> int(_, 16)
3232235521
>>>
>>> width = 5
>>> for num in range(5,12):
... for base in 'dXob':
... print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
... print()
...
5 5 5 101
6 6 6 110
7 7 7 111
8 8 10 1000
9 9 11 1001
10 A 12 1010
11 B 13 1011



.. _template-strings:

Template strings
Expand Down

0 comments on commit d2191e0

Please sign in to comment.