Mise en forme composite

Article
08/10/2011

La fonctionnalité de mise en forme composite du .NET Framework utilise une liste d'objets et une chaîne de format composite comme entrée. Une chaîne de format composite se compose de texte fixe mélangé à des espaces réservés indexés, appelés éléments de format, qui correspondent aux objets de la liste. L'opération de mise en forme produit une chaîne résultante qui se compose du texte fixe d'origine mélangé à la représentation sous forme de chaîne des objets de la liste.

La fonctionnalité de mise en forme composite est prise en charge par des méthodes telles que Format, AppendFormat et certaines surcharges de WriteLine et TextWriter.WriteLine. La méthode String.Format produit une chaîne résultante mise en forme, la méthode AppendFormat ajoute une chaîne résultante mise en forme à un objet StringBuilder, les méthodes Console.WriteLine affichent la chaîne résultante mise en forme dans la console et la méthode the TextWriter.WriteLine écrit la chaîne résultante mise en forme dans un flux ou un fichier.

Chaîne de format composite

Une chaîne de format composite et une liste d'objets sont utilisées comme arguments des méthodes qui prennent en charge la fonctionnalité de mise en forme composite. Une chaîne de format composite est constituée de zéro, une ou plusieurs séquences de texte fixe mélangées à un ou plusieurs éléments de format. Le texte fixe correspond à toute chaîne que vous choisissez, et chaque élément de format correspond à un objet ou une structure boxed dans la liste. La fonctionnalité de mise en forme composite retourne une nouvelle chaîne résultante, dans laquelle chaque élément de format est remplacé par la représentation sous forme de chaîne de l'objet correspondant dans la liste.

Prenons le fragment de code Format suivant.

Dim myName As String = "Fred"
String.Format("Name = {0}, hours = {1:hh}", myName, DateTime.Now)

string myName = "Fred";
String.Format("Name = {0}, hours = {1:hh}", myName, DateTime.Now);

Le texte fixe est « Name = » et « , hours = ». Les éléments de format sont « {0} », dont l'index est 0, qui correspond à l'objet myName, et « {1:hh} », dont l'index est 1, qui correspond à l'objet DateTime.Now.

Syntaxe des éléments de format

Chaque élément de format prend la forme suivante et comprend les composants suivants :

{index[,alignment][:formatString]}

Les accolades correspondantes (« { » et « } ») sont nécessaires.

Composant d'index

Le composant obligatoire index, également appelé spécificateur de paramètre, est un nombre à partir de 0 qui permet d'identifier un élément correspondant dans la liste des objets. En d'autres termes, l'élément de format dont le spécificateur de format est 0 met en forme le premier objet de la liste, l'élément de format dont le spécificateur de paramètres est 1 met en forme le deuxième objet de la liste, etc.

Plusieurs éléments de format peuvent faire référence au même élément de la liste d'objets en indiquant le même spécificateur de paramètre. Par exemple, vous pouvez mettre en forme la même valeur numérique au format hexadécimal, scientifique et numérique en spécifiant une chaîne de format composite telle que : « {0:X} {0:E} {0:N} ».

Chaque élément de format peut faire référence à n'importe quel objet de la liste. Par exemple, si vous disposez de trois objets à mettre en forme, vous pouvez mettre en forme le deuxième, le premier et le troisième en spécifiant une chaîne de format composite telle que : « {1} {0} {2} ». Un objet qui n'est pas référencé par un élément de format est ignoré. Une exception runtime se produit si un spécificateur de paramètres désigne un élément situé en dehors des limites de la liste d'objets.

Composant d'alignement

Le composant facultatif alignment est un entier signé indiquant la largeur préférée du champ mis en forme. Si la valeur du composant alignment est inférieure à la longueur de la chaîne mise en forme, alignment est ignoré et la longueur de la chaîne mise en forme est utilisée comme largeur de champ. Les données mises en forme dans le champ sont alignées à droite si alignment est positif et à gauche si alignment est négatif. Si un remplissage est nécessaire, des espaces blancs sont utilisés. La virgule est requise si alignment est spécifié.

Composant de chaîne de format

Le composant formatString facultatif est une chaîne de format appropriée au type d'objet qui est mis en forme. Spécifiez une chaîne de format numérique standard ou personnalisée si l'objet correspondant est une valeur numérique, une chaîne de format de date et d'heure standard ou personnalisée si l'objet correspondant est un objet DateTime, ou une chaîne de format d'énumération si l'objet correspondant est une valeur d'énumération. Si formatString n'est pas spécifié, le spécificateur de format général (« G ») pour un type numérique, de date et d'heure ou d'énumération est utilisé. Le point est requis si formatString est spécifié.

Remarque
Pour obtenir la liste des chaînes de format numériques standard et personnalisées, consultez Chaînes de format numériques standard et Chaînes de format numériques personnalisées.Pour obtenir la liste des chaînes de format de date et d'heure standard, consultez Chaînes de format de date et d'heure standard et Chaînes de format de date et d'heure personnalisées.

Accolades d'échappement

Les accolades ouvrantes et fermantes sont interprétées comme le début et la fin d'un élément de format. Par conséquent, vous devez utiliser une séquence d'échappement pour afficher une accolade ouvrante ou fermante littérale. Spécifiez deux accolades ouvrantes (« {{ ») dans le texte fixe pour afficher une accolade ouvrante (« { ») ou deux accolades fermantes (« }} ») pour afficher une accolade fermante (« } »). Les accolades d'un élément de format sont interprétées séquentiellement dans l'ordre dans lequel elles sont rencontrées. L'interprétation des accolades imbriquées n'est pas prise en charge.

La façon dont les accolades d'échappement sont interprétées peut générer des résultats inattendus. Par exemple, considérez l'élément de format « {{{0:D}}} » destiné à afficher une accolade ouvrante, une valeur numérique mise en forme en tant que nombre décimal et une accolade fermante. Toutefois, l'élément de format est réellement interprété de la manière suivante :

Les deux premières accolades ouvrantes (« {{ ») font l'objet d'un échappement et produisent une accolade ouvrante.
Les trois caractères suivants (« {0: ») sont interprétés comme le début d'un élément de format.
Le caractère suivant (« D ») devrait être interprété comme le spécificateur de format numérique standard Decimal, mais les deux accolades d'échappement suivantes (« }} ») produisent une seule accolade. Comme la chaîne résultante (« D} ») n'est pas un spécificateur de format numérique standard, elle est interprétée comme une chaîne de mise en forme personnalisée qui sous-entend l'affichage de la chaîne littérale « D} ».
La dernière accolade (« } ») est interprétée comme la fin de l'élément de format.
Le résultat final affiché est la chaîne littérale, « {D} ». La valeur numérique qui devait être mise en forme n'est pas affichée.

Pour éviter une mauvaise interprétation des accolades d'échappement et des éléments de format, mettez en forme séparément les accolades et l'élément de format. Autrement dit, dans la première opération de formatage, affichez une accolade ouvrante littérale, dans l'opération suivante, affichez le résultat de l'élément de format, puis dans la dernière opération, affichez une accolade fermante littérale. L'exemple suivant illustre cette approche.

Dim value As Integer = 6324
Dim output As String = String.Format("{0}{1:D}{2}", _
                                     "{", value, "}")
Console.WriteLine(output)   
' The example displays the following output:
'       {6324}

int value = 6324;
string output = string.Format("{0}{1:D}{2}", 
                             "{", value, "}");
Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Ordre de traitement

Chaque valeur dans la liste de paramètres qui correspond à un élément de mise en forme peut être convertie en une chaîne en exécutant les étapes de la liste suivante. Si une condition présente dans l'une des trois premières étapes est remplie, la représentation sous forme de chaîne de la valeur est retournée dans cette étape et les étapes suivantes ne sont pas effectuées.

Si la valeur à mettre en forme est null, une chaîne vide ("") est retournée.
Si la méthode de mise en forme composite inclut un paramètre de type IFormatProvider qui implémente également l'interface ICustomFormatter, la valeur est passée à la méthode ICustomFormatter.Format.
Si la valeur implémente l'interface IFormattable, sa méthode IFormattable.ToString est appelée.
La méthode ToString du type, qui est soit substituée, soit héritée de la classe Object est appelée.

L'alignement est appliqué une fois les précédentes étapes effectuées.

Exemples de code

L'exemple suivant illustre une chaîne créée à l'aide de la mise en forme composite et une autre chaîne créée à l'aide de la méthode ToString d'un objet. Les deux types de mise en forme produisent des résultats équivalents.

Dim FormatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim FormatString2 As String = DateTime.Now.ToString("dddd MMMM")

string FormatString1 = String.Format("{0:dddd MMMM}", DateTime.Now);
string FormatString2 = DateTime.Now.ToString("dddd MMMM");

En supposant que le jour actuel soit un jeudi du mois de mai, la valeur des deux chaînes de l'exemple précédent est Thursday May dans la culture américaine.

Console.WriteLine présente les mêmes fonctionnalités que String.Format. La seule différence entre les deux méthodes est que String.Format retourne son résultat sous la forme d'une chaîne, alors que Console.WriteLine écrit le résultat dans le flux de sortie associé à l'objet Console. L'exemple suivant utilise la méthode Console.WriteLine pour mettre en forme la valeur de MyInt en une valeur monétaire.

Dim MyInt As Integer = 100
Console.WriteLine("{0:C}", MyInt)
' The example displays the following output
' if en-US is the current culture:
'        $100.00

int MyInt = 100;
Console.WriteLine("{0:C}", MyInt);
// The example displays the following output 
// if en-US is the current culture:
//        $100.00

L'exemple suivant illustre la mise en forme de plusieurs objets, y compris la mise en forme d'un objet de deux manières différentes.

Dim myName As String = "Fred"
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}", _
                  myName, DateTime.Now))
' Depending on the current time, the example displays output like the following:
'    Name = Fred, hours = 11, minutes = 30

string myName = "Fred";
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
      myName, DateTime.Now));
// Depending on the current time, the example displays output like the following:
//    Name = Fred, hours = 11, minutes = 30

L'exemple suivant illustre l'utilisation de l'alignement lors de la mise en forme. Les arguments mis en forme sont placés entre des barres verticales (« | ») pour mettre en évidence l'alignement en résultant.

Dim myFName As String = "Fred"
Dim myLName As String = "Opals"

Dim myInt As Integer = 100
Dim FormatFName As String = String.Format("First Name = |{0,10}|", myFName)
Dim FormatLName As String = String.Format("Last Name = |{0,10}|", myLName)
Dim FormatPrice As String = String.Format("Price = |{0,10:C}|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
Console.WriteLine(FormatPrice)
Console.WriteLine()

FormatFName = String.Format("First Name = |{0,-10}|", myFName)
FormatLName = String.Format("Last Name = |{0,-10}|", myLName)
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
Console.WriteLine(FormatPrice)
' The example displays the following output on a system whose current
' culture is en-US:
'          First Name = |      Fred|
'          Last Name = |     Opals|
'          Price = |   $100.00|
'
'          First Name = |Fred      |
'          Last Name = |Opals     |
'          Price = |$100.00   |

string myFName = "Fred";
string myLName = "Opals";
int myInt = 100;
string FormatFName = String.Format("First Name = |{0,10}|", myFName);
string FormatLName = String.Format("Last Name = |{0,10}|", myLName);
string FormatPrice = String.Format("Price = |{0,10:C}|", myInt); 
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);
Console.WriteLine();

FormatFName = String.Format("First Name = |{0,-10}|", myFName);
FormatLName = String.Format("Last Name = |{0,-10}|", myLName);
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt);
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);
// The example displays the following output on a system whose current
// culture is en-US:
//          First Name = |      Fred|
//          Last Name = |     Opals|
//          Price = |   $100.00|
//
//          First Name = |Fred      |
//          Last Name = |Opals     |
//          Price = |$100.00   |

Voir aussi

Partager via