std::basic_format_context(3)

🎀 std::basic_format_context(3) 🎀

🌸 NAME 🌸

std::basic_format_context — std::basic_format_context

okay bestie, we're in the C++ Standard Libary manual, page std::basic_format_context(3). Buckle up, because this one is all about formatting state access. 💅

✨ Synopsis ✨

Defined in header <format>
template< class OutputIt, class CharT >
(1) (since C++20)
class basic_format_context;
using format_context = std::basic_format_context</* unspecified */,
(2) (since C++20)
char>;
using wformat_context = std::basic_format_context</* unspecified */,
(3) (since C++20)
wchar_t>;

okay so what is this vibe? It 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&>. Like, actually undefined — do not play with that. 😭

A program that declares an explicit or partial specialization of std::basic_format_context is ill-formed, no diagnostic required. So if you're thinking about specializing it: don't, bestie. 💀

🧬 Member types 🧬

• iterator — OutputIt
• char_type — CharT

🎀 Member alias templates 🎀

• formatter_type<T> — std::formatter<T, CharT>

🛠️ Member functions 🛠️

• 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

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). No index, no argument, no drama. 🙈

🌈 std::basic_format_context::locale

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. Locale-specific formatting said slay. 💅

🦋 std::basic_format_context::out

iterator out();

Returns the iterator to the output buffer. The result is move-constructed from the stored iterator. Subtle but important, iykyk. ✨

🔥 std::basic_format_context::advance_to

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. That's the whole plot twist. 👑

🧪 Example

This section is incomplete.

Reason: no example.

🩹 Defect reports

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

• LWG 3567, applied to C++20 — behavior as published: basic_format_context does not work move-only iterator types; correct behavior: made to move iterators.
• LWG 3975, applied to C++20 — behavior as published: user specialization of basic_format_context was allowed; correct behavior: disallowed.

🗂 Category

• Todo no example

---

shoutout to http://cppreference.com, 2024.06.10, and this page is literally std::basic_format_context(3). bye bestie, go format something iconic 💖