mirror/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2024-10-06 06:50:00 +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
.. _string-formatting:
@ -120,63 +122,27 @@ literal text, it can be escaped by doubling: ``{{`` and ``}}``.
The grammar for a replacement field is as follows:
.. productionlist:: sf
replacement_field: "{" [`field_name`] [":" `format_spec`] "}"
field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
arg_name: [`identifier` | `integer`]
attribute_name: `identifier`
element_index: `integer` | `index_string`
index_string: <any source character except "]"> +
replacement_field: "{" [`arg_index`] [":" `format_spec`] "}"
arg_index: `integer`
format_spec: <described in the next section>
In less formal terms, the replacement field can start with a *field_name* that specifies
the object whose value is to be formatted and inserted
into the output instead of the replacement field.
The *field_name* is optionally followed by a *format_spec*, which is preceded
In less formal terms, the replacement field can start with an *arg_index*
that specifies the argument whose value is to be formatted and inserted into
the output instead of the replacement field.
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.
See also the :ref:`formatspec` section.
The *field_name* itself begins with an *arg_name* that is 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
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}'``.
If the numerical arg_indexes in a format string 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.
Some simple format string examples::
"First, thou shalt count to {0}" # References first positional argument
"Bring me a {}" # Implicitly references the first positional argument
"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
"First, thou shalt count to {0}" // References first positional argument
"Bring me a {}" // Implicitly references the first positional argument
"From {} to {}" // Same as "From {0} to {1}"
The *format_spec* field contains a specification of how the value should be
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.
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
format_spec are substituted before the *format_spec* string is interpreted.
This allows the formatting of a value to be dynamically specified.
These nested replacement fields can contain only an argument index;
format specifications are not allowed. Formatting is performed as if 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.
See the :ref:`formatexamples` section for some examples.