Formatting library (since C++20) - cppreference.com (original) (raw)
The text formatting library offers a safe and extensible alternative to the printf family of functions. It is intended to complement the existing C++ I/O streams library.
Contents
- 1 Format specifications
- 2 Formatting functions
- 3 Format strings
- 4 Formatting concepts
- 5 Extensibility support and implementation detail
- 6 Helper items (since C++23)
- 7 Notes
- 8 Example
- 9 Defect reports
- 10 See also
[edit] Format specifications
Format specification specifies how objects are formatted with different kinds of options.
The formatting of objects of basic types and standard string types uses the basic format specification. Other library components may also provide their own format specifications, see here for details.
[edit] Formatting functions
[edit] Format strings
[edit] Formatting concepts
[edit] Extensibility support and implementation detail
| Defined in header | |
|---|---|
| vformat(C++20) | non-template variant of std::format using type-erased argument representation (function) [edit] |
| vformat_to(C++20) | non-template variant of std::format_to using type-erased argument representation (function template) [edit] |
| make_format_argsmake_wformat_args(C++20)(C++20) | creates a type-erased object referencing all formatting arguments, convertible to format_args (function template) [edit] |
| visit_format_arg(C++20) (deprecated in C++26) | argument visitation interface for user-defined formatters (function template) [edit] |
| formatter(C++20) | defines formatting rules for a given type (class template) [edit] |
| range_formatter(C++23) | class template that helps implementing std::formatter specializations for range types (class template) [edit] |
| enable_nonlocking_formatter_optimization(C++23) | indicates the argument type can be efficiently printed(variable template)[edit] |
| range_format(C++23) | specifies how a range should be formatted (enum) [edit] |
| format_kind(C++23) | selects a suited std::range_format for a range(variable template)[edit] |
| basic_format_arg(C++20) | class template that provides access to a formatting argument for user-defined formatters (class template) [edit] |
| basic_format_argsformat_argswformat_args(C++20)(C++20)(C++20) | class that provides access to all formatting arguments (class template) [edit] |
| basic_format_contextformat_contextwformat_context(C++20)(C++20)(C++20) | formatting state, including all formatting arguments and the output iterator (class template) [edit] |
| basic_format_parse_contextformat_parse_contextwformat_parse_context(C++20)(C++20)(C++20) | formatting string parser state (class template) [edit] |
| format_error(C++20) | exception type thrown on formatting errors (class) [edit] |
[edit] Helper items (since C++23)
[edit] Notes
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
| __cpp_lib_format | 201907L | (C++20) | Text formatting |
| 202106L | (C++23)(DR20) | Compile-time format string checks;Reducing parameterization of std::vformat_to | |
| 202110L | (C++23)(DR20) | Fixing locale handling in chrono formatters;Supporting non-const-formattable types | |
| 202207L | (C++23)(DR20) | Exposing std::basic_format_string;Clarify handling of encodings in localized formatting of chrono types | |
| 202304L | (C++26) | Formatting pointers | |
| 202305L | (C++26) | Type-checking format args | |
| 202306L | (C++26) | Member std::basic_format_arg::visit | |
| 202311L | (C++26) | Runtime format string | |
| 202403L | (C++26) | Printing Blank Lines with std::println | |
| 202403L | (C++26)(DR23) | Permit an efficient implementation of std::print This section is incompleteReason: the value should be >= 202406L, i.e. be different from the previous one | |
| __cpp_lib_format_ranges | 202207L | (C++23) | Formatting ranges |
| __cpp_lib_format_path | 202403L | (C++26) | Formatting of std::filesystem::path |
| __cpp_lib_format_uchar | 202311L | (C++26) | Fix formatting of code units as integers |
| __cpp_lib_formatters | 202302L | (C++23) | Formatting std::thread::id and std::stacktrace |
We intentionally treat the addition of std::basic_format_string (P2508) as a defect report because all known implementations make these components available in C++20 mode, although it is not so categorized officially.
[edit] Example
#include #include int main() { std::string message = std::format("The answer is {}.", 42); assert(message == "The answer is 42."); }
[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 |
|---|---|---|---|
| P2418R2 | C++20 | objects that are neither const-formattable nor copyable(such as generator-like objects) are not formattable | allow formatting these objects(relaxed formatter requirements) |
| P2508R1 | C++20 | there's no user-visible name for this facility | the name basic_format_string is exposed |
[edit] See also
| | prints to stdout or a file stream using formatted representation of the arguments (function template) [edit] | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | same as std::print except that each print is terminated by additional new line (function template) [edit] | | | outputs formatted representation of the arguments (function template) [edit] |