std::format_to

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.

Equivalent to:

1) return std::vformat_to (std::move(out), fmt.str, std::make_format_args (args...));

2) return std::vformat_to (std::move(out), fmt.str, std::make_wformat_args (args...));

3) return std::vformat_to (std::move(out), loc, fmt.str, std::make_format_args (args...));

4) 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&>.

If any of the following conditions is satisfied, the behavior is undefined:

OutputIt does not model std::output_iterator <const CharT&>.
std::formatter <Ti, CharT> does not meet the BasicFormatter requirements (as required by std::make_format_args and std::make_wformat_args ) for some Ti in Args.

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 thread id format specification and stacktrace entry format specification.
For std::basic_stacktrace, no format specifier is allowed.

(since C++23)

For std::filesystem::path, see path format specification.

(since C++26)

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

[edit] Return value

Iterator past the end of the output range.

[edit] Exceptions

Propagates any exception thrown by formatter or iterator operations.

[edit] Notes

It is an error if the format string is not a constant expression unless it is initialized from the result of std::runtime_format (since C++26). std::vformat_to does not have this requirement.

[edit] Example

Run this code

#include <format>
#include <iostream>
#include <iterator>
#include <string>
 
int main()
{
 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::flush ;
 
 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()!

[edit] 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 3539	C++20	out could not be a move-only iterator	it can be
P2216R3	C++20	throws std::format_error for invalid format string	results in compile-time error instead
P2418R2	C++20	objects that are neither const-usable nor copyable (such as generator-like objects) are not formattable	allow formatting these objects
P2508R1	C++20	there's no user-visible name for this facility	the name `basic_format_string` is exposed

[edit] See also

format

(C++20)

stores formatted representation of the arguments in a new string
(function template) [edit]

format_to_n

(C++20)

writes out formatted representation of its arguments through an output iterator, not exceeding specified size
(function template) [edit]

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility/format/format_to&oldid=183336"

cppreference.com

Namespaces

Variants

Views

Actions

std::format_to

Contents

[edit] Parameters