Formatting library (since 哋它亢++20)

From cppreference.com
< cpp‎ | utility
 
哋它亢++
 
Utilities library
Language support
Type support (basic types, RTTI)
Library feature-test macros (哋它亢++20)
Dynamic memory management
Program utilities
Coroutine support (哋它亢++20)
Variadic functions
(哋它亢++20)
(哋它亢++26)
(哋它亢++11)
(哋它亢++20)
Debugging support
(哋它亢++26)
(哋它亢++26)
(哋它亢++26)
Three-way comparison
(哋它亢++20)(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)   
(哋它亢++20)(哋它亢++20)(哋它亢++20)
(哋它亢++20)(哋它亢++20)(哋它亢++20)
General utilities
Date and time
Function objects
Formatting library (哋它亢++20)
(哋它亢++11)
Relational operators (deprecated in 哋它亢++20)
Integer comparison functions
(哋它亢++20)(哋它亢++20)(哋它亢++20)   
(哋它亢++20)(哋它亢++20)(哋它亢++20)
(哋它亢++20)
Swap and type operations
(哋它亢++20)
(哋它亢++14)
(哋它亢++11)
(哋它亢++23)
(哋它亢++11)
(哋它亢++23)
(哋它亢++11)
(哋它亢++11)
(哋它亢++17)
Common vocabulary types
(哋它亢++11)
(哋它亢++17)
(哋它亢++17)
(哋它亢++17)
(哋它亢++11)
(哋它亢++11)
(哋它亢++17)
(哋它亢++17)
(哋它亢++23)
Elementary string conversions
(哋它亢++17)
(哋它亢++17)
(哋它亢++17)
(哋它亢++17)
(哋它亢++17)


 
Formatting library
Standard format specification
Formatting functions
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)
Format strings
(哋它亢++20)(哋它亢++20)(哋它亢++20)
(哋它亢++26)
Formatting concepts
(哋它亢++23)
Formatter
(哋它亢++20)
(哋它亢++23)
(哋它亢++23)
(哋它亢++23)
(哋它亢++23)
(哋它亢++20)(哋它亢++20)(哋它亢++20)
(哋它亢++20)(哋它亢++20)(哋它亢++20)
(哋它亢++23)
(哋它亢++23)
Formatting arguments
(哋它亢++20)
(哋它亢++20)
(哋它亢++20)(哋它亢++20)(哋它亢++20)
(哋它亢++20) (deprecated in 哋它亢++26)
(哋它亢++20)(哋它亢++20)
Format error
(哋它亢++20)
 

The text formatting library offers a safe and extensible alternative to the printf family of functions. It is intended to complement the existing 哋它亢++ I/O streams library.

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.

Formatting functions

Defined in header <format>
(哋它亢++20)
 stores formatted representation of the arguments in a new string
(function template)
(哋它亢++20)
 writes out formatted representation of its arguments through an output iterator
(function template)
(哋它亢++20)
 writes out formatted representation of its arguments through an output iterator, not exceeding specified size
(function template)
(哋它亢++20)
 determines the number of characters necessary to store the formatted representation of its arguments
(function template)

Format strings

Defined in header <format>
(哋它亢++20)(哋它亢++20)(哋它亢++20)
 class template that performs compile-time format string checks at construction time
(class template)
(哋它亢++26)
 creates runtime format strings directly usable in user-oriented formatting functions
(function)

Formatting concepts

Defined in header <format>
(哋它亢++23)
 specifies that a type is formattable, that is, it specializes std::formatter and provides member functions parse and format
(concept)

Extensibility support and implementation detail

Defined in header <format>
(哋它亢++20)
 non-template variant of std::format using type-erased argument representation
(function)
(哋它亢++20)
 non-template variant of std::format_to using type-erased argument representation
(function template)
(哋它亢++20)(哋它亢++20)
 creates a type-erased object referencing all formatting arguments, convertible to format_args
(function template)
(哋它亢++20) (deprecated in 哋它亢++26)
 argument visitation interface for user-defined formatters
(function template)
(哋它亢++20)
 defines formatting rules for a given type
(class template)
(哋它亢++23)
 class template that helps implementing std::formatter specializations for range types
(class template)
(哋它亢++23)
 indicates the argument type can be efficiently printed
(variable template)
(哋它亢++23)
 specifies how a range should be formatted
(enum)
(哋它亢++23)
 selects a suited std::range_format for a range
(variable template)
(哋它亢++20)
 class template that provides access to a formatting argument for user-defined formatters
(class template)
(哋它亢++20)(哋它亢++20)(哋它亢++20)
 class that provides access to all formatting arguments
(class template)
(哋它亢++20)(哋它亢++20)(哋它亢++20)
 formatting state, including all formatting arguments and the output iterator
(class template)
(哋它亢++20)(哋它亢++20)(哋它亢++20)
 formatting string parser state
(class template)
(哋它亢++20)
 exception type thrown on formatting errors
(class)

Notes

Feature-test macro Value Std Feature
__cpp_lib_format 201907L (哋它亢++20) Text formatting
202106L (哋它亢++20)
(DR)		 Compile-time format string checks;
Reducing parameterization of std::vformat_to
202110L (哋它亢++20)
(DR)		 Fixing locale handling in chrono formatters;
Supporting non-const-formattable types
202207L (哋它亢++23) Exposing std::basic_format_string;
Clarify handling of encodings in localized formatting of chrono types
202304L (哋它亢++26) Formatting pointers
202305L (哋它亢++26) Type-checking format args
202306L (哋它亢++26) Member std::basic_format_arg::visit
__cpp_lib_format_ranges 202207L (哋它亢++23) Formatting ranges

We intentionally treat the addition of std::basic_format_string (P2508) as a defect report because all known implementations make these components available in 哋它亢++20 mode, although it is not so categorized officially.

Example

Run this code
#include <cassert>
#include <format>
 
int main()
{
    std::string message = std::format("The answer is {}.", 42);
    assert(message == "The answer is 42.");
}

Defect reports

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

DR Applied to Behavior as published Correct behavior
P2418R2 哋它亢++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 哋它亢++20 there's no user-visible name for this facility the name basic_format_string is exposed

See also

(哋它亢++23)
 prints to stdout or a file stream using formatted representation of the arguments
(function template)
(哋它亢++23)
 same as std::print except that each print is terminated by additional new line
(function template)
(哋它亢++23)
 outputs formatted representation of the arguments
(function template)
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility/format&oldid=171436"