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

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

Utilities library

Type support (basic types, RTTI, type traits)
Dynamic memory management
Error handling
Program utilities
Variadic functions
Library feature-test macros
Date and time
Function objects
Formatting library (C++20)
initializer_list (C++11)
source_location (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>=
Comparisons (C++20)
three_way_comparablethree_way_comparable_with
strong_ordering weak_ordering partial_ordering common_comparison_category compare_three_way_result compare_three_way	strong_order weak_order partial_order compare_strong_order_fallback compare_weak_order_fallback compare_partial_order_fallback	is_eqis_neqis_ltis_lteqis_gtis_gteq
Common vocabulary types
pair tuple (C++11) apply (C++17) make_from_tuple (C++17)	optional (C++17) any (C++17) variant (C++17)
Swap, forward and move
swap
exchange (C++14)
forward (C++11)
move (C++11)
move_if_noexcept (C++11)
Elementary string conversions
to_chars (C++17)
from_chars (C++17)
chars_format (C++17)
Type operations
declval (C++11)
as_const (C++17)
launder (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.

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.