From c3c38f496471d509dae0b13e45d527a28db6b3bc Mon Sep 17 00:00:00 2001 From: Jin S Date: Mon, 4 Mar 2024 11:37:44 -0500 Subject: [PATCH 1/4] range format documentation --- doc/syntax.rst | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/doc/syntax.rst b/doc/syntax.rst index 1274727d3496..563d6f330465 100644 --- a/doc/syntax.rst +++ b/doc/syntax.rst @@ -491,7 +491,25 @@ 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 `n` option causes the range to be formatted 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 underlying type of the range must be a char type. The `underlying_spec` is parsed based on the formatter of the range's reference type. From fe0a6b7c674a59c4f242de431851a255b3246a85 Mon Sep 17 00:00:00 2001 From: Jin S Date: Fri, 22 Mar 2024 11:23:50 -0400 Subject: [PATCH 2/4] examples --- doc/syntax.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/doc/syntax.rst b/doc/syntax.rst index 563d6f330465..ad0facd70c45 100644 --- a/doc/syntax.rst +++ b/doc/syntax.rst @@ -493,7 +493,7 @@ Format specifications for range types have the following syntax: .. productionlist:: sf range_format_spec: [":" [`n`][`range_type`][`range_underlying_spec`]] -The `n` option causes the range to be formatted without the opening and closing brackets. +The `n` option formats the range without the opening and closing brackets. The available presentation types for `range_type` are: @@ -509,7 +509,8 @@ The available presentation types for `range_type` are: | | | +---------+----------------------------------------------------------+ -If `range_type` is `s` or `?s`, the underlying type of the range must be a char type. +If `range_type` is `s` or `?s`, the underlying type of the range must be a character type. The +`n` option and `range_underlying_spec` are mutually exclusive with `s` and `?s`. The `underlying_spec` is parsed based on the formatter of the range's reference type. @@ -526,6 +527,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'}); From 8af29e0560024cb2dd39402a7e36a81267a95f1e Mon Sep 17 00:00:00 2001 From: Jin S Date: Fri, 22 Mar 2024 11:50:09 -0400 Subject: [PATCH 3/4] change formatting --- doc/syntax.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/syntax.rst b/doc/syntax.rst index ad0facd70c45..c6cd865ada8b 100644 --- a/doc/syntax.rst +++ b/doc/syntax.rst @@ -491,9 +491,9 @@ Range Format Specifications Format specifications for range types have the following syntax: .. productionlist:: sf - range_format_spec: [":" [`n`][`range_type`][`range_underlying_spec`]] + range_format_spec: [":" ["n"][`range_type`][`range_underlying_spec`]] -The `n` option formats the range without the opening and closing brackets. +The ``'n'`` option formats the range without the opening and closing brackets. The available presentation types for `range_type` are: @@ -505,18 +505,18 @@ The available presentation types for `range_type` are: | ``'?s'``| Debug format. The range is formatted as an escaped | | | string. | +---------+----------------------------------------------------------+ -| none | Default format. The range is formatted with a separator | +| none | Default format. The range is formatted with a separator. | | | | +---------+----------------------------------------------------------+ -If `range_type` is `s` or `?s`, the underlying type of the range must be a character type. The -`n` option and `range_underlying_spec` are mutually exclusive with `s` and `?s`. +If `range_type` is ``'s'`` or ``'?s'``, the underlying type of the range must be a character type. The +``'n'`` option and `range_underlying_spec` are mutually exclusive with ``'s'`` and ``'?s'``. -The `underlying_spec` is parsed based on the formatter of the range'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:: From 71f0bc24d072e4ba2ea33887336c10bf493df00e Mon Sep 17 00:00:00 2001 From: Jin S Date: Sat, 23 Mar 2024 09:32:23 -0400 Subject: [PATCH 4/4] minor changes --- doc/syntax.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/syntax.rst b/doc/syntax.rst index c6cd865ada8b..557e4fd0aa3a 100644 --- a/doc/syntax.rst +++ b/doc/syntax.rst @@ -506,10 +506,9 @@ The available presentation types for `range_type` are: | | string. | +---------+----------------------------------------------------------+ | none | Default format. The range is formatted with a separator. | -| | | +---------+----------------------------------------------------------+ -If `range_type` is ``'s'`` or ``'?s'``, the underlying type of the range must be a character type. The +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