Skip to content

Commit 329b671

Browse files
js324harryzhurov
authored andcommitted
Range formatting documentation (fmtlib#3905)
1 parent 3ff55b1 commit 329b671

File tree

1 file changed

+27
-3
lines changed

1 file changed

+27
-3
lines changed

Diff for: doc/syntax.rst

+27-3
Original file line numberDiff line numberDiff line change
@@ -491,13 +491,31 @@ Range Format Specifications
491491
Format specifications for range types have the following syntax:
492492

493493
.. productionlist:: sf
494-
range_format_spec: [":" [`underlying_spec`]]
494+
range_format_spec: [":" ["n"][`range_type`][`range_underlying_spec`]]
495495

496-
The `underlying_spec` is parsed based on the formatter of the range's
496+
The ``'n'`` option formats the range without the opening and closing brackets.
497+
498+
The available presentation types for `range_type` are:
499+
500+
+---------+----------------------------------------------------------+
501+
| Type | Meaning |
502+
+=========+==========================================================+
503+
| ``'s'`` | String format. The range is formatted as a string. |
504+
+---------+----------------------------------------------------------+
505+
| ``'?s'``| Debug format. The range is formatted as an escaped |
506+
| | string. |
507+
+---------+----------------------------------------------------------+
508+
| none | Default format. The range is formatted with a separator. |
509+
+---------+----------------------------------------------------------+
510+
511+
If `range_type` is ``'s'`` or ``'?s'``, the range element type must be a character type. The
512+
``'n'`` option and `range_underlying_spec` are mutually exclusive with ``'s'`` and ``'?s'``.
513+
514+
The `range_underlying_spec` is parsed based on the formatter of the range's
497515
reference type.
498516

499517
By default, a range of characters or strings is printed escaped and quoted. But
500-
if any `underlying_spec` is provided (even if it is empty), then the characters
518+
if any `range_underlying_spec` is provided (even if it is empty), then the characters
501519
or strings are printed according to the provided specification.
502520

503521
Examples::
@@ -508,6 +526,12 @@ Examples::
508526
// Result: [0xa, 0x14, 0x1e]
509527
fmt::format("{}", vector{'h', 'e', 'l', 'l', 'o'});
510528
// Result: ['h', 'e', 'l', 'l', 'o']
529+
fmt::format("{:n}", vector{'h', 'e', 'l', 'l', 'o'});
530+
// Result: 'h', 'e', 'l', 'l', 'o'
531+
fmt::format("{:s}", vector{'h', 'e', 'l', 'l', 'o'});
532+
// Result: "hello"
533+
fmt::format("{:?s}", vector{'h', 'e', 'l', 'l', 'o', '\n'});
534+
// Result: "hello\n"
511535
fmt::format("{::}", vector{'h', 'e', 'l', 'l', 'o'});
512536
// Result: [h, e, l, l, o]
513537
fmt::format("{::d}", vector{'h', 'e', 'l', 'l', 'o'});

0 commit comments

Comments
 (0)