Mise en forme compositeComposite Formatting

La fonctionnalité de mise en forme composite du .NET utilise une liste d’objets et une chaîne de format composite comme entrée.The .NET composite formatting feature takes a list of objects and a composite format string as input. 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.A composite format string consists of fixed text intermixed with indexed placeholders, called format items, that correspond to the objects in the list. 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.The formatting operation yields a result string that consists of the original fixed text intermixed with the string representation of the objects in the list.

Important

Au lieu d’utiliser des chaînes de format composite, vous pouvez utiliser des chaînes interpolées si le langage et la version du langage que vous utilisez les prennent en charge.Instead of using composite format strings, you can use interpolated strings if the language and language version that you're using support them. Une chaîne interpolée est une chaîne contenant des expressions interpolées.An interpolated string is a string that contains interpolated expressions. Chaque expression interpolée est résolue avec la valeur de l’expression et incluse dans la chaîne du résultat quand la chaîne est affectée.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Pour plus d’informations, consultez Interpolation de chaîne (Informations de référence sur C#) et Chaînes interpolées (Informations de référence sur Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated strings (Visual Basic Reference).

La fonctionnalité de mise en forme composite est prise en charge par les méthodes suivantes :The composite formatting feature is supported by methods such as the following:

Chaîne de format compositeComposite Format String

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.A composite format string and object list are used as arguments of methods that support the composite formatting feature. 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.A composite format string consists of zero or more runs of fixed text intermixed with one or more format items. 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.The fixed text is any string that you choose, and each format item corresponds to an object or boxed structure in the list. 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.The composite formatting feature returns a new result string where each format item is replaced by the string representation of the corresponding object in the list.

Prenons le fragment de code Format suivant.Consider the following Format code fragment.

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

Le texte fixe est Name = et , hours =.The fixed text is "Name = " and ", hours = ". Les éléments de format sont {0}, dont l’index est 0, ce qui correspond à l’objet name, et {1:hh}, dont l’index est 1, ce qui correspond à l’objet DateTime.Now.The format items are "{0}", whose index is 0, which corresponds to the object name, and "{1:hh}", whose index is 1, which corresponds to the object DateTime.Now.

Syntaxe des éléments de formatFormat Item Syntax

Chaque élément de format prend la forme suivante et comprend les composants suivants :Each format item takes the following form and consists of the following components:

{ index[,alignment][:formatString]}{ index[,alignment][:formatString]}

Les accolades correspondantes (« { » et « } ») sont nécessaires.The matching braces ("{" and "}") are required.

Composant d'indexIndex Component

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.The mandatory index component, also called a parameter specifier, is a number starting from 0 that identifies a corresponding item in the list of objects. 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.That is, the format item whose parameter specifier is 0 formats the first object in the list, the format item whose parameter specifier is 1 formats the second object in the list, and so on. L’exemple suivant comprend quatre spécificateurs de paramètres, numérotés de 0 à 3, pour représenter les nombres premiers inférieurs à 10 :The following example includes four parameter specifiers, numbered zero through three, to represent prime numbers less than ten:

string primes;
primes = String.Format("Prime numbers less than 10: {0}, {1}, {2}, {3}",
                       2, 3, 5, 7 );
Console.WriteLine(primes);
// The example displays the following output:
//      Prime numbers less than 10: 2, 3, 5, 7
Dim primes As String
primes = String.Format("Prime numbers less than 10: {0}, {1}, {2}, {3}",
                       2, 3, 5, 7 )
Console.WriteLine(primes)
' The example displays the following output:
'      Prime numbers less than 10: 2, 3, 5, 7

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.Multiple format items can refer to the same element in the list of objects by specifying the same parameter specifier. 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 : « 0x{0:X} {0:E} {0:N} », comme le montre l’exemple suivant.For example, you can format the same numeric value in hexadecimal, scientific, and number format by specifying a composite format string such as : "0x{0:X} {0:E} {0:N}", as the following example shows.

string multiple = String.Format("0x{0:X} {0:E} {0:N}",
                                Int64.MaxValue);
Console.WriteLine(multiple);
// The example displays the following output:
//      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00
Dim multiple As String = String.Format("0x{0:X} {0:E} {0:N}",
                                       Int64.MaxValue)
Console.WriteLine(multiple)
' The example displays the following output:
'      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Chaque élément de format peut faire référence à n'importe quel objet de la liste.Each format item can refer to any object in the list. 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} ».For example, if there are three objects, you can format the second, first, and third object by specifying a composite format string like this: "{1} {0} {2}". Un objet qui n'est pas référencé par un élément de format est ignoré.An object that is not referenced by a format item is ignored. Une exception FormatException est levée à l'exécution si un spécificateur de paramètres désigne un élément situé en dehors des limites de la liste d'objets.A FormatException is thrown at runtime if a parameter specifier designates an item outside the bounds of the list of objects.

Composant d'alignementAlignment Component

Le composant facultatif alignment est un entier signé indiquant la largeur préférée du champ mis en forme.The optional alignment component is a signed integer indicating the preferred formatted field width. Si la valeur du composant alignment est inférieure à la longueur de la chaîne mise en forme, alignmentest ignoré et la longueur de la chaîne mise en forme est utilisée comme largeur de champ.If the value of alignment is less than the length of the formatted string, alignment is ignored and the length of the formatted string is used as the field width. Les données mises en forme dans le champ sont alignées à droite si alignment est positif et alignées à gauche si alignment est négatif.The formatted data in the field is right-aligned if alignment is positive and left-aligned if alignment is negative. Si un remplissage est nécessaire, des espaces blancs sont utilisés.If padding is necessary, white space is used. La virgule est obligatoire si alignment est spécifié.The comma is required if alignment is specified.

L'exemple suivant définit deux tableaux, l'un contenant les noms des employés et l'autre contenant les heures qu'ils ont prestées sur une période de deux semaines.The following example defines two arrays, one containing the names of employees and the other containing the hours they worked over a two-week period. La chaîne de format composite aligne les noms à gauche dans un champ de 20 caractères et aligne leurs heures à droite dans un champ de 5 caractères.The composite format string left-aligns the names in a 20-character field, and right-aligns their hours in a 5-character field. Notez que la chaîne de format standard "N1" est également utilisée pour mettre les heures sous la forme d'un nombre avec une décimale.Note that the "N1" standard format string is also used to format the hours with one fractional digit.

using System;

public class Example
{
   public static void Main()
   {
      string[] names = { "Adam", "Bridgette", "Carla", "Daniel",
                         "Ebenezer", "Francine", "George" };
      decimal[] hours = { 40, 6.667m, 40.39m, 82, 40.333m, 80,
                                 16.75m };

      Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours");
      for (int ctr = 0; ctr < names.Length; ctr++)
         Console.WriteLine("{0,-20} {1,5:N1}", names[ctr], hours[ctr]);

   }
}
// The example displays the following output:
//       Name                 Hours
//
//       Adam                  40.0
//       Bridgette              6.7
//       Carla                 40.4
//       Daniel                82.0
//       Ebenezer              40.3
//       Francine              80.0
//       George                16.8
Module Example
   Public Sub Main()
      Dim names() As String = { "Adam", "Bridgette", "Carla", "Daniel",
                                "Ebenezer", "Francine", "George" }
      Dim hours() As Decimal = { 40, 6.667d, 40.39d, 82, 40.333d, 80,
                                 16.75d }

      Console.WriteLine("{0,-20} {1,5}", "Name", "Hours")
      Console.WriteLine()
      For ctr As Integer = 0 To names.Length - 1
         Console.WriteLine("{0,-20} {1,5:N1}", names(ctr), hours(ctr))
      Next
   End Sub
End Module
' The example displays the following output:
'       Name                 Hours
'
'       Adam                  40.0
'       Bridgette              6.7
'       Carla                 40.4
'       Daniel                82.0
'       Ebenezer              40.3
'       Francine              80.0
'       George                16.8

Composant de chaîne de formatFormat String Component

Le composant facultatif formatString est une chaîne de format appropriée pour le type d’objet mis en forme.The optional formatString component is a format string that is appropriate for the type of object being formatted. 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.Specify a standard or custom numeric format string if the corresponding object is a numeric value, a standard or custom date and time format string if the corresponding object is a DateTime object, or an enumeration format string if the corresponding object is an enumeration value. 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é.If formatString is not specified, the general ("G") format specifier for a numeric, date and time, or enumeration type is used. Le point est obligatoire si formatString est spécifié.The colon is required if formatString is specified.

Le tableau suivant répertorie les types ou les catégories de types dans la bibliothèque de classes .NET Framework qui prennent en charge un ensemble prédéfini de chaînes de format, et fournit des liens vers les rubriques qui répertorient les chaînes de format prises en charge.The following table lists types or categories of types in the .NET Framework class library that support a predefined set of format strings, and provides links to the topics that list the supported format strings. Notez que la mise en forme de chaînes est un mécanisme extensible qui permet de définir de nouvelles chaînes de format pour tous les types existants et de définir un ensemble de chaînes de format pris en charge par un type défini par l'application.Note that string formatting is an extensible mechanism that makes it possible to define new format strings for all existing types as well as to define a set of format strings supported by an application-defined type. Pour plus d'informations, consultez les rubriques sur l'interface IFormattable et ICustomFormatter.For more information, see the IFormattable and ICustomFormatter interface topics.

Type ou catégorie de typeType or type category VoirSee
Types de date et d'heure (DateTime, DateTimeOffset)Date and time types (DateTime, DateTimeOffset) Standard Date and Time Format StringsStandard Date and Time Format Strings

Custom Date and Time Format StringsCustom Date and Time Format Strings
Types d'énumération (tous les types dérivés de System.Enum)Enumeration types (all types derived from System.Enum) Enumeration Format StringsEnumeration Format Strings
Types numériques (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64)Numeric types (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64) Standard Numeric Format StringsStandard Numeric Format Strings

Custom Numeric Format StringsCustom Numeric Format Strings
Guid Guid.ToString(String)
TimeSpan Chaînes de format TimeSpan standardStandard TimeSpan Format Strings

Chaînes de format TimeSpan personnaliséesCustom TimeSpan Format Strings

Accolades d'échappementEscaping Braces

Les accolades ouvrantes et fermantes sont interprétées comme le début et la fin d'un élément de format.Opening and closing braces are interpreted as starting and ending a format item. Par conséquent, vous devez utiliser une séquence d'échappement pour afficher une accolade ouvrante ou fermante littérale.Consequently, you must use an escape sequence to display a literal opening brace or closing brace. Spécifiez deux accolades ouvrantes (« {{ ») dans le texte fixe pour afficher une accolade ouvrante (« { ») ou deux accolades fermantes (« }} ») pour afficher une accolade fermante (« } »).Specify two opening braces ("{{") in the fixed text to display one opening brace ("{"), or two closing braces ("}}") to display one closing brace ("}"). Les accolades d'un élément de format sont interprétées séquentiellement dans l'ordre dans lequel elles sont rencontrées.Braces in a format item are interpreted sequentially in the order they are encountered. L'interprétation des accolades imbriquées n'est pas prise en charge.Interpreting nested braces is not supported.

La façon dont les accolades d'échappement sont interprétées peut générer des résultats inattendus.The way escaped braces are interpreted can lead to unexpected results. 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.For example, consider the format item "{{{0:D}}}", which is intended to display an opening brace, a numeric value formatted as a decimal number, and a closing brace. Toutefois, l'élément de format est réellement interprété de la manière suivante :However, the format item is actually interpreted in the following manner:

  1. Les deux premières accolades ouvrantes (« {{ ») font l'objet d'un échappement et produisent une accolade ouvrante.The first two opening braces ("{{") are escaped and yield one opening brace.

  2. Les trois caractères suivants (« {0: ») sont interprétés comme le début d'un élément de format.The next three characters ("{0:") are interpreted as the start of a format item.

  3. 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.The next character ("D") would be interpreted as the Decimal standard numeric format specifier, but the next two escaped braces ("}}") yield a single brace. 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} ».Because the resulting string ("D}") is not a standard numeric format specifier, the resulting string is interpreted as a custom format string that means display the literal string "D}".

  4. La dernière accolade (« } ») est interprétée comme la fin de l'élément de format.The last brace ("}") is interpreted as the end of the format item.

  5. Le résultat final affiché est la chaîne littérale, « {D} ».The final result that is displayed is the literal string, "{D}". La valeur numérique qui devait être mise en forme n'est pas affichée.The numeric value that was to be formatted is not displayed.

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.One way to write your code to avoid misinterpreting escaped braces and format items is to format the braces and format item separately. 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.That is, in the first format operation display a literal opening brace, in the next operation display the result of the format item, then in the final operation display a literal closing brace. L'exemple suivant illustre cette approche.The following example illustrates this approach.

int value = 6324;
string output = string.Format("{0}{1:D}{2}", 
                             "{", value, "}");
Console.WriteLine(output);
// The example displays the following output:
//       {6324}                            
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}

Ordre de traitementProcessing Order

Si l'appel à la méthode de mise en forme composite comprend un argument IFormatProvider dont la valeur n'est pas null, le runtime appelle sa méthode IFormatProvider.GetFormat pour demander une implémentation de ICustomFormatter.If the call to the composite formatting method includes an IFormatProvider argument whose value is not null, the runtime calls its IFormatProvider.GetFormat method to request an ICustomFormatter implementation. Si la méthode est en mesure de retourner une implémentation de ICustomFormatter, elle est mise en cache durant l’appel de la méthode de mise en forme composite.If the method is able to return an ICustomFormatter implementation, it's cached for the duration of the call of the composite formatting method.

Chaque valeur de la liste de paramètres qui correspond à un élément de mise en forme est convertie en une chaîne de la manière suivante :Each value in the parameter list that corresponds to a format item is converted to a string as follows:

  1. Si la valeur à mettre en forme est null, une chaîne vide String.Empty est retournée.If the value to be formatted is null, an empty string String.Empty is returned.

  2. Si une implémentation de ICustomFormatter est disponible, le runtime appelle sa méthode Format.If an ICustomFormatter implementation is available, the runtime calls its Format method. Il passe à la méthode la valeur formatString de l’élément de mise en forme, s’il en existe une, ou null si ce n’est pas le cas, ainsi que l’implémentation de IFormatProvider.It passes the method the format item's formatString value, if one is present, or null if it's not, along with the IFormatProvider implementation. Si l’appel à la méthode ICustomFormatter.Format retourne null, l’exécution se poursuit à l’étape suivante. Sinon, le résultat de l’appel à ICustomFormatter.Format est retourné.If the call to the ICustomFormatter.Format method returns null, execution proceeds to the next step; otherwise, the result of the ICustomFormatter.Format call is returned.

  3. Si la valeur implémente l'interface IFormattable, la méthode de l'interface ToString(String, IFormatProvider) est appelée.If the value implements the IFormattable interface, the interface's ToString(String, IFormatProvider) method is called. La valeur formatString, s’il en existe une dans l’élément de mise en forme, est passée à la méthode, ou bien la valeur null si ce n’est pas le cas.The method is passed the formatString value, if one is present in the format item, or null if it's not. L'argument IFormatProvider est déterminé comme suit :The IFormatProvider argument is determined as follows:

  4. La méthode ToString sans paramètre du type, qui remplace Object.ToString() ou hérite du comportement de la classe de base, est appelée.The type's parameterless ToString method, which either overrides Object.ToString() or inherits the behavior of its base class, is called. Dans ce cas, la chaîne de format spécifiée par le composant formatString dans l’élément de mise en forme, si elle est présente, est ignorée.In this case, the format string specified by the formatString component in the format item, if it's present, is ignored.

L'alignement est appliqué une fois les précédentes étapes effectuées.Alignment is applied after the preceding steps have been performed.

Exemples de codeCode Examples

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.The following example shows one string created using composite formatting and another created using an object's ToString method. Les deux types de mise en forme produisent des résultats équivalents.Both types of formatting produce equivalent results.

string FormatString1 = String.Format("{0:dddd MMMM}", DateTime.Now);
string FormatString2 = DateTime.Now.ToString("dddd MMMM");
Dim FormatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim FormatString2 As String = 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 Anglais (États-Unis).Assuming that the current day is a Thursday in May, the value of both strings in the preceding example is Thursday May in the U.S. English culture.

Console.WriteLine présente les mêmes fonctionnalités que String.Format.Console.WriteLine exposes the same functionality as 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.The only difference between the two methods is that String.Format returns its result as a string, while Console.WriteLine writes the result to the output stream associated with the Console object. L'exemple suivant utilise la méthode Console.WriteLine pour mettre en forme la valeur de MyInt en une valeur monétaire.The following example uses the Console.WriteLine method to format the value of MyInt to a currency value.

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

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.The following example demonstrates formatting multiple objects, including formatting one object two different ways.

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

L'exemple suivant illustre l'utilisation de l'alignement lors de la mise en forme.The following example demonstrates the use of alignment in formatting. Les arguments mis en forme sont placés entre des barres verticales (|) pour mettre en évidence l’alignement en résultant.The arguments that are formatted are placed between vertical bar characters (|) to highlight the resulting alignment.

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

Voir aussiSee also