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)
Défini dans l'en-tête <format>
template < class T, class CharT = char >

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

class range_formatter ;
(depuis C++23)

std::range_formatter est une classe template utilitaire pour implémenter des spécialisations de formateur de plage std::formatter .

Table des matières

Spécification du format de plage

La syntaxe de range-format-spec est :

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

Le range-fill-and-align est interprété de la même manière qu'un fill-and-align sauf que le fill dans range-fill-and-align est tout caractère autre que { , } , ou : .

La width est décrite dans la spécification standard de format width .

L'option n entraîne le formatage de la plage sans les crochets d'ouverture et de fermeture. 

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

Le format-spec dans un range-underlying-spec (sa syntaxe est équivalente à : format-spec ), s'il est présent, est interprété par le formateur d'éléments de plage 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_");

Le range-type modifie la manière dont une plage est formatée, certaines options n'étant valides qu'avec certains types d'arguments.

Les types de présentation de plage disponibles sont :

  • m : Indique que le crochet ouvrant doit être "{" , le crochet fermant doit être "}" , le séparateur doit être ", " , et chaque élément de la plage doit être formaté comme si m était spécifié pour son tuple-type (dans tuple-format-spec ).
  • Si m est choisi comme range-type , le programme est mal formé sauf si T est soit une spécialisation 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 : Indique que la plage doit être formatée en tant que chaîne de caractères.
  • ?s : Indique que la plage doit être formatée en tant que chaîne échappée .
  • Si s ou ?s est choisi comme range-type , l'option n et le range-underlying-spec ne doivent pas être inclus dans le spécificateur de format, et
  • le programme est mal formé sauf si T est 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\"");

Membres de données

Nom du membre Définition
std:: formatter < T, CharT > underlying_ (privé) le formateur sous-jacent pour les éléments
( objet membre d'exposition uniquement* )
std:: basic_string_view < CharT > separator_ (privé) une chaîne représentant le séparateur du résultat formaté de la plage. Le séparateur par défaut est ", " .
( objet membre d'exposition uniquement* )
std:: basic_string_view < CharT > opening-bracket_ (privé) une chaîne représentant le crochet ouvrant du résultat formaté de la plage. Le crochet ouvrant par défaut est "[" .
( objet membre d'exposition uniquement* )
std:: basic_string_view < CharT > closing-bracket_ (privé) une chaîne représentant le crochet fermant du résultat formaté de la plage. Le crochet fermant par défaut est "]" .
( objet membre d'exposition uniquement* )

Fonctions membres

set_separator
définit un séparateur spécifié pour le résultat formaté de plage
(fonction membre publique)
set_brackets
définit des crochets d'ouverture et de fermeture spécifiés pour le résultat formaté de plage
(fonction membre publique)
underlying
retourne le formateur sous-jacent
(fonction membre publique)
parse
analyse le spécificateur de format comme spécifié par range-format-spec
(fonction membre publique)
format
écrit la sortie formatée de plage comme spécifié par range-format-spec
(fonction membre publique)

std::range_formatter:: set_separator

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

Affecte sep à separator_ .

std::range_formatter:: set_brackets

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

Attribue opening et closing à opening-bracket_ et closing-bracket_ , respectivement.

std::range_formatter:: underlying

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

Retourne underlying_ (le formateur sous-jacent).

std::range_formatter:: parse

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

Analyse les spécificateurs de format en tant que range-format-spec et stocke les spécificateurs analysés dans l'objet courant.

Appelle underlying_ . parse ( ctx ) pour analyser le format-spec dans le range-format-spec ou, si ce dernier n'est pas présent, un format-spec vide.

Si le range-type ou l'option n est présente, les valeurs de opening-bracket_ , closing-bracket_ , et separator_ sont modifiées selon les besoins.

Appelle underlying_ . set_debug_format ( ) si :

  • le range-type n'est ni s ni ?s ,
  • underlying_ . set_debug_format ( ) est une expression valide, et
  • il n'y a pas de range-underlying-spec .

Retourne un itérateur après la fin du 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 le range-type était soit s soit ?s , il écrit le std:: basic_string < CharT > ( std:: from_range , r ) formaté comme une chaîne ou une chaîne échappée, respectivement, dans ctx. out ( ) .

Sinon, il écrit les éléments suivants dans ctx. out ( ) comme spécifié par range-format-spec , dans l'ordre :

  • opening-bracket_ ,
  • pour chaque élément formatable e de la plage r :
  • le résultat de l'écriture de e via underlying_ , et
  • separator_ , sauf si e est le dernier élément de r , et
  • closing-bracket_ .

Retourne un itérateur après la fin de la plage de sortie.

Rapports de défauts

Les rapports de défauts modifiant le comportement suivants ont été appliqués rétroactivement aux normes C++ précédemment publiées.

DR Appliqué à Comportement publié Comportement corrigé
LWG 3892 C++23 le formatage des plages imbriquées était incorrect corrigé

Voir aussi

(C++20)
définit les règles de formatage pour un type donné
(modèle de classe)