Defined in header <format> | ||
---|---|---|
template< class... Args > std::string format( std::format_string<Args...> fmt, Args&&... args ); | (1) | (since C++20) |
template< class... Args > std::wstring format( std::wformat_string<Args...> fmt, Args&&... args ); | (2) | (since C++20) |
template< class... Args > std::string format( const std::locale& loc, std::format_string<Args...> fmt, Args&&... args ); | (3) | (since C++20) |
template< class... Args > std::wstring format( const std::locale& loc, std::wformat_string<Args...> fmt, Args&&... args ); | (4) | (since C++20) |
Format args
according to the format string fmt
, and return the result as a string. If present, loc
is used for locale-specific formatting.
return std::vformat(fmt.get(), std::make_format_args(args...));
return std::vformat(fmt.get(), std::make_wformat_args(args...));
return std::vformat(loc, fmt.get(), std::make_format_args(args...));
return std::vformat(loc, fmt.get(), std::make_wformat_args(args...));
The behavior is undefined 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
), where CharT
is char
for overloads (1,3), wchar_t
for overloads (2,4).
fmt | - | an object that represents the format string. 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 |
A string object holding the formatted result.
Throws std::bad_alloc
on allocation failure. Also propagates exception thrown by any formatter.
It is not an error to provide more arguments than the format string requires:
std::format("{} {}!", "Hello", "world", "something"); // OK, produces "Hello world!"
As of P2216R3, it is an error if the format string is not a constant expression. std::vformat
can be used in this case.
std::string f(std::string_view runtime_format_string) { // return std::format(runtime_format_string, "foo", "bar"); // error return std::vformat(runtime_format_string, std::make_format_args("foo", "bar")); // ok }
#include <format> #include <iostream> #include <string> #include <string_view> template <typename... Args> std::string dyna_print(std::string_view rt_fmt_str, Args&&... args) { return std::vformat(rt_fmt_str, std::make_format_args(args...)); } int main() { std::cout << std::format("Hello {}!\n", "world"); std::string fmt; for (int i{}; i != 3; ++i) { fmt += "{} "; // constructs the formatting string std::cout << fmt << " : "; std::cout << dyna_print(fmt, "alpha", 'Z', 3.14, "unused"); std::cout << '\n'; } }
Output:
Hello world! {} : alpha {} {} : alpha Z {} {} {} : alpha Z 3.14
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 |
P2508R1 | C++20 | there's no user-visible name for this facility | the name basic_format_string is exposed |
(C++20) | writes out formatted representation of its arguments through an output iterator (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