std::format_to_n, std::format_to_n_result

Since C++20

Header: <format>

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.

# Declarations

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 );

(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 );

(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 );

(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 );

(since C++20)

Helper types

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

(since C++20)

# Parameters

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

# Notes

The libstdc++ implementation prior to GCC-13.3 had a bug in reporting the correct format_to_n_result::out value.

# Example

#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";
    }
}

# Defect reports

DRApplied toBehavior as publishedCorrect behavior
P2216R3C++20throws std::format_error for invalid format stringinvalid format string results in compile-time error
P2418R2C++20objects that are neither const-usable nor copyable(such as generator-like objects) are not formattableallow formatting these objects
P2508R1C++20there’s no user-visible name for this facilitythe name basic_format_string is exposed

# See also