| Localization library | |||||||||||||||||||||||||
| Regular expressions library(C++11) | |||||||||||||||||||||||||
| Formatting library(C++20) | |||||||||||||||||||||||||
| Null-terminated sequence utilities | |||||||||||||||||||||||||
| Byte strings | |||||||||||||||||||||||||
| Multibyte strings | |||||||||||||||||||||||||
| Wide strings | |||||||||||||||||||||||||
| Primitive numeric conversions | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| Text encoding identifications | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| Standard format specification | ||||
| Formatting functions | ||||
(C++20) | ||||
(C++20) | ||||
format_to_n (C++20) | ||||
(C++20) | ||||
(C++20) | ||||
(C++20) | ||||
| Format strings | ||||
(C++20)(C++20)(C++20) | ||||
(C++26) | ||||
| Formatting concepts | ||||
(C++23) | ||||
| Formatter | ||||
(C++20) | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
(C++20)(C++20)(C++20) | ||||
(C++20)(C++20)(C++20) | ||||
(C++23) | ||||
(C++23) | ||||
| Formatting arguments | ||||
(C++20) | ||||
(C++20) | ||||
(C++20)(C++20)(C++20) | ||||
(C++20)(deprecated in C++26) | ||||
(C++20)(C++20) | ||||
| Format error | ||||
(C++20) |
Defined in header <format> | ||
template<class OutputIt,class...Args> std::format_to_n_result<OutputIt> | (1) | (since C++20) |
template<class OutputIt,class...Args> std::format_to_n_result<OutputIt> | (2) | (since C++20) |
template<class OutputIt,class...Args> std::format_to_n_result<OutputIt> | (3) | (since C++20) |
template<class OutputIt,class...Args> std::format_to_n_result<OutputIt> | (4) | (since C++20) |
Helper types | ||
template<class OutputIt> struct format_to_n_result{ | (5) | (since C++20) |
Formatargs according to the format stringfmt, and write the result to the output iteratorout. At mostn characters are written. If present,loc is used for locale-specific formatting.
LetCharT bechar for overloads(1,3),wchar_t for overloads(2,4).
These overloads participate in overload resolution only ifOutputIt satisfies the conceptstd::output_iterator<const CharT&>.
The behavior is undefined ifOutputIt does not model (meet the semantic requirements of) the conceptstd::output_iterator<const CharT&>, or ifstd::formatter<std::remove_cvref_t<Ti>, CharT> does not meet theBasicFormatter requirements for anyTi inArgs.
std::format_to_n_result has no base classes, or members other thanout,size and implicitly declared special member functions.Contents |
| out | - | iterator to the output buffer | ||||||||||||||||||||||||||||||||||||||||||||||
| n | - | maximum number of characters to be written to the buffer | ||||||||||||||||||||||||||||||||||||||||||||||
| fmt | - | an object that represents the format string. The format string consists of
Each replacement field has the following format:
1) replacement field without a format specification 2) replacement field with a format specification
| ||||||||||||||||||||||||||||||||||||||||||||||
| args... | - | arguments to be formatted | ||||||||||||||||||||||||||||||||||||||||||||||
| loc | - | std::locale used for locale-specific formatting | ||||||||||||||||||||||||||||||||||||||||||||||
Aformat_to_n_result such that theout member is an iterator past the end of the output range, and thesize member is the total (not truncated) output size.
Propagates any exception thrown by formatter or iterator operations.
The libstdc++ implementation prior to GCC-13.3 had abug in reporting the correctformat_to_n_result::out value.
At Godbolt's Compiler Explorer:clang (trunk) + libc++,GCC (trunk) + libstdc++.
#include <format>#include <initializer_list>#include <iomanip>#include <iostream>#include <string_view> int main(){char buffer[64]; for(std::size_t max_chars_to_write:{std::size(buffer)-1, 23uz, 21uz}){const std::format_to_n_result result= std::format_to_n( buffer, max_chars_to_write,"Hubble's H{2} {3} {0}{4}{1} km/sec/Mpc.",// 24 bytes w/o formatters71,// {0}, occupies 2 bytes8,// {1}, occupies 1 byte"\u2080",// {2}, occupies 3 bytes, '₀' (SUBSCRIPT ZERO)"\u2245",// {3}, occupies 3 bytes, '≅' (APPROXIMATELY EQUAL TO)"\u00B1"// {4}, occupies 2 bytes, '±' (PLUS-MINUS SIGN));// 24 + 2 + 1 + 3 + 3 + 2 == 35, no trailing '\0' *result.out='\0';// adds terminator to buffer conststd::string_view str(buffer, result.out); std::cout<<"Buffer until '\\0': "<<std::quoted(str)<<'\n'<<"Max chars to write: "<< max_chars_to_write<<'\n'<<"result.out offset: "<< result.out- buffer<<'\n'<<"Untruncated output size: "<< result.size<<"\n\n";}}
Output:
Buffer until '\0': "Hubble's H₀ ≅ 71±8 km/sec/Mpc."Max chars to write: 63result.out offset: 35Untruncated output size: 35 Buffer until '\0': "Hubble's H₀ ≅ 71±8"Max chars to write: 23result.out offset: 23Untruncated output size: 35 Buffer until '\0': "Hubble's H₀ ≅ 71�"Max chars to write: 21result.out offset: 21Untruncated output size: 35
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 | throwsstd::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 namebasic_format_string is exposed |
(C++20) | stores formatted representation of the arguments in a new string (function template)[edit] |
(C++20) | writes out formatted representation of its arguments through an output iterator (function template)[edit] |
(C++20) | determines the number of characters necessary to store the formatted representation of its arguments (function template)[edit] |
