Namespaces
Variants
    Actions

      std::format_to

      From cppreference.com
      < cpp‎ | utility‎ | format
       
      C++
       
      Text processing library
       
      Formatting library
      Standard format specification
      Formatting functions
      (C++20)
      format_to
      (C++20)
      (C++20)
      (C++20)
      (C++20)
      (C++20)
      Format strings
      (C++20)(C++20)(C++20)
      (C++26)
      Formatting concepts
      (C++23)
      Formatter
      (C++20)
      (C++23)
      (C++23)
      (C++23)
      (C++23)
      (C++20)(C++20)(C++20)
      (C++20)(C++20)(C++20)
      (C++23)
      (C++23)
      Formatting arguments
      (C++20)
      (C++20)
      (C++20)(C++20)(C++20)
      (C++20)(deprecated in C++26)
      (C++20)(C++20)
      Format error
      (C++20)
       
      Defined in header <format>
      template<class OutputIt, class... Args>

      OutputIt format_to( OutputIt out,

                          std::format_string<Args...> fmt, Args&&... args);
      		 (1) (since C++20)
      template<class OutputIt, class... Args>

      OutputIt format_to( OutputIt out,

                          std::wformat_string<Args...> fmt, Args&&... args);
      		 (2) (since C++20)
      template<class OutputIt, class... Args>

      OutputIt format_to( OutputIt out, conststd::locale& loc,

                          std::format_string<Args...> fmt, Args&&... args);
      		 (3) (since C++20)
      template<class OutputIt, class... Args>

      OutputIt format_to( OutputIt out, conststd::locale& loc,

                          std::wformat_string<Args...> fmt, Args&&... args);
      		 (4) (since C++20)

      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.

      Equivalent to:

      1)returnstd::vformat_to(std::move(out), fmt.str, std::make_format_args(args...));
      2)returnstd::vformat_to(std::move(out), fmt.str, std::make_wformat_args(args...));
      3)returnstd::vformat_to(std::move(out), loc, fmt.str, std::make_format_args(args...));
      4)returnstd::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 satisfies the concept std::output_iterator<const CharT&>.

      If any of the following conditions is satisfied, the behavior is undefined:

      Contents

      [edit]Parameters

      out - iterator to the output buffer
      fmt -
      [edit]
      an object that represents 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:

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

      (since C++23)
      (since C++26)
      • 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

      [edit]Return value

      Iterator past the end of the output range.

      [edit]Exceptions

      Propagates any exception thrown by formatter or iterator operations.

      [edit]Notes

      As of P2216R3, it is an error if the format string is not a constant expression. std::vformat_toor std::runtime_format(since C++26) can be used in this case.

      [edit]Example

      Run this code
      #include <format>#include <iostream>#include <iterator>#include <string>   int main(){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::flush;   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()!

      [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
      LWG 3539C++20 out could not be a move-only iterator it can be
      P2216R3C++20 throws std::format_error for invalid format string results in compile-time error instead
      P2418R2C++20 objects that are neither const-usable nor copyable
      (such as generator-like objects) are not formattable       		allow formatting these objects
      P2508R1C++20 there's no user-visible name for this facility the name basic_format_string is exposed

      [edit]See also

      (C++20)
      		 stores formatted representation of the arguments in a new string
      (function template)[edit]
      (C++20)
      		 writes out formatted representation of its arguments through an output iterator, not exceeding specified size
      (function template)[edit]
      Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility/format/format_to&oldid=179715"
      close