A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://en.cppreference.com/w/cpp/language/../algorithm/../utility/format/format_to_n.html below:

std::format_to_n, std::format_to_n_result - cppreference.com

(1) (since C++20) (2) (since C++20) (3) (since C++20) (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.

[edit] Parameters 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:

{ 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 }. 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++.

#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 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]

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4