Range formatting documentation (#3905)

This commit is contained in:
js324 2024-03-24 17:39:16 -04:00 committed by GitHub
parent 5d63e87d23
commit 88620e53a4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -491,13 +491,31 @@ Range Format Specifications
Format specifications for range types have the following syntax:
.. productionlist:: sf
range_format_spec: [":" [`underlying_spec`]]
range_format_spec: [":" ["n"][`range_type`][`range_underlying_spec`]]
The `underlying_spec` is parsed based on the formatter of the range's
The ``'n'`` option formats the range without the opening and closing brackets.
The available presentation types for `range_type` are:
+---------+----------------------------------------------------------+
| Type | Meaning |
+=========+==========================================================+
| ``'s'`` | String format. The range is formatted as a string. |
+---------+----------------------------------------------------------+
| ``'?s'``| Debug format. The range is formatted as an escaped |
| | string. |
+---------+----------------------------------------------------------+
| none | Default format. The range is formatted with a separator. |
+---------+----------------------------------------------------------+
If `range_type` is ``'s'`` or ``'?s'``, the range element type must be a character type. The
``'n'`` option and `range_underlying_spec` are mutually exclusive with ``'s'`` and ``'?s'``.
The `range_underlying_spec` is parsed based on the formatter of the range's
reference type.
By default, a range of characters or strings is printed escaped and quoted. But
if any `underlying_spec` is provided (even if it is empty), then the characters
if any `range_underlying_spec` is provided (even if it is empty), then the characters
or strings are printed according to the provided specification.
Examples::
@ -508,6 +526,12 @@ Examples::
// Result: [0xa, 0x14, 0x1e]
fmt::format("{}", vector{'h', 'e', 'l', 'l', 'o'});
// Result: ['h', 'e', 'l', 'l', 'o']
fmt::format("{:n}", vector{'h', 'e', 'l', 'l', 'o'});
// Result: 'h', 'e', 'l', 'l', 'o'
fmt::format("{:s}", vector{'h', 'e', 'l', 'l', 'o'});
// Result: "hello"
fmt::format("{:?s}", vector{'h', 'e', 'l', 'l', 'o', '\n'});
// Result: "hello\n"
fmt::format("{::}", vector{'h', 'e', 'l', 'l', 'o'});
// Result: [h, e, l, l, o]
fmt::format("{::d}", vector{'h', 'e', 'l', 'l', 'o'});