std::format_to(3)

💖 NAME 💖

std::format_to — literally std::format_to. This is the std::format_to(3) manual page from the C++ Standard Libary (yes bestie, that's the header's spelling, we're keeping it 💅). It's giving "format your args and write the glow-up straight into an output iterator" energy. Obsessed. ✨

---

✨ Synopsis ✨

Defined in header <format>

template< class OutputIt, class... Args >
OutputIt format_to( OutputIt out, std::format_string<Args...> fmt, Args&&... args );

(1) (since C++20)

template< class OutputIt, class... Args >
OutputIt format_to( OutputIt out, std::wformat_string<Args...> fmt, Args&&... args );

(2) (since C++20)

template< class OutputIt, class... Args >
OutputIt format_to( OutputIt out, const std::locale& loc, std::format_string<Args...> fmt, Args&&... args );

(3) (since C++20)

template< class OutputIt, class... Args >
OutputIt format_to( OutputIt out, const std::locale& loc, std::wformat_string<Args...> fmt, Args&&... args );

(4) (since C++20)

Format args according to the format string fmt, and write the result to the output iterator out. If present, loc is used for locale-specific formatting. Fr fr, that's the whole vibe. 🫶

1. equivalent to return std::vformat_to(out, fmt.str, std::make_format_args(args...));
2. equivalent to return std::vformat_to(std::move(out), fmt.str, std::make_wformat_args(args...));
3. equivalent to return std::vformat_to(out, loc, fmt.str, std::make_format_args(args...));
4. equivalent to return std::vformat_to(std::move(out), loc, fmt.str, std::make_wformat_args(args...));

Let CharT be char for overloads (1,3), wchar_t for overloads (2,4).

These overloads participate in overload resolution only if OutputIt satisfies the concept std::output_iterator<const CharT&>.

The behavior is undefined if OutputIt does not model (meet the semantic requirements of) the concept std::output_iterator<const CharT&>, or if std::formatter<Ti, CharT> does not meet the BasicFormatter requirements for any Ti in Args (as required by std::make_format_args and std::make_wformat_args). Not me warning you about undefined behavior — okay, it is me, and it's important. 😭

---

🌸 Parameters 🌸

• out — iterator to the output buffer, aka where the formatted result gets written. 💖
• fmt — an object that represents the format string. The format string consists of:
  • ordinary characters (except { and }), which are copied unchanged to the output,
  • escape sequences {{ and }}, which are replaced with { and } respectively in the output, and
  • replacement fields.

Each replacement field has the following format:

{ arg-id (optional) }               (1)
{ arg-id (optional) : format-spec } (2)

1. replacement field without a format specification
2. replacement field with a format specification

• arg-id — specifies the index of the argument in args whose value is to be used for formatting; if it is omitted, the arguments are used in order. The arg-ids in a format string must all be present or all be omitted. Mixing manual and automatic indexing is an error. Periodt. 🚨
• format-spec — the format specification defined by the std::formatter specialization for the corresponding argument. Cannot start with }.
  • For basic types and standard string types, the format specification is interpreted as standard format specification.
  • For chrono types, the format specification is interpreted as chrono format specification.
  • For range types, the format specification is interpreted as range format specification.
  • For std::pair and std::tuple, the format specification is interpreted as tuple format specification.
  • For std::thread::id and std::stacktrace_entry, see (since C++23) thread id format specification and stacktrace entry format specification.
  • For std::basic_stacktrace, no format specifier is allowed.
  • For std::filesystem::path, see path format (since C++26) specification.
  • For other formattable types, the format specification is determined by user-defined formatter specializations.
• args... — arguments to be formatted.
• loc — std::locale used for locale-specific formatting.

---

🦋 Return value 🦋

Iterator past the end of the output range. That's it, that's the return value bestie. 💅

---

🌈 Exceptions 🌈

Propagates any exception thrown by formatter or iterator operations. No cap, if the formatter or iterator throws, it's coming through. 💀

---

🎀 Notes 🎀

As of P2216R3, it is an error if the format string is not a constant expression. std::vformat_to or std::runtime_format (since C++26) can be used in this case.

Highkey clock this: the format string has to be a constant expression now, unless you reach for std::vformat_to or std::runtime_format (since C++26). That's the whole note, iykyk. 🔥

---

🍓 Example 🍓

// Run this code

#include <format>
#include <iostream>
#include <iterator>
#include <string>

auto main() -> int
{
    std::string buffer;

    std::format_to(
        std::back_inserter(buffer), //< OutputIt
        "Hello, C++{}!\n",          //< fmt
        "20");                      //< arg
    std::cout << buffer;
    buffer.clear();

    std::format_to(
        std::back_inserter(buffer), //< OutputIt
        "Hello, {0}::{1}!{2}",      //< fmt
        "std",                      //< arg {0}
        "format_to()",              //< arg {1}
        "\n",                       //< arg {2}
        "extra param(s)...");       //< unused
    std::cout << buffer;

    std::wstring wbuffer;
    std::format_to(
        std::back_inserter(wbuffer),//< OutputIt
        L"Hello, {2}::{1}!{0}",     //< fmt
        L"\n",                      //< arg {0}
        L"format_to()",             //< arg {1}
        L"std",                     //< arg {2}
        L"...is not..."             //< unused
        L"...an error!");           //< unused
    std::wcout << wbuffer;
}

---

🌟 Output 🌟

Hello, C++20!
Hello, std::format_to()!
Hello, std::format_to()!

---

👑 Defect reports 👑

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

• P2216R3 — applied to C++20. Behavior as published: throws std::format_error for invalid format string. Correct behavior: invalid format string results in compile-time error.
• P2418R2 — applied to C++20. Behavior as published: objects that are neither const-usable nor copyable (such as generator-like objects) are not formattable. Correct behavior: allow formatting these objects.
• P2508R1 — applied to C++20. Behavior as published: there's no user-visible name for this facility. Correct behavior: the name basic_format_string is exposed.

---

🧚 See also 🧚

• format (C++20) — stores formatted representation of the arguments in a new string (function template).
• format_to_n (C++20) — writes out formatted representation of its arguments through an output iterator, not exceeding specified size (function template).

---

xoxo, your C++ bestie 💖 — source/version: http://cppreference.com, 2024.06.10, and the manual name is std::format_to(3). Slay this format string, periodt. 🎀