std::format_to_n, std::format_to_n_result
<format>
std::format_to_n_result<OutputIt>
format_to_n( OutputIt out, std::iter_difference_t <OutputIt> n,
std::format_to_n_result<OutputIt>
format_to_n( OutputIt out, std::iter_difference_t <OutputIt> n,
std::format_to_n_result<OutputIt>
format_to_n( OutputIt out, std::iter_difference_t <OutputIt> n,
const std::locale & loc,
std::format_to_n_result<OutputIt>
format_to_n( OutputIt out, std::iter_difference_t <OutputIt> n,
const std::locale & loc,
struct format_to_n_result {
OutputIt out;
std::iter_difference_t <OutputIt> size;
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.[edit] Parameters
- 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:
{
arg-id (optional) }
(1)
{
arg-id (optional) :
format-spec }
(2)
args
whose value is to be used for formatting; if it is omitted, the arguments are used in order.
The arg-id s in a format string must all be present or all be omitted. Mixing manual and automatic indexing is an error.
- 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 range types, the format specification is interpreted as range format specification.
- For std::pair and std::tuple , the format specification is interpreted as tuple format specification.
- For std::thread::id and std::stacktrace_entry, see thread id format specification and stacktrace entry format specification.
- For std::basic_stacktrace, no format specifier is allowed.
- For other formattable types, the format specification is determined by user-defined
formatter
specializations.
[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] Notes
The libstdc++ implementation prior to GCC-13.3 had a bug in reporting the correct format_to_n_result::out value.
[edit] Example
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 formatters 71, // {0}, occupies 2 bytes 8, // {1}, occupies 1 byte "\u2080", // {2}, occupies 3 bytes, '0' (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 const std::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 H0 ≅ 71±8 km/sec/Mpc." Max chars to write: 63 result.out offset: 35 Untruncated output size: 35 Buffer until '0円': "Hubble's H0 ≅ 71±8" Max chars to write: 23 result.out offset: 23 Untruncated output size: 35 Buffer until '0円': "Hubble's H0 ≅ 71�" Max chars to write: 21 result.out offset: 21 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
(function template) [edit]
(function template) [edit]