# std::basic_format_context

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

Provides access to formatting state consisting of the formatting arguments and the output iterator.

## Official Specification Summary (cppreference)

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

template< class OutputIt, class CharT >
class basic_format_context; // (1) (since C++20)

using format_context = basic_format_context</* unspecified */, char>; // (2) (since C++20)

using wformat_context = basic_format_context</* unspecified */, wchar_t>; // (3) (since C++20)
```

Provides access to formatting state consisting of the formatting arguments and the output iterator.

2) The unspecified template argument is an output iterator that appends to `std::string`, such as `std::back_insert_iterator<std::string>`. Implementations typically use an iterator to type-erased buffer type that supports appending to any contiguous and resizable container.

3) The unspecified template argument is an output iterator that appends to `std::wstring`.

The behavior is undefined if `OutputIt` does not model `std::output_iterator<const CharT&>`.

A program that declares an explicit or partial specialization of `std::basic_format_context` is ill-formed, no diagnostic required.

`std::basic_format_context` objects can only be created by the implementation. User codes are only allowed to modify the format context via the `format` function of `std::formatter` specializations.

#### Member types

**Type — Definition**

- `iterator`: `OutputIt`
- `char_type`: `CharT`

#### Member alias templates

**Type — Definition**

- `formatter_type<T>`: `std::formatter<T, CharT>`

#### Member functions

- (constructor) [deleted]: `basic_format_context` cannot be constructed by user code (public member function)
- `operator=` [deleted]: `basic_format_context` is not assignable (public member function)
- `arg`: returns the argument at the given index (public member function)
- `locale`: returns the locale used for locale-specific formatting (public member function)
- `out`: returns the iterator to output buffer (public member function)
- `advance_to`: advances the output iterator to the given position (public member function)

### std::basic_format_context::arg

```cpp
std::basic_format_arg<basic_format_context> arg( std::size_t id ) const;
```

Returns a `std::basic_format_arg` holding the `id`-th argument in `args`, where `args` is the parameter pack or `std::basic_format_args` object passed to the formatting function.

If `id` is not less than the number of formatting arguments, returns a default-constructed `std::basic_format_arg` (holding a `std::monostate` object).

### std::basic_format_context::locale

```cpp
std::locale locale();
```

Returns the locale passed to the formatting function, or a default-constructed `std::locale` if the formatting function does not take a locale.

### std::basic_format_context::out

```cpp
iterator out();
```

Returns the iterator to the output buffer. The result is move-constructed from the stored iterator.

### std::basic_format_context::advance_to

```cpp
void advance_to( iterator it );
```

Move assigns `it` to the stored output iterator. After a call to `advance_to`, the next call to `out()` will return an iterator with the value that `it` had before the assignment.

#### Example

> Note: This section is incomplete Reason: no example

#### 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 3567 | C++20 | `basic_format_context` does not work move-only iterator types | made to move iterators |
| LWG 3975 | C++20 | user specialization of `basic_format_context` was allowed | disallowed |
| LWG 4061 | C++20 | `basic_format_context` was constructible and assignable by user code | made neither constructible nor assignable |

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