Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/utility/format/format to n"

From cppreference.com
< cpp‎ | utility‎ | format
(Created page with "{{cpp/title|format_to_n}} {{cpp/utility/format/navbar}} {{dcl begin}} {{dcl header | format }} {{dcl | num=1 | since=c++20 |1= template<class OutputIt, class... Args> std::fo...")
 
m (→‎Notes: I mention the bug-110990 because people report it from time to time.)
 
(31 intermediate revisions by 14 users not shown)
Line 1: Line 1:
−
{{cpp/title|format_to_n}}
+
{{cpp/title|format_to_n|format_to_n_result}}
 
{{cpp/utility/format/navbar}}
 
{{cpp/utility/format/navbar}}
−
 
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl header | format }}
+
{{dcl header|format}}
−
{{dcl | num=1 | since=c++20 |1=
+
{{dcl|num=1|since=c++20|1=
−
template<class OutputIt, class... Args>
+
template< class OutputIt, class... Args >
 
std::format_to_n_result<OutputIt>
 
std::format_to_n_result<OutputIt>
−
     format_to_n(OutputIt out, std::iter_difference_t<OutputIt> n,
+
     format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,
−
                std::string_view fmt, const Args&... args);
+
                std::format_string<Args...> fmt, Args&&... args );
 
}}
 
}}
−
{{dcl | num=2 | since=c++20 |1=
+
{{dcl|num=2|since=c++20|1=
−
template<class OutputIt, class... Args>
+
template< class OutputIt, class... Args >
 
std::format_to_n_result<OutputIt>
 
std::format_to_n_result<OutputIt>
−
     format_to_n(OutputIt out, std::iter_difference_t<OutputIt> n,
+
     format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,
−
                std::wstring_view fmt, const Args&... args);
+
                std::wformat_string<Args...> fmt, Args&&... args );
 
}}
 
}}
−
{{dcl | num=3 | since=c++20 |1=
+
{{dcl|num=3|since=c++20|1=
−
template<class OutputIt, class... Args>
+
template< class OutputIt, class... Args >
 
std::format_to_n_result<OutputIt>
 
std::format_to_n_result<OutputIt>
−
     format_to_n(OutputIt out, std::iter_difference_t<OutputIt> n,
+
     format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,
−
                const std::locale& loc, std::string_view fmt, const Args&... args);
+
                const std::locale& loc,
 +
                std::format_string<Args...> fmt, Args&&... args );
 
}}
 
}}
−
{{dcl | num=4 | since=c++20 |1=
+
{{dcl|num=4|since=c++20|1=
−
template<class OutputIt, class... Args>
+
template< class OutputIt, class... Args >
 
std::format_to_n_result<OutputIt>
 
std::format_to_n_result<OutputIt>
−
     format_to_n(OutputIt out, std::iter_difference_t<OutputIt> n,
+
     format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,
−
                const std::locale& loc, std::wstring_view fmt, const Args&... args);
+
                const std::locale& loc,
 +
                std::wformat_string<Args...> fmt, Args&&... args );
 
}}
 
}}
−
{{dcl | num=5 | since=c++20 |1=
+
{{dcl h|Helper types}}
−
template<class OutputIt>
+
{{dcl|num=5|since=c++20|1=
 +
template< class OutputIt >
 
struct format_to_n_result {
 
struct format_to_n_result {
 
     OutputIt out;
 
     OutputIt out;
Line 37: Line 39:
 
{{dcl end}}
 
{{dcl end}}
  
−
Format {{tt|args}} according to the format string {{tt|fmt}}, and write the result to the output iterator {{tt|out}}. At most {{tt|n}} characters are written. If present, {{tt|loc}} is used for locale-specific formatting.
+
Format {{c|args}} according to the format string {{c|fmt}}, and write the result to the output iterator {{c|out}}. At most {{c|n}} characters are written. If present, {{c|loc}} is used for locale-specific formatting.
  
−
Let {{tt|CharT}} be {{c|decltype(fmt)::char_type}} ({{tt|char}} for overloads {{v|1,3}}, {{tt|wchar_t}} for overloads {{v|2,4}}).
+
Let {{tt|CharT}} be {{c/core|char}} for overloads {{v|1,3}}, {{co|wchar_t}} for overloads {{v|2,4}}.
  
 
{{cpp/enable if|plural=true|
 
{{cpp/enable if|plural=true|
−
{{tt|OutputIt}} satisfies the concept {{tt|std::output_iterator<const CharT&>}}.
+
{{tt|OutputIt}} satisfies the concept {{c|std::output_iterator<const CharT&>}}.
 
}}
 
}}
−
The behavior is undefined if {{tt|OutputIt}} does not model (meet the semantic requirements of) the the concept {{tt|std::output_iterator<const CharT&>}}, or if {{c|std::formatter<Ti, CharT>}} does not meet the {{named req|Formatter}} requirements for each {{tt|Ti}} in {{tt|Args}}.  
+
The behavior is undefined if {{tt|OutputIt}} does not model (meet the semantic requirements of) the concept {{c|std::output_iterator<const CharT&>}}, or if {{c|std::formatter<std::remove_cvref_t<Ti>, CharT>}} does not meet the {{named req|BasicFormatter}} requirements for any {{tt|Ti}} in {{tt|Args}}.
 +
 
 +
@5@ {{tt|std::format_to_n_result}} has no base classes, or members other than {{c|out}}, {{tt|size}} and implicitly declared special member functions.
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | out | iterator to the output buffer}}
+
{{par|out|iterator to the output buffer}}
−
{{par | n | maximum number of characters to be written to the buffer}}
+
{{par|n|maximum number of characters to be written to the buffer}}
−
{{par | fmt | string view representing the format string.
+
{{par|fmt|{{include|cpp/utility/format/format string|const}}}}
−
{{cpp/utility/format/format string}}
+
{{par|args...|arguments to be formatted}}
−
}}
+
{{par|loc|{{lc|std::locale}} used for locale-specific formatting}}
−
{{par | args... | arguments to be formatted}}
+
−
{{par | loc | {{lc|std::locale}} used for locale-specific formatting}}
+
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
A {{tt|format_to_n_result}} such that the {{tt|out}} member is an iterator past the end of the output range, and the {{tt|size}} member is the total (not truncated) output size.
+
A {{tt|format_to_n_result}} such that the {{c|out}} member is an iterator past the end of the output range, and the {{tt|size}} member is the total (not truncated) output size.
  
 
===Exceptions===
 
===Exceptions===
−
Throws {{lc|std::format_error}} if {{tt|fmt}} is not a valid format string. Also propagates exception thrown by any formatter.
+
Propagates any exception thrown by formatter or iterator operations.
  
−
{{todo|the second sentence is not backed by the draft standard}}
+
===Notes===
 +
The libstdc++ implementation prior to GCC-13.3 had a [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=110990 bug] in reporting the correct {{c|format_to_n_result::out}} value.
  
 
===Example===
 
===Example===
 
{{example
 
{{example
−
|code=
+
|At Godbolt's Compiler Explorer: [https://godbolt.org/z/s7a5d76ET clang (trunk) + libc++], [https://godbolt.org/z/bdvxnPb1T GCC (trunk) + libstdc++].
−
  |output=
+
|code=
 +
#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, '₀' (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
 
}}
 
}}
 +
 +
===Defect reports===
 +
{{dr list begin}}
 +
{{dr list item|paper=P2216R3|std=C++20|before=throws {{lc|std::format_error}} for invalid format string|after=invalid format string results in compile-time error}}
 +
{{dr list item|paper=P2418R2|std=C++20|before=objects that are neither const-usable nor copyable<br>(such as generator-like objects) are not formattable|after=allow formatting these objects}}
 +
{{dr_p2508}}
 +
{{dr list end}}
  
 
===See also===
 
===See also===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/utility/format/dsc format}}
 +
{{dsc inc|cpp/utility/format/dsc format_to}}
 +
{{dsc inc|cpp/utility/format/dsc formatted_size}}
 +
{{dsc end}}
 +
 +
{{langlinks|es|ja|ru|zh}}

Latest revision as of 12:37, 9 July 2024

 
C++
 
Utilities library
General utilities
Relational operators (deprecated in C++20)
 
Formatting library
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++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>
    format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,

                 std::format_string<Args...> fmt, Args&&... args );
 (1) (since C++20)
template< class OutputIt, class... Args >

std::format_to_n_result<OutputIt>
    format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,

                 std::wformat_string<Args...> fmt, Args&&... args );
 (2) (since C++20)
template< class OutputIt, class... Args >

std::format_to_n_result<OutputIt>
    format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,
                 const std::locale& loc,

                 std::format_string<Args...> fmt, Args&&... args );
 (3) (since C++20)
template< class OutputIt, class... Args >

std::format_to_n_result<OutputIt>
    format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n,
                 const std::locale& loc,

                 std::wformat_string<Args...> fmt, Args&&... args );
 (4) (since C++20)
Helper types
template< class OutputIt >

struct format_to_n_result {
    OutputIt out;
    std::iter_difference_t<OutputIt> size;

};
 (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.

5) 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 -
[edit]
an object that represents the format string. The format string consists of
  • 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)
1) replacement field without a format specification
2) replacement field with a format specification
arg-id - specifies the index of the argument in 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.

format-spec - the format specification defined by the std::formatter specialization for the corresponding argument. Cannot start with }.

(since C++23)
(since C++26)
  • For other formattable types, the format specification is determined by user-defined formatter specializations.
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] 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++.

Run this code
#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, '₀' (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.

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) [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]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility/format/format_to_n&oldid=173440"