std::format_to
Defined in header <format> |
||
---|---|---|
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, /*format_string<Args...>*/ fmt, Args&&... args ); |
(1) | (since C++20) |
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, /*wformat_string<Args...>*/ fmt, Args&&... args ); |
(2) | (since C++20) |
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, const std::locale& loc, /*format_string<Args...>*/ fmt, Args&&... args ); |
(3) | (since C++20) |
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, const std::locale& loc, /*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.
return std::vformat_to(out, fmt.str, std::make_format_args(args...));
return std::vformat_to(std::move(out), fmt.str, std::make_wformat_args(args...));
return std::vformat_to(out, loc, fmt.str, std::make_format_args(args...));
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
).
Parameters
out | - | iterator to the output buffer | ||||||||||||
fmt | - | parameter of unspecified type, whose initialization is valid only if the argument is convertible to std::string_view (for (1,3)) or std::wstring_view (for (2,4)), and the result of conversion is a constant expression and a valid format string for Args . The format string consists of
Each replacement field has the following format:
|
||||||||||||
args... | - | arguments to be formatted | ||||||||||||
loc | - | std::locale used for locale-specific formatting |
Return value
Iterator past the end of the output range.
Exceptions
Propagates any exception thrown by formatter or iterator operations.
Notes
As of P2216R3, it is an error if the format string is not a constant expression. std::vformat_to
can be used in this case.
Example
#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.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
P2216R3 | C++20 | throws std::format_error for invalid format string |
invalid format string results in compile-time error |
P2418R2 | C++20 | objects that are neither const-usable nor copyable (such as generator-like objects) are not formattable |
allow formatting these objects |
See also
(C++20)
|
stores formatted representation of the arguments in a new string (function template) |
(C++20)
|
writes out formatted representation of its arguments through an output iterator, not exceeding specified size (function template) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/utility/format/format_to