Namespaces
Variants

std:: format_to

From cppreference.net
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)
Definido en el encabezado <format>
template < class OutputIt, class ... Args >

OutputIt format_to ( OutputIt out,

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

OutputIt format_to ( OutputIt out,

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

OutputIt format_to ( OutputIt out, const std:: locale & loc,

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

OutputIt format_to ( OutputIt out, const std:: locale & loc,

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

Formatea args de acuerdo con la cadena de formato fmt , y escribe el resultado al iterador de salida out . Si está presente, loc se utiliza para el formato específico de la configuración regional.

Equivalente a:

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


Sea CharT como char para las sobrecargas (1,3) , wchar_t para las sobrecargas (2,4) .

Estas sobrecargas participan en la resolución de sobrecarga solo si OutputIt satisface el concepto std:: output_iterator < const CharT & > .

Si se satisface cualquiera de las siguientes condiciones, el comportamiento es indefinido:

Contenidos

Parámetros

out - iterador al búfer de salida
fmt -
un objeto que representa la cadena de formato. La cadena de formato consiste en
  • caracteres ordinarios (excepto { y } ), que se copian sin cambios a la salida,
  • secuencias de escape { { y } } , que se reemplazan con { y } respectivamente en la salida, y
  • campos de reemplazo.

Cada campo de reemplazo tiene el siguiente formato:

{ arg-id (opcional) } (1)
{ arg-id (opcional) : format-spec } (2)
1) campo de reemplazo sin especificación de formato
2) campo de reemplazo con especificación de formato
arg-id - especifica el índice del argumento en args cuyo valor se usará para el formato; si se omite, los argumentos se usan en orden.

Los arg-id s en una cadena de formato deben estar todos presentes o todos omitidos. Mezclar indexación manual y automática es un error.

format-spec - la especificación de formato definida por la especialización de std::formatter para el argumento correspondiente. No puede comenzar con } .

(desde C++23)
(desde C++26)
  • Para otros tipos formateables, la especificación de formato está determinada por especializaciones formatter definidas por el usuario.
args... - argumentos a formatear
loc - std::locale usado para formato específico de localización

Valor de retorno

Iterador más allá del final del rango de salida.

Excepciones

Propaga cualquier excepción lanzada por operaciones de formateador o iterador.

Notas

Es un error si la cadena de formato no es una expresión constante a menos que se inicialice a partir del resultado de std::runtime_format (desde C++26) . std::vformat_to no tiene este requisito.

Ejemplo

Ejecutar este código 
#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;
}

Salida: 

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

Informes de defectos

Los siguientes informes de defectos que modifican el comportamiento se aplicaron retroactivamente a los estándares publicados anteriormente de C++.

DR Aplicado a Comportamiento publicado Comportamiento correcto
LWG 3539 C++20 out no podía ser un iterador de solo movimiento puede serlo
P2216R3 C++20 lanza std::format_error para cadena de formato inválida resulta en error en tiempo de compilación en su lugar
P2418R2 C++20 objetos que no son ni const-usables ni copiables
(como objetos tipo generador) no son formateables 		permitir formatear estos objetos
P2508R1 C++20 no hay nombre visible para el usuario para esta facilidad el nombre basic_format_string está expuesto

Véase también

(C++20)
almacena la representación formateada de los argumentos en una nueva cadena
(plantilla de función)
(C++20)
escribe la representación formateada de sus argumentos a través de un iterador de salida, sin exceder el tamaño especificado
(plantilla de función)