Namespaces
Variants

std:: range_formatter

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
(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)
range_formatter
(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 T, class CharT = char >

requires std:: same_as < std:: remove_cvref_t < T > , T > && std:: formattable < T, CharT >

class range_formatter ;
(desde C++23)

std::range_formatter es una clase plantilla auxiliar para implementar especializaciones de formateadores de rangos std::formatter .

Contenidos

Especificación de formato de rango

La sintaxis de range-format-spec es:

range-fill-and-align  (opcional) width  (opcional) n (opcional) range-type  (opcional) range-underlying-spec  (opcional)

El range-fill-and-align se interpreta de la misma manera que un fill-and-align excepto que el fill en range-fill-and-align es cualquier carácter distinto de { , } , o : .

El width se describe en la especificación estándar de formato width .

La opción n hace que el rango se formatee sin los corchetes de apertura y cierre. 

assert(std::format("{}", views::iota(1, 5)) == "[1, 2, 3, 4]");
assert(std::format("{:n}", views::iota(1, 5)) == "1, 2, 3, 4");

El format-spec en un range-underlying-spec (su sintaxis es equivalente a : format-spec ), si está presente, es interpretado por el formateador de elementos de rango std::formatter<T, CharT> . 

std::array ints{12, 10, 15, 14};
assert(std::format("{}", ints) == "[12, 10, 15, 14]");
assert(std::format("{::X}", ints) == "[C, A, F, E]");
assert(std::format("{:n:_^4}", ints) == "_12_, _10_, _15_, _14_");

El range-type cambia la forma en que se formatea un rango, con ciertas opciones válidas únicamente con tipos de argumentos específicos.

Los tipos de presentación de rango disponibles son:

  • m : Indica que el corchete de apertura debe ser "{" , el corchete de cierre debe ser "}" , el separador debe ser ", " , y cada elemento del rango debe formatearse como si m estuviera especificado para su tuple-type (en tuple-format-spec ).
  • Si m se elige como el range-type , el programa está mal formado a menos que T sea una especialización de: 
std::array char_pairs
{
    std::pair{'A', 5}, std::pair{'B', 10}, std::pair{'C', 12}
};
assert(std::format("{}", char_pairs) == "[('A', 5), ('B', 10), ('C', 12)]");
assert(std::format("{:m}", char_pairs) == "{'A': 5, 'B': 10, 'C': 12}");
  • s : Indica que el rango debe formatearse como una cadena.
  • ?s : Indica que el rango debe formatearse como una cadena escapada .
  • Si se elige s o ?s como el range-type , ni la opción n ni el range-underlying-spec deben incluirse en el especificador de formato, y
  • el programa está mal formado a menos que T sea CharT . 
std::array star{'S', 'T', 'A', 'R'};
assert(std::format("{}", star) == "['S', 'T', 'A', 'R']");
assert(std::format("{:s}", star) == "STAR");
assert(std::format("{:?s}", star) == "\"STAR\"");

Miembros de datos

Nombre del miembro Definición
std:: formatter < T, CharT > underlying_ (privado) el formateador subyacente para elementos
( objeto miembro solo para exposición* )
std:: basic_string_view < CharT > separator_ (privado) una cadena que representa el separador del resultado formateado del rango. El separador predeterminado es ", " .
( objeto miembro solo para exposición* )
std:: basic_string_view < CharT > opening-bracket_ (privado) una cadena que representa el corchete de apertura del resultado formateado del rango. El corchete de apertura predeterminado es "[" .
( objeto miembro solo para exposición* )
std:: basic_string_view < CharT > closing-bracket_ (privado) una cadena que representa el corchete de cierre del resultado formateado del rango. El corchete de cierre predeterminado es "]" .
( objeto miembro solo para exposición* )

Funciones miembro

set_separator
establece un separador específico para el resultado formateado del rango
(función de miembro pública)
set_brackets
establece corchetes de apertura y cierre específicos para el resultado formateado del rango
(función de miembro pública)
underlying
devuelve el formateador subyacente
(función de miembro pública)
parse
analiza el especificador de formato según lo especificado por range-format-spec
(función de miembro pública)
format
escribe la salida formateada del rango según lo especificado por range-format-spec
(función de miembro pública)

std::range_formatter:: set_separator

constexpr void set_separator ( std:: basic_string_view < CharT > sep ) noexcept ;

Asigna sep a separator_ .

std::range_formatter:: set_brackets

constexpr void set_brackets ( std:: basic_string_view < CharT > opening,
std:: basic_string_view < CharT > closing ) noexcept ;

Asigna opening y closing a opening-bracket_ y closing-bracket_ , respectivamente.

std::range_formatter:: underlying

constexpr std:: formatter < T, CharT > & underlying ( ) ;
(1)
constexpr const std:: formatter < T, CharT > & underlying ( ) const ;
(2)

Devuelve underlying_ (el formateador subyacente).

std::range_formatter:: parse

template < class ParseContext >
constexpr auto parse ( ParseContext & ctx ) - > ParseContext :: iterator ;

Analiza los especificadores de formato como un range-format-spec y almacena los especificadores analizados en el objeto actual.

Llama a underlying_ . parse ( ctx ) para analizar el format-spec en el range-format-spec o, si este último no está presente, un format-spec vacío.

Si está presente el range-type o la opción n , los valores de opening-bracket_ , closing-bracket_ , y separator_ se modifican según sea necesario.

Llama a underlying_ . set_debug_format ( ) si:

  • el range-type no es ni s ni ?s ,
  • underlying_ . set_debug_format ( ) es una expresión válida, y
  • no hay un range-underlying-spec .

Devuelve un iterador más allá del final del range-format-spec .

std::range_formatter:: format

template < ranges:: input_range R, class FormatContext >

requires std:: formattable < ranges:: range_reference_t < R > , CharT > &&
std:: same_as < std:: remove_cvref_t < ranges:: range_reference_t < R >> , T >

auto format ( R && r, FormatContext & ctx ) const - > FormatContext :: iterator ;

Si el tipo-de-rango era s o ?s , escribe el std:: basic_string < CharT > ( std:: from_range , r ) formateado como una cadena o una cadena escapada, respectivamente, en ctx. out ( ) .

De lo contrario, escribe lo siguiente en ctx. out ( ) según lo especificado por especificación-de-formato-de-rango , en orden:

  • corchete-de-apertura_ ,
  • para cada elemento formateable e del rango r :
  • el resultado de escribir e mediante subyacente_ , y
  • separador_ , a menos que e sea el último elemento de r , y
  • corchete-de-cierre_ .

Devuelve un iterador más allá del final del rango de salida.

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 3892 C++23 el formato de rangos anidados era incorrecto corregido

Véase también

(C++20)
define las reglas de formato para un tipo dado
(plantilla de clase)