std::formatter

 

C++

Apoyo de compiladores

Implementaciones independientes y albergadas

Lenguaje

Biblioteca estándar

Encabezados de la biblioteca estándar

Requisitos denominados

Macros de prueba de característica (C++20)

Biblioteca de apoyo del lenguaje

Biblioteca de conceptos(C++20)

Biblioteca de diagnósticos

Biblioteca de gestión de memoria

Biblioteca de metaprogramación(C++11)

Biblioteca de servicios generales

Biblioteca de contenedores

Biblioteca de iteradores

Biblioteca de rangos(C++20)

Biblioteca de algoritmos

Biblioteca de cadenas

Biblioteca de procesamiento de texto

Biblioteca numérica

Biblioteca de fecha y hora

Biblioteca de entrada/salida

Biblioteca del sistema de archivos(C++17)

Biblioteca de apoyo de concurrencia(C++11)

Biblioteca de apoyo de ejecución(C++26)

Especificaciones técnicas

Índice de símbolos

Bibliotecas externas

 

Biblioteca de servicios

Apoyo del lenguaje Apoyo de tipos (tipos básicos, RTTI) Biblioteca de macros de prueba de característica(C++20) Servicios del programa Apoyo de corrutinas(C++20) Funciones variádicas is_constant_evaluated (C++20) is_within_lifetime (C++26) initializer_list (C++11) source_location (C++20) Comparación de tres vías three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

Servicios generales Objetos función Manipulación de bits(C++20) bitset hash (C++11) Operadores relacionales(en desuso en C++20) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= Funciones de comparación de enteros cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Intercambio y operaciones de tipos swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Tipos vocabulario comunes pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23)

 

Biblioteca de formato

Funciones de formato

format (C++20)

format_to (C++20)

format_to_n (C++20)

formatted_size (C++20)

vformat (C++20)

vformat_to (C++20)

Formateador

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)

Argumentos de formato

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)

Error de formato

format_error (C++20)

 

Definido en el archivo de encabezado <format>
template<class T, class CharT =char> struct formatter;		(desde C++20)

Las especializaciones habilitadas de formatter definen reglas de formato para un tipo dado. Las especializaciones habilitadas cumplen con los requerimientos de Formatter. En particular, definen funciones miembro o plantillas de función parse y format, tales que:

• El miembro parse ...

• acepta un solo parámetro pc de tipo std::basic_format_parse_context<CharT>;
• analiza la especificación de formato para el tipo T en el rango [pc.begin(), pc.end());
• almacena los especificadores de formato analizados en *this;
• devuelve un valor de tipo std::basic_format_parse_context<CharT>::iterator que representa el final de la especificación de formato;
• puede lanzar std::format_error para indicar un error en la cadena de formato;

• El miembro format ...

• acepta dos parámetros: un parámetro t de tipo T seguido de un parámetro fc de tipo std::basic_format_context<OutputIt, CharT>, donde OutputIt es un tipo de iterador de salida;
• formatea a t de acuerdo a los especificadores almacenados en *this;
• escribe la salida a fc.out();
• devuelve un valor de tipo std::basic_format_context<OutputIt, CharT>::iterator que representa el final de la salida;
• la salida debe depender solamente de t, fc.locale(), y los últimos especificadores de formato analizados.

Las especializaciones habilitadas son DefaultConstructible, CopyConstructible, CopyAssignable, Swappable y Destructible.

Para todos los tipos T y CharT para los que ni la biblioteca ni el usuario proporcionan una especialización habilitada std::formatter<T, CharT>, esa especialización es un tipo completo y está deshabilitada. Las especializaciones deshabilitadas no cumplen con los requerimientos de Formatter, y std::is_default_constructible_v, std::is_copy_constructible_v, std::is_move_constructible_v, std::is_copy_assignable_v, std::is_move_assignable_v son todos false.

Especializaciones estándar para tipos básicos y tipos cadena

En la siguiente lista, CharT es ya sea char o wchar_t, ArithmeticT es cualquier tipo aritmético no calificado-cv distinto de char, wchar_t, char8_t, char16_t, o char32_t.

template<>struct formatter<char, char>; template<>struct formatter<char, wchar_t>; template<>struct formatter<wchar_t, wchar_t>; template<>struct formatter<CharT*, CharT>; template<>struct formatter<const CharT*, CharT>; template<std::size_t N>struct formatter<const CharT[N], CharT>; template<class Traits, class Alloc>   struct formatter<std::basic_string<CharT, Traits, Alloc>, CharT>; template<class Traits>   struct formatter<std::basic_string_view<CharT, Traits>, CharT>; template<>struct formatter<ArithmeticT, CharT>; template<>struct formatter<std::nullptr_t, CharT>; template<>struct formatter<void*, CharT>; template<>struct formatter<constvoid*, CharT>;

Los formateadores para otros punteros y punteros a miembro están deshabilitados.

Las especializaciones como std::formatter<wchar_t, char> y std::formatter<const char*, wchar_t> que requerirían conversiones de codificación están deshabilitadas.

Especificación de formato estándar

Para tipos básicos y tipos cadena, la especificación de formato está basada en la especificación de formato en Python.

La sintaxis de la especificación de formato es:

rellenar-y-alinear(opcional)signo(opcional)#(opcional)0(opcional)anchura(opcional)precisión(opcional)L(opcional)tipo(opcional)

Las opciones de signo, # y 0 solo son válidas cuando se usa un tipo de presentación de entero o de punto flotante.

rellenar y alinear

rellenar-y-alinear es un carácter opcional de relleno (que puede ser cualquier carácter distinto de { o }), seguido de una de las opciones de alinear<, >, ^. El significado de las opciones de alinear es el siguiente:

• <: Fuerza al campo a que esté alineado al comienzo del espacio disponible. Este es el valor predeterminado cuando se utiliza un tipo de presentación que no es ni de punto flotante ni entero.
• >: Fuerza al campo a que esté alineado al final del espacio disponible. Este es el valor predeterminado cuando se utiliza un tipo de presentación de punto flotante o entero.
• ^: Fuerza al campo a que esté centrado dentro del espacio disponible al insertar caracteres ⌊

  n

  2

  ⌋ antes y caracteres ⌈

  n

  2

  ⌉ después del valor, donde n es el número total de los caracteres de relleno a insertar.

char c =120;auto s0 =std::format("{:6}", 42);// el valor de s0 es " 42"auto s1 =std::format("{:6}", 'x');// el valor de s1 es "x "auto s2 =std::format("{:*<6}", 'x');// el valor de s2 es "x*****"auto s3 =std::format("{:*>6}", 'x');// el valor de s3 es "*****x"auto s4 =std::format("{:*^6}", 'x');// el valor de s4 es "**x***"auto s5 =std::format("{:6d}", c);// el valor de s5 es " 120"auto s6 =std::format("{:6}", true);// el valor de s6 es "true "

signo, #, y 0

La opción signo puede ser una de las siguientes:

• +: Indica que un signo debería usarse tanto para números no negativos como negativos. El signo + se inserta antes del valor de salida para números no negativos.
• -: Indica que un signo debería usarse solo para números negativos (este es el comportamiento por defecto).
• espacio: Indica que se debe usar un espacio inicial para números no negativos y un signo menos para números negativos.

El cero negativo se trata como un número negativo.

La opción signo se aplica al infinito de punto flotante y NaN.

double inf =std::numeric_limits<double>::infinity();double nan =std::numeric_limits<double>::quiet_NaN();auto s0 =std::format("{0:},{0:+},{0:-},{0: }", 1);// el valor de s0 es "1,+1,1, 1"auto s1 =std::format("{0:},{0:+},{0:-},{0: }", -1);// el valor de s1 es "-1,-1,-1,-1"auto s2 =std::format("{0:},{0:+},{0:-},{0: }", inf);// el valor de s2 es "inf,+inf,inf, inf"auto s3 =std::format("{0:},{0:+},{0:-},{0: }", nan);// el valor de s3 es "nan,+nan,nan, nan"

La opción # ocasiona que se use la forma alterna para la conversión.

• Para tipos enteros, cuando se usa el tipo de presentación binaria, octal o hexadecimal, la forma alterna inserta el prefijo (0b, 0, o 0x) dentro del valor de salida después del carácter de signo (posiblemente un espacio) si es que lo hay, o de lo contrario, lo agrega antes del valor de salida.
• Para tipos de punto flotante, la forma alterna ocasiona que el resultado de la conversión de valores finitos siempre contenga un carácter de punto decimal, incluso si no lo sigue ningún dígito. Además, para las conversiones g y G, los ceros finales no se eliminan del resultado.

La opción 0 rellena el campo con ceros a la izquierda (después de cualquier indicación de signo o base) a la anchura del campo, excepto cuando se aplica a un infinito o NaN. Si aparecen el carácter 0 y una opción alinear, se ignora el carácter 0.

char c =120;auto s1 =std::format("{:+06d}", c);// el valor de s1 es "+00120"auto s2 =std::format("{:#06x}", 0xa);// el valor de s2 es "0x000a"auto s3 =std::format("{:<06}", -42);// el valor de s3 es "-42 " (0 se ignora porque < alignment)

anchura y precisión

anchura es o bien un número decimal positivo, o un campo de reemplazo anidado ({} o {n}). Si está presente, especifica la anchura mínima del campo.

precisión es un punto (.) seguido ya sea de un número decimal no negativo o un campo de reemplazo anidado. Este campo indica la precisión o tamaño máximo del campo. Solo puede usarse con tipos de punto flotante y de cadena. Para los tipos de punto flotante, este campo especifica la precisión de formato. Para los tipos cadena, especifica cuántos caracteres se usarán de la cadena.

Si un campo de reemplazo anidado se usa para la anchura o la precisión, y el argumento correspondiente no es de tipo entero, o es negativo, o es cero para la anchura, se lanza una excepción de tipo std::format_error.

float pi =3.14f;auto s1 =std::format("{:10f}", pi);// s1 = " 3.140000" (anchura = 10)auto s2 =std::format("{:{}f}", pi, 10);// s2 = " 3.140000" (anchura = 10)auto s3 =std::format("{:.5f}", pi);// s3 = "3.14000" (precisión = 5)auto s4 =std::format("{:.{}f}", pi, 5);// s4 = "3.14000" (precisión = 5)auto s5 =std::format("{:10.5f}", pi);// s5 = " 3.14000" (anchura = 10, precisión = 5)auto s6 =std::format("{:{}.{}f}", pi, 10, 5);// s6 = " 3.14000" (anchura = 10, precisión = 5)   auto b1 =std::format("{:{}f}", pi, 10.0);// lanza: el argumento de anchura no es de tipo entero auto b2 =std::format("{:{}f}", pi, -10);// lanza: la anchura es negativaauto b3 =std::format("{:.{}f}", pi, 5.0);// lanza: la precisión no es de tipo entero

L (formateo específico de la configuración regional)

La opción L ocasiona que se use la forma específica de la configuración regional. Esta opción solo es válida para tipos aritméticos.

• Para los tipos enteros, la forma específica de la configuración regional inserta el grupo de caracteres de separadores de dígitos apropiado de acuerdo a la configuración regional del contexto.
• Para los tipos de punto flotante, la forma específica de la configuración regional inserta el grupo de dígitos apropiado y los caracteres separadores de base de acuerdo a la configuración regional del contexto.
• Para la representación textual de bool, la forma específica de la configuración regional usa la cadena apropiada como si se hubiera obtenido con std::numpunct::truename o std::numpunct::falsename.

tipo

La opción tipo determina cómo deberían presentarse los datos .

Los tipos de presentación de cadena disponibles son:

• ninguno, s: Copia la cadena a la salida.

Los tipos de presentación disponibles para tipos enteros distintos de char, wchar_t, y bool son:

• b: Formato binario. Produce la salida como si se llamara a std::to_chars(first, last, value, 2). El prefijo de la base es 0b.
• B: Igual que b, excepto que el prefijo de la base es 0B.
• c: Copia el carácter static_cast<CharT>(value) a la salida, donde CharT es el tipo de carácter de la cadena de formato. Lanza std::format_error si el valor no está en el rango de valores representables para CharT.
• d: Formato decimal. Produce la salida como si se llamara a std::to_chars(first, last, value).
• o: Formato octal. Produce la salida como si se llamara a std::to_chars(first, last, value, 8). El prefijo de la base es 0 si el valor del argumento correspondiente no es cero, y de lo contrario, está vacío.
• x: Formato hexadecimal. Produce la salida como si se llamara a std::to_chars(first, last, value, 16). El prefijo de la base es 0x.
• X: Igual que x, excepto que usa letras mayúsculas para dígitos mayores a 9 y el prefijo de la base es 0X.
• ninguno: Igual que d.

Los tipos de presentación disponibles char y wchar_t son:

• ninguno, c: Copia el carácter a la salida.
• b, B, d, o, x, X: Usa tipos de presentación enteros.

Los tipos de presentación disponibles bool son:

• ninguno, s: Copia la representación textual (true o false, o la forma específica de la configuración regional) a la salida.
• b, B, c, d, o, x, X: Usa tipos de presentación enteros con el valor static_cast<unsigned char>(value).

Los tipos de presentación disponibles de punto flotante son:

• a: Si se especifica precisión, produce la salida como si se llamara a std::to_chars(first, last, value, std::chars_format::hex, precisión), donde precisión es la precisión especificada; de lo contrario, la salida se produce como si se llamara a std::to_chars(first, last, value, std::chars_format::hex).
• A: Igual que a, excepto que usa letras mayúsculas para dígitos mayores a 9 y usa P para indicar el exponente.
• e: Produce la salida como si se llamara a std::to_chars(first, last, value, std::chars_format::scientific, precisión), donde precisión es la precisión especificada, o 6 si no se especifica la precisión.
• E: Igual que e, excepto que usa E para indicar el exponente.
• f, F: Produce la salida como si se llamara a std::to_chars(first, last, value, std::chars_format::fixed, precisión), donde precisión es la precisión especificada, o 6 si no se especifica la precisión.
• g: Produce la salida como si se llamara a std::to_chars(first, last, value, std::chars_format::general, precisión) donde precisión es la precisión especificada, o 6 si no se especifica la precisión.
• G: Igual que g, excepto que usa E para indicar el exponente.
• ninguno: Si se especifica precisión, produce la salida como si se llamara a std::to_chars(first, last, value, std::chars_format::general, precisión), donde precisión es la precisión especificada; de lo contrario, la salida se produce como si se llamara a std::to_chars(first, last, value).

Para tipos de presentación en minúsculas, infinito y NaN se formatean como inf y nan, respectivamente. Para tipos de presentación en mayúsculas, infinito y NaN se formatean como INF y NAN, respectivamente.

Los tipos de presentación de puntero disponibles (también usados para std::nullptr_t) son:

• ninguno, p: Si std::uintptr_t está definido, produce la salida como si se llamara a std::to_chars(first, last, reinterpret_cast<std::uintptr_t>(value), 16) con el prefijo 0x añadido a la salida; de lo contrario, la salida está definida por la implementación.

Especializaciones estándar para tipos de la biblioteca

std::formatter<std::chrono::duration> (C++20)	Especialización de std::formatter que da formato a un objeto de tipo duration según el formato proporcionado. (especialización de plantilla de clase)
std::formatter<std::chrono::sys_time> (C++20)	Especialización de std::formatter que formatea sys_time de acuerdo al formato suministrado (especialización de plantilla de clase)
std::formatter<std::chrono::utc_time> (C++20)	Especialización de std::formatter que formatea utc_time de acuerdo al formato suministrado (especialización de plantilla de clase)
std::formatter<std::chrono::tai_time> (C++20)	Especialización de std::formatter que formatea tai_time de acuerdo al formato suministrado (especialización de plantilla de clase)
std::formatter<std::chrono::gps_time> (C++20)	Especialización de std::formatter que formatea gps_time de acuerdo al formato suministrado (especialización de plantilla de clase)
std::formatter<std::chrono::file_time> (C++20)	Especialización de std::formatter que formatea file_time de acuerdo al formato suministrado (especialización de plantilla de clase)
std::formatter<std::chrono::local_time> (C++20)	Especialización de std::formatter que formatea local_time de acuerdo al formato suministrado (especialización de plantilla de clase)
std::formatter<std::chrono::day> (C++20)	Especialización de std::formatter que formatea un objeto day de acuerdo al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::month> (C++20)	Especialización de std::formatter que formatea un objeto month de acuerdo al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::year> (C++20)	Especialización de std::formatter que formatea un objeto year conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::weekday> (C++20)	Especialización de std::formatter que formatea un weekday de acuerdo al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::weekday_indexed> (C++20)	Especialización de std::formatter formatea un objeto weekday_indexed conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::weekday_last> (C++20)	Especialización de std::formatter que formatea un weekday_last de acuerdo al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::month_day> (C++20)	Especialización de std::formatter que formatea un objeto month_day conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::month_day_last> (C++20)	Especialización de std::formatter que formatea un objeto month_day_last conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::month_weekday> (C++20)	Especialización de std::formatter que formatea un objeto month_weekday conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::month_weekday_last> (C++20)	Especialización de std::formatter que formatea un objeto month_weekday_last conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::year_month> (C++20)	Especialización de std::formatter que formatea un objeto year_month conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::year_month_day> (C++20)	Especialización de std::formatter que formatea un objeto year_month_day conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::year_month_day_last> (C++20)	Especialización de std::formatter que formatea un objeto de tipo year_month_day_last conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::year_month_weekday> (C++20)	Especialización de std::formatter que formatea un objeto de tipo year_month_weekday conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::year_month_weekday_last> (C++20)	Especialización de std::formatter que formatea un objeto de tipo year_month_weekday_last conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::hh_mm_ss> (C++20)	Especialización de std::formatter que formatea un hh_mm_ss de acuerdo al formato proporcionado. (especialización de plantilla de clase)
std::formatter<std::chrono::sys_info> (C++20)	Especialización de std::formatter que formatea un objeto sys_info conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::local_info> (C++20)	Especialización de std::formatter que formatea un objeto local_info conforme al formato suministrado. (especialización de plantilla de clase)
std::formatter<std::chrono::zoned_time> (C++20)	Especialización de std::formatter que formatea un objeto zoned_time conforme al formato proporcionado. (especialización de plantilla de clase)

Ejemplo

Ejecuta este código

#include <format>#include <iostream>   // Un envoltorio para el tipo Ttemplate<class T>struct Box { T value;};   // El envoltorio Box<T> puede formatearse usando la especificación de formato del valor envueltotemplate<class T, class CharT>struct std::formatter<Box<T>, CharT>: std::formatter<T, CharT>{// parse() se hereda de la clase base   // Define a format() llamando a la implementación de la clase base con el valor envueltotemplate<class FormatContext>auto format(Box<T> t, FormatContext& fc){return std::formatter<T, CharT>::format(t.value, fc);}};   int main(){ Box<int> v ={42};std::cout<<std::format("{:#x}", v);}

Salida:

0x2a

Véase también

basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)

Estado de formato, incluyendo todos los argumentos de formato y el iterador de salida. (plantilla de clase)