Notes
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
La fonctionnalité de mise en forme composite .NET prend 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é à 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 génère une chaîne de résultat qui se compose du texte fixe d’origine mélangé avec la représentation sous forme de chaîne des objets de la liste.
Importante
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 Interpolation de chaîne (référence C#) et chaînes interpolées (référence Visual Basic).
Les méthodes suivantes prennent en charge la fonctionnalité de mise en forme composite :
- String.Format, qui retourne une chaîne de résultat mise en forme.
- StringBuilder.AppendFormat, qui ajoute une chaîne de résultat mise en forme à un StringBuilder objet.
- Certaines versions surchargées de la méthode Console.WriteLine, qui affichent une chaîne de résultat formatée dans la console.
- Certaines surcharges de la méthode TextWriter.WriteLine, qui écrivent la chaîne de résultat mise en forme dans un flux ou un fichier. Les classes dérivées de TextWriter, telles que StreamWriter et HtmlTextWriter, partagent également cette fonctionnalité.
- Debug.WriteLine(String, Object[]), qui génère un message mis en forme pour les écouteurs Trace.
- Les méthodes Trace.TraceError(String, Object[]), Trace.TraceInformation(String, Object[]) et Trace.TraceWarning(String, Object[]) qui génèrent des messages mis en forme pour les écouteurs Trace.
- La méthode TraceSource.TraceInformation(String, Object[]), qui écrit une méthode informative pour tracer les auditeurs.
Chaîne de format composite
Une chaîne de format composite et une liste d’objets sont utilisées comme arguments de méthodes qui prennent en charge la fonctionnalité de mise en forme composite. Une chaîne de format composite se compose de zéro ou plusieurs séquences de texte fixe mélangées avec un ou plusieurs éléments de format. Le texte fixe est une chaîne que vous choisissez, et chaque élément de format correspond à un objet ou à une structure encapsulée dans la liste. La représentation sous forme de chaîne de chaque objet remplace l’élément de format correspondant.
Considérez le fragment de code suivant Format :
string.Format("Name = {0}, hours = {1:hh}", "Fred", DateTime.Now);
String.Format("Name = {0}, hours = {1:hh}", "Fred", DateTime.Now)
Le texte fixe est Name =
et , hours =
. Les éléments de format sont {0}
, dont l’index de 0 correspond à l’objet name
et {1:hh}
, dont l’index de 1 correspond à l’objet DateTime.Now
.
Syntaxe des éléments de format
Chaque élément de format prend la forme suivante et se compose des composants suivants :
{index[,width][:formatString]}
Les accolades correspondantes ({
et }
) sont requises.
Composant d’index
Le composant obligatoire index
, également appelé spécificateur de paramètre, est un nombre commençant par 0 qui identifie un élément correspondant dans la liste des objets. Autrement dit, l’élément de format avec le spécificateur de paramètre 0
formate le premier objet de la liste. L'élément de format avec le spécificateur de paramètre 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és zéro à trois, pour représenter les nombres premiers inférieurs à 10 :
string primes = string.Format("Four prime numbers: {0}, {1}, {2}, {3}",
2, 3, 5, 7);
Console.WriteLine(primes);
// The example displays the following output:
// Four prime numbers: 2, 3, 5, 7
Dim primes As String = String.Format("Four prime numbers: {0}, {1}, {2}, {3}",
2, 3, 5, 7)
Console.WriteLine(primes)
'The example displays the following output
' Four prime numbers 2, 3, 5, 7
Plusieurs éléments de format peuvent faire référence au même élément dans la liste des objets en spécifiant 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é au moment de l’exécution si un paramètre spécifie un élément hors des limites de la liste d'objets.
Composant de largeur
Le composant facultatif width
est un entier signé indiquant la largeur de champ mise en forme par défaut. Si la valeur de width
est inférieure à la longueur de la chaîne mise en forme, width
est ignorée 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 width
elles sont positives et alignées à gauche si width
elles sont négatives. Si le remplissage est nécessaire, l’espace blanc est utilisé. La virgule est requise si width
est spécifié.
L’exemple suivant définit deux tableaux, un contenant les noms des employés et l’autre contenant les heures qu’ils ont travaillées sur deux semaines. La chaîne de format composite à gauche aligne 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 » formate les heures avec un chiffre décimal.
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 counter = 0; counter < names.Length; counter++)
Console.WriteLine("{0,-20} {1,5:N1}", names[counter], hours[counter]);
// 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
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}\n", "Name", "Hours")
For counter = 0 To names.Length - 1
Console.WriteLine("{0,-20} {1,5:N1}", names(counter), hours(counter))
Next
'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 format
Le composant facultatif formatString
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.
S’il 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 d'interface IFormattable et ICustomFormatter.
Type ou catégorie de type | Consultez |
---|---|
Types de date et d’heure (DateTime, DateTimeOffset) |
Chaînes au format date et 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érique 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. 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 fermante (}}
) pour afficher une accolade fermante (}
).
Les accolades d’échappement contenant un élément de format sont analysées différemment entre .NET et .NET Framework.
.FILET
Les accolades peuvent être placées dans une séquence d’échappement autour d’un élément de format. Par exemple, considérez l’élément de format {{{0:D}}}
, qui est destiné à afficher une accolade ouvrante, une valeur numérique mise en forme comme un nombre décimal et une accolade fermante. L’élément de format est 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
) est interprété comme spécificateur de format numérique standard décimal. - L’accolade suivante (
}
) est interprétée comme la fin de l’élément de format. - Les deux dernières accolades fermantes sont placées dans une séquence d’échappement et produisent une accolade fermante.
- Le résultat final affiché est la chaîne littérale.
{6324}
int value = 6324;
string output = string.Format("{{{0:D}}}", value);
Console.WriteLine(output);
// The example displays the following output:
// {6324}
Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}", value)
Console.WriteLine(output)
'The example displays the following output
' {6324}
.NET Framework
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}}}
, qui est destiné à afficher une accolade ouvrante, une valeur numérique mise en forme comme un nombre décimal et une accolade fermante. Toutefois, l’élément de format est 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. Étant donné que la chaîne résultante (D}
) n’est 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îneD}
littérale. - 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 à mettre en forme n’est pas affichée.
int value = 6324;
string output = string.Format("{{{0:D}}}",
value);
Console.WriteLine(output);
// The example displays the following output:
// {D}
Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}",
value)
Console.WriteLine(output)
'The example displays the following output:
' {D}
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 les éléments de format. Autrement dit, dans la première opération de mise en forme, affichez une accolade d’ouverture littérale. Dans l’opération suivante, affichez le résultat de l’élément de format et, dans l’opération finale, affichez une accolade fermante 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 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 format est convertie en chaîne comme suit :
Si la valeur à mettre en forme est
null
, une chaîne String.Empty vide est retournée.Si une ICustomFormatter implémentation est disponible, le runtime appelle sa Format méthode. Le runtime transmet la valeur de l’élément de format
formatString
(ounull
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 retournenull
, l’exécution passe à l’étape suivante. Sinon, le résultat de l'appel ICustomFormatter.Format est renvoyé.Si la valeur implémente l’interface IFormattable, la méthode ToString(String, IFormatProvider) de l’interface est appelée. La valeur
formatString
, s’il en existe une dans l’élément de mise en forme, est transmise à la méthode. Sinon,null
est transmis. L’argument IFormatProvider est déterminé comme suit :Pour une valeur numérique, si une méthode de mise en forme composite avec un argument non null IFormatProvider est appelée, le runtime demande un NumberFormatInfo objet à partir de sa IFormatProvider.GetFormat méthode. S’il ne peut pas en fournir un, si la valeur de l’argument est
null
, ou si la méthode de mise en forme composite n’a pas de IFormatProvider paramètre, l’objet NumberFormatInfo de la culture actuelle est utilisé.Pour une valeur de date et d’heure, si une méthode de mise en forme composite avec un argument non null IFormatProvider est appelée, le runtime demande un DateTimeFormatInfo objet à partir de sa IFormatProvider.GetFormat méthode. Dans les situations suivantes, l’objet DateTimeFormatInfo de la culture actuelle est utilisé à la place :
- La IFormatProvider.GetFormat méthode n’est pas en mesure de fournir un DateTimeFormatInfo objet.
- La valeur de l’argument est
null
. - La méthode de mise en forme composite n’a pas de IFormatProvider paramètre.
Pour les objets d’autres types, si une méthode de mise en forme composite est appelée avec un IFormatProvider argument, sa valeur est transmise directement à l’implémentation IFormattable.ToString . Sinon,
null
est passé à l’implémentation IFormattable.ToString.
La méthode sans
ToString
paramètre du type, qui remplace Object.ToString() ou hérite du comportement de sa classe de base, est appelée. Dans ce cas, la chaîne de format spécifiée par leformatString
composant dans l’élément de format, s’il est présent, est ignorée.
L’alignement est appliqué une fois les étapes précédentes effectuées.
Exemples de code
L’exemple suivant montre une chaîne créée à l’aide de la mise en forme composite et une autre créée à l’aide de la méthode d’un ToString
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 expose 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 forme de chaîne, tandis 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 formater la valeur de myNumber
à une valeur monétaire.
int myNumber = 100;
Console.WriteLine($"{myNumber:C}");
// The example displays the following output
// if en-US is the current culture:
// $100.00
Dim myNumber As Integer = 100
Console.WriteLine("{0:C}", myNumber)
'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 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 la largeur dans la mise en forme. Les arguments mis en forme sont placés entre les caractères de barre verticale (|
) pour mettre en évidence l’alignement obtenu.
string firstName = "Fred";
string lastName = "Opals";
int myNumber = 100;
string formatFirstName = string.Format("First Name = |{0,10}|", firstName);
string formatLastName = string.Format("Last Name = |{0,10}|", lastName);
string formatPrice = string.Format("Price = |{0,10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);
Console.WriteLine();
formatFirstName = string.Format("First Name = |{0,-10}|", firstName);
formatLastName = string.Format("Last Name = |{0,-10}|", lastName);
formatPrice = string.Format("Price = |{0,-10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
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 firstName As String = "Fred"
Dim lastName As String = "Opals"
Dim myNumber As Integer = 100
Dim formatFirstName As String = String.Format("First Name = |{0,10}|", firstName)
Dim formatLastName As String = String.Format("Last Name = |{0,10}|", lastName)
Dim formatPrice As String = String.Format("Price = |{0,10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)
Console.WriteLine()
formatFirstName = String.Format("First Name = |{0,-10}|", firstName)
formatLastName = String.Format("Last Name = |{0,-10}|", lastName)
formatPrice = String.Format("Price = |{0,-10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
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
- WriteLine
- String.Format
- Interpolation de chaîne (C#)
- Interpolation de chaîne (Visual Basic)
- Mise en forme des types
- Chaînes de format numériques standard
- Chaînes de format numérique personnalisées
- Chaînes de format de date et heure standard
- Chaînes de format de date et d’heure personnalisées
- Chaînes de format TimeSpan standard
- Chaînes de format TimeSpan personnalisées
- Chaînes de format d’énumération