std::format_to_n

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

Utilities library

Language support Type support (basic types, RTTI, type traits) Library feature-test macros (C++20) Dynamic memory management Program utilities Error handling Coroutine support (C++20) Variadic functions launder (C++17) initializer_list (C++11) source_location (C++20) Three-way comparison (C++20) three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20) is_eqis_neqis_ltis_lteqis_gtis_gteq (C++20)(C++20)(C++20)(C++20)(C++20)(C++20)

General utilities Date and time Function objects Formatting library (C++20) bitset hash (C++11) integer_sequence (C++14) Relational operators (deprecated in C++20) rel_ops::operator!=rel_ops::operator>rel_ops::operator<=rel_ops::operator>= Integer comparison functions cmp_equalcmp_not_equalcmp_lesscmp_greatercmp_less_thancmp_greater_than (C++20)(C++20)(C++20)(C++20)(C++20)(C++20) in_range (C++20) Swap and type operations swap ranges::swap (C++20) exchange (C++14) declval (C++11) forward (C++11) move (C++11) move_if_noexcept (C++11) as_const (C++17) Common vocabulary types pair tuple (C++11) apply (C++17) make_from_tuple (C++17) optional (C++17) any (C++17) variant (C++17) Elementary string conversions to_chars (C++17) from_chars (C++17) chars_format (C++17)

 

Formatting library

Formatting functions

format (C++20)

format_to (C++20)

format_to_n (C++20)

formatted_size (C++20)

vformat (C++20)

vformat_to (C++20)

Formatter

formatter (C++20)

basic_format_parse_contextformat_parse_contextwformat_parse_context (C++20)(C++20)(C++20)

basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)

Formatting arguments

basic_format_arg (C++20)

basic_format_argsformat_argswformat_argsformat_args_t (C++20)(C++20)(C++20)(C++20)

visit_format_arg (C++20)

make_format_argsmake_wformat_args (C++20)(C++20)

Format error

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::string_view fmt, const 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::wstring_view fmt, const 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::string_view fmt, const 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::wstring_view fmt, const Args&... args);	(4)	(since C++20)
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 decltype(fmt)::char_type (char for overloads (1,3), wchar_t for overloads (2,4)).

These overloads only participate in overload resolution 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 the concept std::output_iterator<const CharT&>, or if std::formatter<Ti, CharT> does not meet the Formatter 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.

Parameters

out	-	iterator to the output buffer
n	-	maximum number of characters to be written to the buffer
fmt	-	string view representing 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: introductory { character; (optional) arg-id, a non-negative number; (optional) a colon (:) followed by a format specification; final } character. arg-id specifies the index of the argument in args whose value is to be used for formatting; if arg-id is omitted, the arguments are used in order. The arg-ids in a format string must all be present or all be omitted. Mixing manual and automatic indexing is an error. The format specification is defined by the std::formatter specialization for the corresponding argument. 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 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

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.

Exceptions

Throws std::format_error if fmt is not a valid format string for the provided arguments. Also propagates any exception thrown by formatter or iterator operations.

Example

Run this code

#include <format>
#include <string_view>
#include <iostream>
 
int main()
{
    char buffer[64];
 
    const auto result =
        std::format_to_n(buffer, std::size(buffer), 
                         "Hubble's H{0} {1} {2} miles/sec/mpc.",
                         "\u2080", "\u2245", 42);
 
    std::cout << "Buffer: \"" << std::string_view{buffer, result.size} << "\"\n"
              << "Buffer size = " << std::size(buffer) << '\n'
              << "Untruncated output size = " << result.size << '\n';
}

Output:

Buffer: "Hubble's H₀ ≅ 42 miles/sec/mpc."
Buffer size = 64
Untruncated output size = 35

See also

format (C++20)	stores formatted representation of the arguments in a new string (function template)
format_to (C++20)	writes out formatted representation of its arguments through an output iterator (function template)
formatted_size (C++20)	determines the number of characters necessary to store the formatted representation of its arguments (function template)