std::format_to_n, std::format_to_n_result - cppreference.com (original) (raw)

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.

1. std::format_to_n_result has no base classes, or members other than out, size and implicitly declared special member functions.

Contents

• 1 Parameters
• 2 Return value
• 3 Exceptions
• 4 Notes
• 5 Example
• 6 Defect reports
• 7 See also

[edit] Parameters

[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 #include #include #include #include   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, '₀' (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 H₀ ≅ 71±8 km/sec/Mpc." Max chars to write: 63 result.out offset: 35 Untruncated output size: 35   Buffer until '\0': "Hubble's H₀ ≅ 71±8" Max chars to write: 23 result.out offset: 23 Untruncated output size: 35   Buffer until '\0': "Hubble's H₀ ≅ 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.

[edit] See also

| | stores formatted representation of the arguments in a new string (function template) [edit] | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | writes out formatted representation of its arguments through an output iterator (function template) [edit] | | | determines the number of characters necessary to store the formatted representation of its arguments (function template) [edit] |