diff options
Diffstat (limited to 'Doc/library/string.rst')
| -rw-r--r-- | Doc/library/string.rst | 27 |
1 files changed, 15 insertions, 12 deletions
diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 2bd8dfd..5b917d9 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -75,14 +75,14 @@ The constants defined in this module are: .. _string-formatting: -String Formatting ------------------ +Custom String Formatting +------------------------ The built-in string class provides the ability to do complex variable -substitutions and value formatting via the :func:`format` method described in +substitutions and value formatting via the :meth:`~str.format` method described in :pep:`3101`. The :class:`Formatter` class in the :mod:`string` module allows you to create and customize your own string formatting behaviors using the same -implementation as the built-in :meth:`format` method. +implementation as the built-in :meth:`~str.format` method. .. class:: Formatter @@ -91,9 +91,9 @@ implementation as the built-in :meth:`format` method. .. method:: format(format_string, *args, **kwargs) - :meth:`format` is the primary API method. It takes a format string and + The primary API method. It takes a format string and an arbitrary set of positional and keyword arguments. - :meth:`format` is just a wrapper that calls :meth:`vformat`. + It is just a wrapper that calls :meth:`vformat`. .. deprecated:: 3.5 Passing a format string as keyword argument *format_string* has been @@ -267,8 +267,9 @@ Most built-in types support a common formatting mini-language, which is described in the next section. A *format_spec* field can also include nested replacement fields within it. -These nested replacement fields can contain only a field name; conversion flags -and format specifications are not allowed. The replacement fields within the +These nested replacement fields may contain a field name, conversion flag +and format specification, but deeper nesting is +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. @@ -306,8 +307,10 @@ The general form of a *standard format specifier* is: If a valid *align* value is specified, it can be preceded by a *fill* character that can be any character and defaults to a space if omitted. -Note that it is not possible to use ``{`` and ``}`` as *fill* char while -using the :meth:`str.format` method; this limitation however doesn't +It is not possible to use a literal curly brace ("``{``" or "``}``") as +the *fill* character when using the :meth:`str.format` +method. However, it is possible to insert a curly brace +with a nested replacement field. This limitation doesn't affect the :func:`format` function. The meaning of the various alignment options is as follows: @@ -496,8 +499,8 @@ The available presentation types for floating point and decimal values are: Format examples ^^^^^^^^^^^^^^^ -This section contains examples of the new format syntax and comparison with -the old ``%``-formatting. +This section contains examples of the :meth:`str.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 ``%``. |