std::format

• 1 Parameters
• 2 Return value
• 3 Exceptions
• 4 Notes
• 5 Example
• 6 Defect reports
• 7 See also

• 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:

• 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 other formattable types, the format specification is determined by user-defined formatter specializations.

[edit] Return value

A string object holding the formatted result.

[edit] Exceptions

Throws std::bad_alloc on allocation failure. Also propagates exception thrown by any formatter.

[edit] Notes

It is not an error to provide more arguments than the format string requires:

std::format("{} {}!", "Hello", "world", "something"); // OK, produces "Hello world!"

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 does not have this requirement.

std::string f1(std::string_view runtime_format_string)
{
 // return std::format(runtime_format_string, "x", 42); // error
 char v1[] = "x";
 int v2 = 42;
 return std::vformat (runtime_format_string, std::make_format_args (v1, v2)); // OK
}
 
std::string f2(std::string_view runtime_format_string)
{
 return std::format(std::runtime_format (runtime_format_string), "x", 42); // OK (C++26)
}

[edit] Example

#include <format>
#include <iostream>
#include <set>
#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()
{
#ifdef __cpp_lib_format_ranges
 const std::set <std::string_view > continents 
 {
 "Africa", "America", "Antarctica", 
 "Asia", "Australia", "Europe"
 };
 std::cout << std::format("Hello {}!\n", continents);
#else
 std::cout << std::format("Hello {}!\n", "continents");
#endif
 
 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';
 }
}

Hello {"Africa", "America", "Antarctica", "Asia", "Australia", "Europe"}!
{}  : alpha
{} {}  : alpha Z
{} {} {}  : alpha Z 3.14

[edit] Defect reports

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

[edit] See also