std::format_to_n, std::format_to_n_result
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) |
Format args
according to the format string fmt
, and write the result to the output iterator out
. At most n
characters are written. If present, loc
is used for locale-specific formatting.
Let CharT
be char for overloads (1,3), wchar_t for overloads (2,4).
These overloads participate in overload resolution only if
OutputIt
satisfies the concept std::output_iterator<const CharT&>.
The behavior is undefined if OutputIt
does not model (meet the semantic requirements of) the concept std::output_iterator<const CharT&>, or if std::formatter<std::remove_cvref_t<Ti>, CharT> does not meet the BasicFormatter requirements for any Ti
in Args
.
std::format_to_n_result
has no base classes, or members other than out
, size
and implicitly declared special member functions.Contents |
[edit] Parameters
out | - | iterator to the output buffer | ||||||||||||||||||||||||||||||||||||||||||
n | - | maximum number of characters to be written to the buffer | ||||||||||||||||||||||||||||||||||||||||||
fmt | - |
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 |
[edit] Return value
A format_to_n_result
such that the out
member is an iterator past the end of the output range, and the size
member is the total (not truncated) output size.
[edit] Exceptions
Propagates any exception thrown by formatter or iterator operations.
[edit] Example
#include <format> #include <iostream> #include <string_view> int main() { char buffer[64]; const auto result = std::format_to_n(buffer, std::size(buffer) - 1, "Hubble's H{2} {3} {0}{4}{1} km/sec/Mpc.", 71, // {0}, occupies 2 bytes 8, // {1}, occupies 1 byte "\u2080", // {2}, occupies 3 bytes "\u2245", // {3}, occupies 3 bytes "\u00B1" // {4}, occupies 2 bytes ); *result.out = '\0'; const std::string_view str{buffer, result.out}; // uses C++20 constructor std::cout << "Buffer: \"" << str << "\"\n" << "Buffer size = " << std::size(buffer) << '\n' << "Untruncated output size = " << result.size << '\n'; }
Output:
Buffer: "Hubble's H₀ ≅ 71±8 km/sec/Mpc." Buffer size = 64 Untruncated output size = 35
[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 |
---|---|---|---|
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
|
[edit] See also
(C++20) |
stores formatted representation of the arguments in a new string (function template) |
(C++20) |
writes out formatted representation of its arguments through an output iterator (function template) |
(C++20) |
determines the number of characters necessary to store the formatted representation of its arguments (function template) |