Namespaces
Variants

std:: format_to_n, std:: format_to_n_result

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
(C++20)
format_to_n
(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 >

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,

std:: format_string < Args... > fmt, Args && ... args ) ;
(1) (desde 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:: wformat_string < Args... > fmt, Args && ... args ) ;
(2) (desde 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:: format_string < Args... > fmt, Args && ... args ) ;
(3) (desde 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:: wformat_string < Args... > fmt, Args && ... args ) ;
(4) (desde C++20)
Tipos auxiliares
template < class OutputIt >

struct format_to_n_result {
OutputIt out ;
std:: iter_difference_t < OutputIt > size ;

} ;
(5) (desde C++20)

Formatee args de acuerdo con la cadena de formato fmt , y escriba el resultado en el iterador de salida out . Se escriben como máximo n caracteres. Si está presente, loc se utiliza para el formato específico de la configuración regional.

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 & > .

El comportamiento es indefinido si OutputIt no modela (no cumple con los requisitos semánticos de) el concepto std:: output_iterator < const CharT & > , o si std:: formatter < std:: remove_cvref_t < Ti > , CharT > no cumple con los requisitos de BasicFormatter para cualquier Ti en Args .

5) std::format_to_n_result no tiene clases base, ni miembros aparte de out , size y las funciones miembro especiales declaradas implícitamente.

Contenidos

Parámetros

out - iterador al búfer de salida
n - número máximo de caracteres a escribir en el búfer
fmt -
un objeto que representa la cadena de formato. La cadena de formato consta de
  • 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 utilizará para el formato; si se omite, los argumentos se utilizan 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 de formatter definidas por el usuario.
args... - argumentos a formatear
loc - std::locale utilizado para el formato específico de la configuración regional

Valor de retorno

Un format_to_n_result tal que el miembro out sea un iterador después del final del rango de salida, y el miembro size sea el tamaño total (no truncado) de la salida.

Excepciones

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

Notas

La implementación de libstdc++ anterior a GCC-13.3 tenía un error al reportar el valor correcto de format_to_n_result :: out .

Ejemplo

En Godbolt's Compiler Explorer: clang (trunk) + libc++ , GCC (trunk) + libstdc++ .

Ejecutar este código 
#include <format>
#include <initializer_list>
#include <iomanip>
#include <iostream>
#include <string_view>
int main()
{
    char buffer[64];
    for (std::size_t max_chars_to_write : {std::size(buffer) - 1, 23uz, 21uz})
    {
        const std::format_to_n_result result =
            std::format_to_n(
                buffer, max_chars_to_write,
                "Hubble's H{2} {3} {0}{4}{1} km/sec/Mpc.", // 24 bytes w/o formatters
                71,       // {0}, occupies 2 bytes
                8,        // {1}, occupies 1 byte
                "\u2080", // {2}, occupies 3 bytes, '₀' (SUBSCRIPT ZERO)
                "\u2245", // {3}, occupies 3 bytes, '≅' (APPROXIMATELY EQUAL TO)
                "\u00B1"  // {4}, occupies 2 bytes, '±' (PLUS-MINUS SIGN)
                ); // 24 + 2 + 1 + 3 + 3 + 2 == 35, no trailing '\0'
        *result.out = '\0'; // adds terminator to buffer
        const std::string_view str(buffer, result.out);
        std::cout << "Buffer until '\\0': " << std::quoted(str) << '\n'
                  << "Max chars to write: " << max_chars_to_write << '\n'
                  << "result.out offset: " << result.out - buffer << '\n'
                  << "Untruncated output size: " << result.size << "\n\n";
    }
}

Salida: 

Buffer until '\0': "Hubble's H₀ ≅ 71±8 km/sec/Mpc."
Max chars to write: 63
result.out offset: 35
Untruncated output size: 35
Buffer until '\0': "Hubble's H₀ ≅ 71±8"
Max chars to write: 23
result.out offset: 23
Untruncated output size: 35
Buffer until '\0': "Hubble's H₀ ≅ 71�"
Max chars to write: 21
result.out offset: 21
Untruncated output size: 35

Informes de defectos

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

DR Aplicado a Comportamiento publicado Comportamiento correcto
P2216R3 C++20 lanza std::format_error para cadena de formato inválida cadena de formato inválida resulta en error en tiempo de compilación
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
(plantilla de función)
(C++20)
determina el número de caracteres necesarios para almacenar la representación formateada de sus argumentos
(plantilla de función)