home | help 
std::format_to(3)	       C++ Standard Libary	       std::format_to(3)

NAME
     std::format_to - std::format_to

Synopsis
	Defined in header <format>
	template< class OutputIt, class... Args >
	OutputIt  format_to(  OutputIt out, std::format_string<Args...> fmt, (1)
     (since C++20)
	Args&&... args );
	template< class OutputIt, class... Args >
	OutputIt format_to( OutputIt out,  std::wformat_string<Args...>      (2)
     (since C++20)
	fmt, Args&&... args );
	template< class OutputIt, class... Args >

	OutputIt  format_to(  OutputIt out, const std::locale& loc,	     (3)
     (since C++20)

			    std::format_string<Args...> fmt, Args&&...
	args );
	template< class OutputIt, class... Args >

	OutputIt format_to( OutputIt out, const std::locale&  loc,	     (4)
     (since C++20)

			    std::wformat_string<Args...> fmt, Args&&...
	args );

	Format	args according to the format string fmt, and write the result to
     the output
	iterator out. If present, loc is used for locale-specific formatting.

	1) equivalent to return std::vformat_to(out, fmt.str,
	std::make_format_args(args...));
	2) equivalent to return std::vformat_to(std::move(out), fmt.str,
	std::make_wformat_args(args...));
	3) equivalent to return std::vformat_to(out, loc, fmt.str,
	std::make_format_args(args...));
	4) equivalent to return std::vformat_to(std::move(out), loc, fmt.str,
	std::make_wformat_args(args...));

	Let CharT be char for overloads (1,3), wchar_t for overloads (2,4).

	These overloads participate in overload resolution only if OutputIt sat-
     isfies 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::format-
     ter<Ti, CharT>
	does not meet the BasicFormatter requirements for any Ti in Args (as re-
     quired by
	std::make_format_args and std::make_wformat_args).

Parameters
	out	- iterator to the output buffer

		  an object that represents the format string. The format string
     consists of
		    * ordinary characters (except { and }), which are copied un-
     changed 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

				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.
		  arg-id      -
				The arg-idas in a  format  string  must  all  be
     present or all
				be omitted. Mixing manual and automatic indexing
     is an
				error.
	fmt	  -		    the  format  specification	defined  by  the
     std::formatter
		  format-spec - specialization for the	corresponding  argument.
     Cannot start
				with }.

		    *  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 range types, the format specification is interpreted
		      as range format specification.
		    * For std::pair and std::tuple, the format specification
		      is interpreted as tuple format specification.
		    *	For   std::thread::id	and  std::stacktrace_entry,  see
     (since C++23)
		      thread id format specification and stacktrace entry
		      format specification.
		    * For std::basic_stacktrace, no format specifier is
		      allowed.

		    *	 For	std::filesystem::path,	  see	 path	  format
     (since C++26)
		      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
	Iterator past the end of the output range.

Exceptions
	Propagates any exception thrown by formatter or iterator operations.

Notes
	As of P2216R3, it is an error if the format string is not a constant ex-
     pression.
	std::vformat_to
	or std::runtime_format
	(since C++26) can be used in this case.

Example
     // Run this code

      #include <format>
      #include <iostream>
      #include <iterator>
      #include <string>

      auto main() -> int
      {
	  std::string buffer;

	  std::format_to(
	      std::back_inserter(buffer), //< OutputIt
	      "Hello, C++{}!\n",	  //< fmt
	      "20");			  //< arg
	  std::cout << buffer;
	  buffer.clear();

	  std::format_to(
	      std::back_inserter(buffer), //< OutputIt
	      "Hello, {0}::{1}!{2}",	  //< fmt
	      "std",			  //< arg {0}
	      "format_to()",		  //< arg {1}
	      "\n",			  //< arg {2}
	      "extra param(s)...");	  //< unused
	  std::cout << buffer;

	  std::wstring wbuffer;
	  std::format_to(
	      std::back_inserter(wbuffer),//< OutputIt
	      L"Hello, {2}::{1}!{0}",	  //< fmt
	      L"\n",			  //< arg {0}
	      L"format_to()",		  //< arg {1}
	      L"std",			  //< arg {2}
	      L"...is not..."		  //< unused
	      L"...an error!"); 	  //< unused
	  std::wcout << wbuffer;
      }

Output:
      Hello, C++20!
      Hello, std::format_to()!
      Hello, std::format_to()!

	Defect reports

	The following behavior-changing defect	reports  were  applied	retroac-
     tively to
	previously published C++ standards.

	  DR	 Applied to	 Behavior as published		     Correct be-
     havior
	P2216R3  C++20	     throws  std::format_error	for	 invalid  format
     string results in
			   invalid format string	    compile-time error
			   objects that are neither
	P2418R2  C++20	     const-usable  nor	copyable	allow formatting
     these objects
			   (such as generator-like objects)
			   are not formattable
	P2508R1 C++20	   there's no user-visible name for the name  basic_for-
     mat_string is
			   this facility		    exposed

See also
	format	     stores  formatted	representation of the arguments in a new
     string
	(C++20)     (function template)
	format_to_n writes out formatted representation of its arguments through
     an output
	(C++20)     iterator, not exceeding specified size
		    (function template)

http://cppreference.com 	   2024.06.10		       std::format_to(3)
home | help