# std::range_formatter

> C++ Atlas: `cppatlas.com/w/cpp/utility/format/range_formatter` | Source: https://en.cppreference.com/w/cpp/utility/format/range_formatter | Domain: Utility | Standards: C++20, C++23

std::range_formatter is a helper class template for implementing range std::formatter specializations.

## Official Specification Summary (cppreference)

```cpp
// Defined in header <format>

template< class T, class CharT = char >
    requires std::same_as<std::remove_cvref_t<T>, T> && std::formattable<T, CharT>
class range_formatter; // (since C++23)
```

`std::range_formatter` is a helper class template for implementing range `std::formatter` specializations.

#### Range format specification

The syntax of *range-format-spec* is:

- *range-fill-and-align* (optional) *width* (optional) `n` (optional) *range-type* (optional) *range-underlying-spec* (optional)

The *range-fill-and-align* is interpreted the same way as a *fill-and-align* except that the *fill* in *range-fill-and-align* is any character other than `{`, `}`, or `:`.

The *width* is described in standard format width specification.

The `n` option causes the range to be formatted without the opening and closing brackets.

```cpp
assert(std::format("{}", views::iota(1, 5)) == "[1, 2, 3, 4]");
assert(std::format("{:n}", views::iota(1, 5)) == "1, 2, 3, 4");
```

The *format-spec* in a *range-underlying-spec* (its syntax is equivalent to `:` *format-spec*), if any, is interpreted by the range element formatter `std::formatter<T, CharT>`.

```cpp
std::array ints{12, 10, 15, 14};

assert(std::format("{}", ints) == "[12, 10, 15, 14]");
assert(std::format("{::X}", ints) == "[C, A, F, E]");
assert(std::format("{:n:_^4}", ints) == "_12_, _10_, _15_, _14_");
```

The *range-type* changes the way a range is formatted, with certain options only valid with certain argument types.

The available range presentation types are:

- `m`: Indicates that the opening bracket should be `"{"`, the closing bracket should be `"}"`, the separator should be `", "`, and each range element should be formatted as if `m` were specified for its *tuple-type* (in *tuple-format-spec*).

  - If `m` is chosen as the *range-type*, the program is ill-formed unless `T` is either a specialization of:

  - `std::pair`, or
  - `std::tuple` such that `std::tuple_size_v<T> == 2` is `true`.

```cpp
std::array char_pairs
{
    std::pair{'A', 5}, std::pair{'B', 10}, std::pair{'C', 12}
};

assert(std::format("{}", char_pairs) == "[('A', 5), ('B', 10), ('C', 12)]");
assert(std::format("{:m}", char_pairs) == "{'A': 5, 'B': 10, 'C': 12}");
```

- `s`: Indicates that the range should be formatted as a string.
- `?s`: Indicates that the range should be formatted as an escaped string.

  - If `s` or `?s` is chosen as the *range-type*, both `n` option and *range-underlying-spec* should not be included in the format specifier, and
  - the program is ill-formed unless `T` is `CharT`.

```cpp
std::array star{'S', 'T', 'A', 'R'};

assert(std::format("{}", star) == "['S', 'T', 'A', 'R']");
assert(std::format("{:s}", star) == "STAR");
assert(std::format("{:?s}", star) == "\"STAR\"");
```

#### Data members

**Member name — Definition**

- `std::formatter<T, CharT>` `underlying_` (private): the underlying formatter for elements (exposition-only member object*)
- `std::basic_string_view<CharT>` `separator_` (private): a string representing the separator of the range formatted result. The default separator is `", "`. (exposition-only member object*)
- `std::basic_string_view<CharT>` `opening-bracket_` (private): a string representing the opening bracket of the range formatted result. The default opening bracket is `"["`. (exposition-only member object*)
- `std::basic_string_view<CharT>` `closing-bracket_` (private): a string representing the closing bracket of the range formatted result. The default closing bracket is `"]"`. (exposition-only member object*)

#### Member functions

- `set_separator`: sets a specified separator for the range formatted result (public member function)
- `set_brackets`: sets a specified opening and closing brackets for the range formatted result (public member function)
- `underlying`: returns the underlying formatter (public member function)
- `parse`: parses the format specifier as specified by *range-format-spec* (public member function)
- `format`: writes the range formatted output as specified by *range-format-spec* (public member function)

### std::range_formatter::set_separator

```cpp
constexpr void set_separator( std::basic_string_view<CharT> sep ) noexcept;
```

Assigns `sep` to `separator_`.

### std::range_formatter::set_brackets

```cpp
constexpr void set_brackets( std::basic_string_view<CharT> opening,
                             std::basic_string_view<CharT> closing ) noexcept;
```

Assigns `opening` and `closing` to `opening-bracket_` and `closing-bracket_`, respectively.

### std::range_formatter::underlying

```cpp
constexpr std::formatter<T, CharT>& underlying(); // (1)
constexpr const std::formatter<T, CharT>& underlying() const; // (2)
```

Returns `underlying_` (the underlying formatter).

### std::range_formatter::parse

```cpp
template< class ParseContext >
constexpr auto parse( ParseContext& ctx ) -> ParseContext::iterator;
```

Parses the format specifiers as a *range-format-spec* and stores the parsed specifiers in the current object.

Calls `underlying_.parse(ctx)` to parse *format-spec* in *range-format-spec* or, if the latter is not present, an empty *format-spec*.

If *range-type* or the `n` option is present, the values of `opening-bracket_`, `closing-bracket_`, and `separator_` are modified as required.

It calls `underlying_.set_debug_format()` if:

- the *range-type* is neither `s` nor `?s`,
- `underlying_.set_debug_format()` is a valid expression, and
- there is no *range-underlying-spec*.

Returns an iterator past the end of the *range-format-spec*.

### std::range_formatter::format

```cpp
template< ranges::input_range R, class FormatContext >
  requires std::formattable<ranges::range_reference_t<R>, CharT> &&
           std::same_as<std::remove_cvref_t<ranges::range_reference_t<R>>, T>
auto format( R&& r, FormatContext& ctx ) const -> FormatContext::iterator;
```

If the *range-type* was either `s` or `?s`, it writes the formatted `std::basic_string<CharT>(std::from_range, r)` as a string or an escaped string, respectively, into `ctx.out()`.

Otherwise, it writes the following into `ctx.out()` as specified by *range-format-spec*, in order:

- `opening-bracket_`,
- for each formattable element `e` of the range `r`:

  - the result of writing `e` via `underlying_`, and
  - `separator_`, unless `e` is the last element of `r`, and

- `closing-bracket_`.

Returns an iterator past the end of the output range.

#### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 3892 | C++23 | the formatting of nested ranges was incorrect | corrected |

#### See also

- [`formatter`](https://en.cppreference.com/w/cpp/utility/format/formatter) (C++20): defines formatting rules for a given type (class template)

---
Attribution: content from https://en.cppreference.com/w/cpp/utility/format/range_formatter (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.