mirror/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2024-12-24 12:14:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Adapt "Format String Syntax" for the format library.

Browse Source
This commit is contained in:
Victor Zverovich 2012-12-18 08:41:59 -08:00
parent a658427bbf
commit 2a95e670e5
1 changed files with 19 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
doc/string.rst
View File

@ -1,3 +1,5 @@
.. highlight:: c++
.. ifconfig:: False .. ifconfig:: False
.. _string-formatting: .. _string-formatting:
@ -120,63 +122,27 @@ literal text, it can be escaped by doubling: ``{{`` and ``}}``.
The grammar for a replacement field is as follows: The grammar for a replacement field is as follows:
.. productionlist:: sf .. productionlist:: sf
replacement_field: "{" [`field_name`] [":" `format_spec`] "}" replacement_field: "{" [`arg_index`] [":" `format_spec`] "}"
field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")* arg_index: `integer`
arg_name: [`identifier` | `integer`]
attribute_name: `identifier`
element_index: `integer` | `index_string`
index_string: <any source character except "]"> +
format_spec: <described in the next section> format_spec: <described in the next section>
In less formal terms, the replacement field can start with a *field_name* that specifies In less formal terms, the replacement field can start with an *arg_index*
the object whose value is to be formatted and inserted that specifies the argument whose value is to be formatted and inserted into
into the output instead of the replacement field. the output instead of the replacement field.
The *field_name* is optionally followed by a *format_spec*, which is preceded The *arg_index* is optionally followed by a *format_spec*, which is preceded
by a colon ``':'``. These specify a non-default format for the replacement value. by a colon ``':'``. These specify a non-default format for the replacement value.
See also the :ref:`formatspec` section. See also the :ref:`formatspec` section.
The *field_name* itself begins with an *arg_name* that is either a number or a If the numerical arg_indexes in a format string are 0, 1, 2, ... in sequence,
keyword. If it's a number, it refers to a positional argument, and if it's a keyword, they can all be omitted (not just some) and the numbers 0, 1, 2, ... will be
it refers to a named keyword argument. If the numerical arg_names in a format string automatically inserted in that order.
are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
and the numbers 0, 1, 2, ... will be automatically inserted in that order.
Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary
dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string.
The *arg_name* can be followed by any number of index or
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:: Some simple format string examples::
"First, thou shalt count to {0}" # References first positional argument "First, thou shalt count to {0}" // References first positional argument
"Bring me a {}" # Implicitly references the first positional argument "Bring me a {}" // Implicitly references the first positional argument
"From {} to {}" # Same as "From {0} to {1}" "From {} to {}" // Same as "From {0} to {1}"
"My quest is {name}" # References keyword argument 'name'
"Weight in tons {0.weight}" # 'weight' attribute of first positional arg
"Units destroyed: {players[0]}" # First element of keyword argument 'players'.
The *conversion* field causes a type coercion before formatting. Normally, the
job of formatting a value is done by the :meth:`__format__` method of the value
itself. However, in some cases it is desirable to force a type to be formatted
as a string, overriding its own definition of formatting. By converting the
value to a string before calling :meth:`__format__`, the normal formatting logic
is bypassed.
Three conversion flags are currently supported: ``'!s'`` which calls :func:`str`
on the value, ``'!r'`` which calls :func:`repr` and ``'!a'`` which calls
:func:`ascii`.
Some examples::
"Harold's a clever {0!s}" # Calls str() on the argument first
"Bring out the holy {name!r}" # Calls repr() on the argument first
"More {!a}" # Calls ascii() on the argument first
The *format_spec* field contains a specification of how the value should be The *format_spec* field contains a specification of how the value should be
presented, including such details as field width, alignment, padding, decimal presented, including such details as field width, alignment, padding, decimal
@ -187,10 +153,11 @@ Most built-in types support a common formatting mini-language, which is
described in the next section. described in the next section.
A *format_spec* field can also include nested replacement fields within it. A *format_spec* field can also include nested replacement fields within it.
These nested replacement fields can contain only a field name; conversion flags These nested replacement fields can contain only an argument index;
and format specifications are not allowed. The replacement fields within the format specifications are not allowed. Formatting is performed as if the
format_spec are substituted before the *format_spec* string is interpreted. replacement fields within the format_spec are substituted before the
This allows the formatting of a value to be dynamically specified. *format_spec* string is interpreted. This allows the formatting of a value
to be dynamically specified.
See the :ref:`formatexamples` section for some examples. See the :ref:`formatexamples` section for some examples.