Mise en forme composite

  • Article
  • 14 minutes de lecture

La fonctionnalité de mise en forme composite du .NET utilise une liste d’objets et une chaîne de format composite comme entrée. Une chaîne de format composite se compose d’un texte fixe mélangé avec des espaces réservés indexés, appelés éléments de format. Ces éléments de format 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.

Important

Au lieu d’utiliser des chaînes de format composite, vous pouvez utiliser des chaînes interpolées si la langue et sa version que vous utilisez les prennent en charge. Une chaîne interpolée contient des expressions interpolées. 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. Pour plus d’informations, consultez l’interpolation de chaîne (référence C#) et les chaînes interpolées (Référence Visual Basic).

La fonctionnalité de mise en forme composite est prise en charge par les méthodes suivantes :

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.

Tenez compte du fragment de code suivant Format :

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 = . Les éléments de format sont {0}, dont l’index 0 correspond à l’objet nameet {1:hh}, dont l’index de 1 correspond à l’objet DateTime.Now.

Syntaxe de l’élément de format

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

{index[,alignment][:formatString]}

Les accolades correspondantes ({ et }) sont requises.

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. Autrement dit, l’élément de format dont le spécificateur de paramètre est 0 met en forme le premier objet de la liste. Élément de format dont le spécificateur de paramètre est 1 met en forme le deuxième objet de la liste, et ainsi de suite. L’exemple suivant inclut quatre spécificateurs de paramètres, numéroté zéro à trois, pour représenter les nombres premiers inférieurs à 10 :

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. 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 l’illustre l’exemple suivant :

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. Par exemple, s’il existe trois objets, vous pouvez mettre en forme le deuxième, le premier et le troisième objet 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é. Un FormatException est levée au moment de l’exécution si un spécificateur de paramètre désigne un élément en dehors des limites de la liste des 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 de l’alignement est inférieure à la longueur de la chaîne mise en forme, l’alignement 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 alignées à gauche si alignment est négatif. Si un remplissage est nécessaire, des espaces blancs sont utilisés. La virgule est requise si l’alignement est spécifié.

L’exemple suivant définit deux tableaux, l’un contenant les noms des employés et l’autre contenant les heures qu’ils ont travaillées plus de deux semaines. La chaîne de format composite aligne à gauche les noms dans un champ de 20 caractères et aligne à droite leurs heures dans un champ de 5 caractères. La chaîne de format standard « N1 » met en forme les heures avec un chiffre fractionnel.

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

Format du composant de chaîne

Le composant formatString facultatif est une chaîne de format appropriée pour le type d’objet mis en forme. Vous pouvez spécifier les valeurs suivantes :

  • Chaîne de format numérique standard ou personnalisée si l’objet correspondant est une valeur numérique.
  • Chaîne de format de date et d’heure standard ou personnalisée si l’objet correspondant est un DateTime objet.
  • 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 obligatoire si formatString est spécifié.

Le tableau suivant répertorie les types ou catégories de types dans la bibliothèque de classes .NET qui prennent en charge un ensemble prédéfini de chaînes de format et fournit des liens vers les articles qui répertorient les chaînes de format prises en charge. La mise en forme de chaîne 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 prises en charge par un type défini par l’application.

Pour plus d’informations, consultez les articles et ICustomFormatter les articles d’interfaceIFormattable.

Type ou catégorie de type Consultez
Types de date et d'heure (DateTime, DateTimeOffset) Chaînes de format de date et d’heure standard

Chaînes de format de date et d’heure personnalisées
Types d'énumération (tous les types dérivés de System.Enum) Chaînes de format d’énumération
Types numériques (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64) Chaînes de format numériques standard

Chaînes de format numériques personnalisées
Guid Guid.ToString(String)
TimeSpan Chaînes de format TimeSpan standard

Chaînes de format TimeSpan 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. Pour afficher un accolades d’ouverture littérale ou une accolade fermante, vous devez utiliser une séquence d’échappement. Spécifiez deux accolades d’ouverture ({{) dans le texte fixe pour afficher une accolades ouvrantes ({), ou deux accolades fermante (}}) pour afficher une accolades fermante (}). Les accolades d’un élément de format sont interprétées de façon séquentielle dans l’ordre dans lequel ils sont rencontrés. 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 {{{0:D}}}de format, qui est destiné à afficher une accolades ouvrante, une valeur numérique mise en forme comme un nombre décimal et une accolades fermante. Toutefois, l’élément de format est interprété de la manière suivante :

  1. Les deux premiers accolades ({{) sont échappés et produisent une accolade ouvrante.
  2. Les trois caractères suivants ({0:) sont interprétés comme le début d’un élément de format.
  3. Le caractère suivant (D) serait interprété comme spécificateur de format numérique standard décimal, mais les deux accolades}} () suivantes produisent un seul accolades. Étant donné que la chaîne obtenue n’estD} pas un spécificateur de format numérique standard, la chaîne résultante est interprétée comme une chaîne de format personnalisée qui signifie afficher la chaîne D}littérale.
  4. Le dernier accolades (}) est interprété comme la fin de l’élément de format.
  5. Le résultat final affiché est la chaîne littérale. {D} La valeur numérique à mettre en forme n’est pas affichée.

Une façon d’écrire votre code pour éviter toute mauvaise interprétation des accolades et des éléments de mise en forme consiste à mettre en forme les accolades et les éléments de mise en forme séparément. Autrement dit, dans la première opération de format, affichez un accolades littéral ouvrant. Dans l’opération suivante, affichez le résultat de l’élément de format et, dans l’opération finale, affichez un accolades de fermeture littérale. L’exemple suivant illustre cette approche :

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 traitement

Si l’appel à la méthode de mise en forme composite inclut un IFormatProvider argument dont la valeur n’est pas null, le runtime appelle sa IFormatProvider.GetFormat méthode pour demander une ICustomFormatter implémentation. Si la méthode peut retourner une ICustomFormatter implémentation, elle est mise en cache pendant la durée de l’appel de la méthode de mise en forme composite.

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 :

  1. Si la valeur à mettre en forme est null, une chaîne vide String.Empty est retournée.

  2. Si une implémentation de ICustomFormatter est disponible, le runtime appelle sa méthode Format. Le runtime transmet la valeur de l’élément de formatString format (ou null s’il n’est pas présent) à la méthode. Le runtime transmet également l’implémentation IFormatProvider à la méthode. Si l’appel à la ICustomFormatter.Format méthode retourne null, l’exécution passe à l’étape suivante. Sinon, le résultat de l’appel ICustomFormatter.Format est retourné.

  3. Si la valeur implémente l'interface IFormattable, la méthode de l'interface ToString(String, IFormatProvider) est appelée. Si une valeur est présente dans l’élément de format, la valeur formatString est passée à la méthode. Sinon, null est passé. L'argument IFormatProvider est déterminé comme suit :

  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. Dans ce cas, la chaîne de format spécifiée par le composant dans l’élément formatString de format, s’il est présent, est ignoré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.

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 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 Console.WriteLine méthode pour mettre en forme la valeur d’une MyInt valeur monétaire :

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, notamment la mise en forme d’un objet de deux façons différentes :

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. Les arguments mis en forme sont placés entre des barres verticales (« | ») pour mettre en évidence l’alignement en résultant.

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 aussi