Mise en forme des types
La mise en forme est le processus de conversion d'une instance d'une classe, d'une structure ou d'une valeur d'énumération en représentation sous forme de chaîne, généralement pour exposer la chaîne obtenue aux utilisateurs ou pour qu'elle soit désérialisée afin de restaurer le type de données d'origine. Cette conversion peut présenter plusieurs difficultés :
La manière dont les valeurs sont stockées en interne ne reflète pas nécessairement celle dont les utilisateurs souhaitent les voir. Par exemple, un numéro de téléphone peut être stocké sous la forme 8009999999, ce qui n'est pas convivial. Il devrait plutôt être affiché sous la forme 800-999-9999.
La conversion d'un objet en sa représentation sous forme de chaîne n'est pas toujours intuitive. Par exemple, il n'est pas évident de savoir comment doit s'afficher la représentation sous forme de chaîne d'un objet Temperature ou Person.
Les valeurs requièrent souvent une mise en forme qui tient compte de la culture. Par exemple, dans une application qui utilise des nombre pour refléter des valeurs monétaires, les chaînes numériques doivent inclure le symbole monétaire, le séparateur de groupes (qui, dans la plupart des cultures, est le séparateur des milliers) et le symbole décimal qui correspondent à la culture actuelle.
Une application peut avoir à afficher la même valeur de différentes manières. Par exemple, une application peut représenter un membre d'énumération en affichant une représentation sous forme de chaîne de son nom ou en affichant sa valeur sous-jacente.
.gif "Remarque") Remarque |
|---|
La mise en forme convertit la valeur d'un type en une représentation sous forme de chaîne.L'analyse est l'opération inverse de la mise en forme.Une opération d'analyse crée une instance d'un type de données à partir de sa représentation sous forme de chaîne.Pour plus d'informations sur la conversion de chaînes en d'autres types de données, consultez Analyse de chaînes. |
Le .NET Framework assure une prise en charge évoluée de la mise en forme qui permet aux développeurs surmonter ces difficultés.
Cette vue d'ensemble contient les sections suivantes :
Mise en forme dans le .NET Framework
Mise en forme par défaut à l'aide de la méthode ToString
Substitution de la méthode ToString
Méthode ToString et chaînes de format
Fournisseurs de format et interface IFormatProvider
Interface IFormattable
Mise en forme composite
Mise en forme personnalisée avec ICustomFormatter
Rubriques connexes
Référence
Mise en forme dans le .NET Framework
Le mécanisme de base de la mise en forme est l'implémentation par défaut de la méthode Object.ToString, décrite ultérieurement dans la section Mise en forme par défaut à l'aide de la méthode ToString, plus loin dans cette rubrique. Toutefois, le .NET Framework propose différentes manières de modifier et d'étendre sa prise en charge par défaut de la mise en forme. Notamment :
Substitution de la méthode Object.ToString pour définir une représentation sous forme de chaîne personnalisée de la valeur d'un objet. Pour plus d'informations, consultez la section Substitution de la méthode ToString, plus loin dans cette rubrique.
Définition de spécificateurs de format qui permettent à la représentation sous forme de chaîne de la valeur d'un objet de prendre plusieurs formes. Par exemple, dans l'instruction suivante, le spécificateur de format "X" convertit un entier en la représentation sous forme de chaîne d'une valeur hexadécimale.
Console.WriteLine(integerValue.ToString("X")) ' Displays EB98.Console.WriteLine(integerValue.ToString("X")); // Displays EB98.Pour plus d'informations sur les spécificateurs de format, consultez la section Méthode ToString et chaînes de format.
Utilisation de fournisseurs de format pour tirer parti des conventions de mise en forme d'une culture spécifique. Par exemple, l'instruction suivante affiche une valeur monétaire en utilisant les conventions de mise en forme de la culture en-US.
Console.WriteLine(cost.ToString("C", New System.Globalization.CultureInfo("en-US"))) ' The example displays the following output: ' $1,632.54Console.WriteLine(cost.ToString("C", new System.Globalization.CultureInfo("en-US"))); // The example displays the following output: // $1,632.54Pour plus d'informations sur la mise en forme avec des fournisseurs de format, consultez la section Fournisseurs de format et interface IFormatProvider.
Implémentation de l'interface IFormattable pour prendre en charge la conversion de chaînes avec la classe Convert et la mise en forme composite. Pour plus d'informations, consultez la section Interface IFormattable.
Utilisation de la mise en forme composite pour incorporer la représentation sous forme de chaîne d'une valeur dans une chaîne plus grande. Pour plus d'informations, consultez la section Mise en forme composite.
Implémentation d'ICustomFormatter et d'IFormatProvider pour fournir une solution de mise en forme personnalisée et complète. Pour plus d'informations, consultez la section Mise en forme personnalisée avec ICustomFormatter.
Les sections suivantes étudient ces méthodes de conversion d'un objet en sa représentation sous forme de chaîne.
Retour au début
Mise en forme par défaut à l'aide de la méthode ToString
Chaque type qui est dérivé d'System.Object hérite automatiquement d'une méthode ToString sans paramètre, laquelle retourne le nom du type par défaut. L'exemple suivant illustre la méthode ToString par défaut. Il définit une classe nommée Automobile qui n'a pas d'implémentation. Lorsque cette classe est instanciée et que sa méthode ToString est appelée, elle affiche son nom de type.
Public Class Automobile
' No implementation. All members are inherited from Object.
End Class
Module Example
Public Sub Main()
Dim firstAuto As New Automobile()
Console.WriteLine(firstAuto)
End Sub
End Module
' The example displays the following output:
' Automobile
using System;
public class Automobile
{
// No implementation. All members are inherited from Object.
}
public class Example
{
public static void Main()
{
Automobile firstAuto = new Automobile();
Console.WriteLine(firstAuto);
}
}
// The example displays the following output:
// Automobile
Étant donné que tous les types autres que les interfaces sont dérivés de Object, ces fonctionnalités sont fournies automatiquement à vos classes ou structures personnalisées. Toutefois, les fonctionnalités offertes par la méthode ToString par défaut sont limitées : Bien qu'elle identifie le type, elle ne fournit aucune information relative à une instance du type. Pour fournir une représentation sous forme de chaîne d'un objet qui donne des informations sur cet objet, vous devez substituer la méthode ToString.
| Remarque |
|---|
Les structures héritent de ValueType, qui, à son tour, est dérivé d'Object.Bien que ValueType substitue Object.ToString, son implémentation est identique. |
Retour au début
Substitution de la méthode ToString
L'utilité de l'affichage du nom d'un type est souvent limitée et ne permet pas aux consommateurs de vos types de différencier une instance d'une autre. Toutefois, vous pouvez substituer la méthode ToString pour fournir une représentation plus utile de la valeur d'un objet. L'exemple suivant définit un objet Temperature et substitue sa méthode ToString pour afficher la température en degrés Celsius.
Public Class Temperature
Private temp As Decimal
Public Sub New(temperature As Decimal)
Me.temp = temperature
End Sub
Public Overrides Function ToString() As String
Return Me.temp.ToString("N1") + "°C"
End Function
End Class
Module Example
Public Sub Main()
Dim currentTemperature As New Temperature(23.6d)
Console.WriteLine("The current temperature is {0}.", currentTemperature)
End Sub
End Module
' The example displays the following output:
' The current temperature is 23.6°C.
using System;
public class Temperature
{
private decimal temp;
public Temperature(decimal temperature)
{
this.temp = temperature;
}
public override string ToString()
{
return this.temp.ToString("N1") + "°C";
}
}
public class Example
{
public static void Main()
{
Temperature currentTemperature = new Temperature(23.6m);
Console.WriteLine("The current temperature is {0}.", currentTemperature);
}
}
// The example displays the following output:
// The current temperature is 23.6°C.
Dans le .NET Framework, la méthode ToString de chaque type valeur primitif a été substituée de façon à afficher la valeur de l'objet au lieu de son nom. Le tableau suivant montre la substitution pour chaque type primitif. Notez que la plupart des méthodes substituées appellent une autre surcharge de la méthode ToString et lui passent le spécificateur de format "G", qui définit le format général pour son type, ainsi qu'un objet IFormatProvider qui représente la culture actuelle.
Type |
Substitution de ToString |
|---|---|
Retourne Boolean.TrueString ou Boolean.FalseString. |
|
Appelle Byte.ToString("G", NumberFormatInfo.CurrentInfo) afin de mettre en forme la valeur Byte pour la culture actuelle. |
|
Retourne le caractère sous forme de chaîne. |
|
Appelle DateTime.ToString("G", DatetimeFormatInfo.CurrentInfo) afin de mettre en forme la valeur de date et d'heure pour la culture actuelle. |
|
Appelle Decimal.ToString("G", NumberFormatInfo.CurrentInfo) afin de mettre en forme la valeur Decimal pour la culture actuelle. |
|
Appelle Double.ToString("G", NumberFormatInfo.CurrentInfo) afin de mettre en forme la valeur Double pour la culture actuelle. |
|
Appelle Int16.ToString("G", NumberFormatInfo.CurrentInfo) afin de mettre en forme la valeur Int16 pour la culture actuelle. |
|
Appelle Int32.ToString("G", NumberFormatInfo.CurrentInfo) afin de mettre en forme la valeur Int32 pour la culture actuelle. |
|
Appelle Int64.ToString("G", NumberFormatInfo.CurrentInfo) afin de mettre en forme la valeur Int64 pour la culture actuelle. |
|
Appelle SByte.ToString("G", NumberFormatInfo.CurrentInfo) afin de mettre en forme la valeur SByte pour la culture actuelle. |
|
Appelle Single.ToString("G", NumberFormatInfo.CurrentInfo) afin de mettre en forme la valeur Single pour la culture actuelle. |
|
Appelle UInt16.ToString("G", NumberFormatInfo.CurrentInfo) afin de mettre en forme la valeur UInt16 pour la culture actuelle. |
|
Appelle UInt32.ToString("G", NumberFormatInfo.CurrentInfo) afin de mettre en forme la valeur UInt32 pour la culture actuelle. |
|
Appelle UInt64.ToString("G", NumberFormatInfo.CurrentInfo) afin de mettre en forme la valeur UInt64 pour la culture actuelle. |
Retour au début
Méthode ToString et chaînes de format
Le recours à la méthode ToString ou la substitution de ToString ne valent que lorsqu'un objet a une seule représentation sous forme de chaîne possible. Toutefois, la valeur d'un objet a souvent plusieurs représentations. Par exemple, une température peut être exprimée en degrés Fahrenheit, Celsius ou Kelvin. De même, la valeur entière 10 peut être représentée de plusieurs façons, dont 10, 10,0, 1,0e01 ou $10,00.
Pour permettre à une même valeur d'avoir plusieurs représentations sous forme de chaîne, le .NET Framework utilise des chaînes de format. Une chaîne de format est une chaîne qui contient un ou plusieurs spécificateurs de format prédéfinis, constitués d'un ou de plusieurs caractères servant à définir la manière dont la méthode ToString doit mettre en forme sa sortie. La chaîne de format est ensuite passée en tant que paramètre à la méthode ToString de l'objet et détermine la manière dont la représentation sous forme de chaîne de la valeur de cet objet doit apparaître.
Dans le .NET Framework, tous les types numériques, types de date et d'heure et types énumération prennent en charge un jeu prédéfini de spécificateurs de format. Vous pouvez aussi utiliser des chaînes de format pour définir plusieurs représentations sous forme de chaîne de vos types de données définis par l'application.
Chaînes de format standard
Une chaîne de format standard comprend un spécificateur de format unique, qui est un caractère alphabétique définissant la représentation sous forme de chaîne de l'objet auquel il s'applique, ainsi qu'un spécificateur de précision facultatif qui affecte le nombre de chiffres affichés dans la chaîne de résultat. Si le spécificateur de précision est omis ou n'est pas pris en charge, un spécificateur de format standard équivaut à une chaîne de format standard.
Le .NET Framework définit un jeu de spécificateurs de format standard pour tous les types numériques, types de date et d'heure et types énumération. Par exemple, chacune de ces catégories prend en charge un spécificateur de format standard "G", lequel définit une représentation sous forme de chaîne générale d'une valeur de ce type.
Les chaînes de format standard pour les types énumération contrôlent directement la représentation sous forme de chaîne d'une valeur. Les chaînes de format passées à la méthode ToString d'une valeur d'énumération déterminent si la valeur est affichée en utilisant son nom de chaîne (spécificateurs de format "G" et "F"), sa valeur intégrale sous-jacente (spécificateur de format "D") ou sa valeur hexadécimale (spécificateur de format "X"). L'exemple suivant illustre l'utilisation de chaînes de format standard pour mettre en forme une valeur d'énumération DayOfWeek.
Dim thisDay As DayOfWeek = DayOfWeek.Monday
Dim formatStrings() As String = {"G", "F", "D", "X"}
For Each formatString As String In formatStrings
Console.WriteLine(thisDay.ToString(formatString))
Next
' The example displays the following output:
' Monday
' Monday
' 1
' 00000001
DayOfWeek thisDay = DayOfWeek.Monday;
string[] formatStrings = {"G", "F", "D", "X"};
foreach (string formatString in formatStrings)
Console.WriteLine(thisDay.ToString(formatString));
// The example displays the following output:
// Monday
// Monday
// 1
// 00000001
Pour plus d'informations sur les chaînes de format d'énumération, consultez Chaînes de format d'énumération.
Les chaînes de format standard pour les types numériques définissent généralement une chaîne de résultat dont l'apparence précise est contrôlée par une ou plusieurs valeurs de propriété. Par exemple, le spécificateur de format "C" met en forme un nombre en tant que valeur monétaire. Lorsque vous appelez la méthode ToString avec, comme seul paramètre, le spécificateur de format "C", les valeurs des propriétés suivantes de l'objet NumberFormatInfo de la culture actuelle sont utilisées pour définir la représentation sous forme de chaîne de la valeur numérique :
Propriété CurrencySymbol, qui spécifie le symbole monétaire de la culture actuelle.
Propriété CurrencyNegativePattern ou CurrencyPositivePattern, qui retourne un entier déterminant :
la position du symbole monétaire ;
si les valeurs négatives sont indiquées par un signe négatif devant, par un signe négatif derrière ou par des parenthèses ;
si un espace apparaît entre la valeur numérique et le symbole monétaire.
Propriété CurrencyDecimalDigits, qui définit le nombre de chiffres fractionnaires dans la chaîne de résultat.
Propriété CurrencyDecimalSeparator, qui définit le symbole de séparateur décimal dans la chaîne de résultat.
Propriété CurrencyGroupSeparator, qui définit le symbole du séparateur de groupes.
Propriété CurrencyGroupSizes, qui définit le nombre de chiffres de chaque groupe situé à gauche du séparateur décimal.
Propriété NegativeSign, qui détermine le signe négatif utilisé dans la chaîne de résultat si les parenthèses ne sont pas utilisées pour indiquer des valeurs négatives.
De plus, les chaînes de format numériques peuvent inclure un spécificateur de précision. La signification de ce spécificateur dépend de la chaîne de format avec laquelle il est utilisé, mais il indique généralement le nombre total de chiffres ou le nombre de chiffres fractionnaires qui doivent s'afficher dans la chaîne de résultat. Par exemple, le code suivant utilise la chaîne numérique standard "X4" et un spécificateur de précision pour créer une valeur de chaîne qui comprend quatre chiffres hexadécimaux.
Dim byteValues() As Byte = { 12, 163, 255 }
For Each byteValue As Byte In byteValues
Console.WriteLine(byteValue.ToString("X4"))
Next
' The example displays the following output:
' 000C
' 00A3
' 00FF
byte[] byteValues = { 12, 163, 255 };
foreach (byte byteValue in byteValues)
Console.WriteLine(byteValue.ToString("X4"));
// The example displays the following output:
// 000C
// 00A3
// 00FF
Pour plus d'informations sur les chaînes de format numériques standard, consultez Chaînes de format numériques standard.
Les chaînes de format standard pour les valeurs de date et d'heure sont des alias de chaînes de format personnalisées stockées par une propriété DateTimeFormatInfo particulière. Par exemple, appeler la méthode ToString d'une valeur de date et d'heure avec le spécificateur de format "D" affiche la date et l'heure en utilisant la chaîne de format personnalisée stockée dans la propriété DateTimeFormatInfo.LongDatePattern de la culture actuelle. (Pour plus d'informations sur les chaînes de format personnalisées, consultez la section suivante.) L'exemple suivant illustre cette relation.
Imports System.Globalization
Module Example
Public Sub Main()
Dim date1 As Date = #6/30/2009#
Console.WriteLine("D Format Specifier: {0:D}", date1)
Dim longPattern As String = CultureInfo.CurrentCulture.DateTimeFormat.LongDatePattern
Console.WriteLine("'{0}' custom format string: {1}", _
longPattern, date1.ToString(longPattern))
End Sub
End Module
' The example displays the following output when run on a system whose
' current culture is en-US:
' D Format Specifier: Tuesday, June 30, 2009
' 'dddd, MMMM dd, yyyy' custom format string: Tuesday, June 30, 2009
using System;
using System.Globalization;
public class Example
{
public static void Main()
{
DateTime date1 = new DateTime(2009, 6, 30);
Console.WriteLine("D Format Specifier: {0:D}", date1);
string longPattern = CultureInfo.CurrentCulture.DateTimeFormat.LongDatePattern;
Console.WriteLine("'{0}' custom format string: {1}",
longPattern, date1.ToString(longPattern));
}
}
// The example displays the following output when run on a system whose
// current culture is en-US:
// D Format Specifier: Tuesday, June 30, 2009
// 'dddd, MMMM dd, yyyy' custom format string: Tuesday, June 30, 2009
Pour plus d'informations sur les chaînes de format de date et d'heure standard, consultez Chaînes de format de date et d'heure standard.
Vous pouvez aussi utiliser des chaînes de format standard pour définir la représentation sous forme de chaîne produite par la méthode ToString(String) d'un objet défini par l'application. Vous pouvez définir les spécificateurs de format standard spécifiques que votre objet prend en charge, et déterminer s'ils respectent la casse. Votre implémentation de la méthode ToString(String) doit prendre en charge les éléments suivants :
Spécificateur de format "G" qui représente un format habituel ou commun de l'objet. La surcharge sans paramètre de la méthode ToString de votre objet doit appeler sa surcharge ToString(String) et lui passer la chaîne de format standard "G".
Prise en charge d'un spécificateur de format qui est égal à une référence null (Nothing en Visual Basic). Un spécificateur de format qui est égal à une référence null doit être considéré comme équivalent au spécificateur de format "G".
Par exemple, une classe Temperature peut stocker en interne la température en degrés Celsius et utiliser des spécificateurs de format pour représenter la valeur de l'objet Temperature en degrés Celsius, Fahrenheit et Kelvin. L'exemple suivant illustre cette situation.
Public Class Temperature
Private m_Temp As Decimal
Public Sub New(temperature As Decimal)
Me.m_Temp = temperature
End Sub
Public ReadOnly Property Celsius() As Decimal
Get
Return Me.m_Temp
End Get
End Property
Public ReadOnly Property Kelvin() As Decimal
Get
Return Me.m_Temp + 273.15d
End Get
End Property
Public ReadOnly Property Fahrenheit() As Decimal
Get
Return Math.Round(CDec(Me.m_Temp * 9 / 5 + 32), 2)
End Get
End Property
Public Overrides Function ToString() As String
Return Me.ToString("C")
End Function
Public Overloads Function ToString(format As String) As String
' Handle null or empty string.
If String.IsNullOrEmpty(format) Then format = "C"
' Remove spaces and convert to uppercase.
format = format.Trim().ToUpperInvariant()
' Convert temperature to Fahrenheit and return string.
Select Case format
Case "F"
Return Me.Fahrenheit.ToString("N2") & " °F"
' Convert temperature to Kelvin and return string.
Case "K"
Return Me.Kelvin.ToString("N2") & " K"
' Return temperature in Celsius.
Case "C"
Return Me.Celsius.ToString("N2") & " °C"
Case Else
Throw New FormatException(String.Format("The '{0}' format string is not supported.", format))
End Select
End Function
End Class
Public Module Example
Public Sub Main()
Dim temp1 As New Temperature(0d)
Console.WriteLine(temp1.ToString())
Console.WriteLine(temp1.ToString("C"))
Console.WriteLine(temp1.ToString("F"))
Console.WriteLine(temp1.ToString("K"))
Dim temp2 As New Temperature(-40d)
Console.WriteLine(temp2.ToString())
Console.WriteLine(temp2.ToString("C"))
Console.WriteLine(temp2.ToString("F"))
Console.WriteLine(temp2.ToString("K"))
Dim temp3 As New Temperature(16d)
Console.WriteLine(temp3.ToString())
Console.WriteLine(temp3.ToString("C"))
Console.WriteLine(temp3.ToString("F"))
Console.WriteLine(temp3.ToString("K"))
Console.WriteLine(String.Format("The temperature is now {0:F}.", temp3))
End Sub
End Module
' The example displays the following output:
' 0.00 °C
' 0.00 °C
' 32.00 °F
' 273.15 K
' -40.00 °C
' -40.00 °C
' -40.00 °F
' 233.15 K
' 16.00 °C
' 16.00 °C
' 60.80 °F
' 289.15 K
' The temperature is now 16.00 °C.
public class Temperature
{
private decimal m_Temp;
public Temperature(decimal temperature)
{
this.m_Temp = temperature;
}
public decimal Celsius
{
get { return this.m_Temp; }
}
public decimal Kelvin
{
get { return this.m_Temp + 273.15m; }
}
public decimal Fahrenheit
{
get { return Math.Round(((decimal) (this.m_Temp * 9 / 5 + 32)), 2); }
}
public override string ToString()
{
return this.ToString("C");
}
public string ToString(string format)
{
// Handle null or empty string.
if (String.IsNullOrEmpty(format)) format = "C";
// Remove spaces and convert to uppercase.
format = format.Trim().ToUpperInvariant();
// Convert temperature to Fahrenheit and return string.
switch (format)
{
// Convert temperature to Fahrenheit and return string.
case "F":
return this.Fahrenheit.ToString("N2") + " °F";
// Convert temperature to Kelvin and return string.
case "K":
return this.Kelvin.ToString("N2") + " K";
// return temperature in Celsius.
case "C":
return this.Celsius.ToString("N2") + " °C";
default:
throw new FormatException(String.Format("The '{0}' format string is not supported.", format));
}
}
}
public class Example
{
public static void Main()
{
Temperature temp1 = new Temperature(0m);
Console.WriteLine(temp1.ToString());
Console.WriteLine(temp1.ToString("C"));
Console.WriteLine(temp1.ToString("F"));
Console.WriteLine(temp1.ToString("K"));
Temperature temp2 = new Temperature(-40m);
Console.WriteLine(temp2.ToString());
Console.WriteLine(temp2.ToString("C"));
Console.WriteLine(temp2.ToString("F"));
Console.WriteLine(temp2.ToString("K"));
Temperature temp3 = new Temperature(16m);
Console.WriteLine(temp3.ToString());
Console.WriteLine(temp3.ToString("C"));
Console.WriteLine(temp3.ToString("F"));
Console.WriteLine(temp3.ToString("K"));
Console.WriteLine(String.Format("The temperature is now {0:F}.", temp3));
}
}
// The example displays the following output:
// 0.00 °C
// 0.00 °C
// 32.00 °F
// 273.15 K
// -40.00 °C
// -40.00 °C
// -40.00 °F
// 233.15 K
// 16.00 °C
// 16.00 °C
// 60.80 °F
// 289.15 K
// The temperature is now 16.00 °C.
Retour au début
Chaînes de format personnalisées
Outre les chaînes de format standard, le .NET Framework définit des chaînes de format personnalisées pour les valeurs numériques et les valeurs de date et d'heure. Une chaîne de format personnalisée se compose d'un ou de plusieurs spécificateurs de format personnalisés qui définissent la représentation sous forme de chaîne d'une valeur. Par exemple, la chaîne de format de date et d'heure personnalisée "yyyy\mm\dd hh:mm:ffff t zzz" convertit une date en sa représentation sous forme de chaîne "2008/11/15 07:45:00.0000 P -08:00" pour la culture en-US. De même, la chaîne de format personnalisée "0000" convertit la valeur entière 12 en "0012". Pour obtenir la liste complète des chaînes de format personnalisées, consultez Chaînes de format de date et d'heure personnalisées et Chaînes de format numériques personnalisées.
Si une chaîne de format se compose d'un seul spécificateur de format personnalisé, le spécificateur de format doit être précédé du symbole de pourcentage (%) pour éviter toute confusion avec un spécificateur de format standard. L'exemple suivant utilise le spécificateur de format personnalisé "M" pour afficher un nombre à un chiffre ou à deux chiffres du mois d'une date particulière.
Dim date1 As Date = #09/08/2009#
Console.WriteLine(date1.ToString("%M")) ' Displays 9
DateTime date1 = new DateTime(2009, 9, 8);
Console.WriteLine(date1.ToString("%M")); // Displays 9
De nombreuses chaînes de format standard pour les valeurs de date et d'heure sont des alias de chaînes de format personnalisées qui sont définies par les propriétés de l'objet DateTimeFormatInfo. Les chaînes de format personnalisées offrent également une souplesse considérable en matière de mise en forme définie par l'application pour les valeurs numériques ou les valeurs de date et d'heure. Vous pouvez définir vos propres chaînes de résultat personnalisées à la fois pour les valeurs numériques et pour les valeurs de date et d'heure en combinant plusieurs spécificateurs de format personnalisés dans une chaîne de format personnalisée unique. L'exemple suivant définit une chaîne de format personnalisée qui affiche le jour de la semaine entre parenthèses après le nom du mois, le jour et l'année.
Dim customFormat As String = "MMMM dd, yyyy (dddd)"
Dim date1 As Date = #8/28/2009#
Console.WriteLine(date1.ToString(customFormat))
' The example displays the following output if run on a system
' whose language is English:
' August 28, 2009 (Friday)
string customFormat = "MMMM dd, yyyy (dddd)";
DateTime date1 = new DateTime(2009, 8, 28);
Console.WriteLine(date1.ToString(customFormat));
// The example displays the following output if run on a system
// whose language is English:
// August 28, 2009 (Friday)
Bien que les chaînes de format standard puissent généralement gérer la plupart des besoins de mise en forme pour vos types définis par l'application, vous pouvez également définir des spécificateurs de format personnalisés pour mettre en forme vos types.
Retour au début
Fournisseurs de format et interface IFormatProvider
Si les spécificateurs de format vous permettent de personnaliser la mise en forme d'objets, la production, pour ces derniers, d'une représentation sous forme de chaîne explicite requiert souvent des informations de mise en forme supplémentaires. Par exemple, la mise en forme d'un nombre en tant que valeur monétaire en utilisant la chaîne de format standard "C" ou une chaîne de format personnalisée telle que "$ #, #.00" requiert au minimum l'existence d'informations à inclure dans la chaîne mise en forme concernant le symbole monétaire, le séparateur de groupes et le séparateur décimal appropriés. Dans le .NET Framework, ces informations de mise en forme supplémentaires sont disponibles via l'interface IFormatProvider, laquelle est fournie en tant que paramètre à une ou plusieurs surcharges de la méthode ToString de types numériques et de types de date et d'heure. L'exemple suivant montre comment évolue la représentation sous forme de chaîne d'un objet lorsqu'il est mis en forme avec trois objets IFormatProvider différents.
Imports System.Globalization
Public Module Example
Public Sub Main()
Dim value As Decimal = 1603.42d
Console.WriteLine(value.ToString("C3", New CultureInfo("en-US")))
Console.WriteLine(value.ToString("C3", New CultureInfo("fr-FR")))
Console.WriteLine(value.ToString("C3", New CultureInfo("de-DE")))
End Sub
End Module
' The example displays the following output:
' $1,603.420
' 1 603,420 €
' 1.603,420 €
using System;
using System.Globalization;
public class Example
{
public static void Main()
{
decimal value = 1603.42m;
Console.WriteLine(value.ToString("C3", new CultureInfo("en-US")));
Console.WriteLine(value.ToString("C3", new CultureInfo("fr-FR")));
Console.WriteLine(value.ToString("C3", new CultureInfo("de-DE")));
}
}
// The example displays the following output:
// $1,603.420
// 1 603,420 €
// 1.603,420 €
L'interface IFormatProvider inclut une méthode, GetFormat(Type), qui a un seul paramètre spécifiant le type d'objet qui fournit les informations de mise en forme. Si la méthode peut fournir un objet de ce type, elle le retourne. Sinon, elle retourne une référence null (Nothing en Visual Basic).
IFormatProvider.GetFormat est une méthode de rappel. Lorsque vous appelez une surcharge de méthode ToString qui inclut un paramètre IFormatProvider, elle appelle la méthode GetFormat de cet objet IFormatProvider. La méthode GetFormat est chargée de retourner les informations de mise en forme requises, spécifiées par son paramètre formatType, à la méthode ToString.
Certaines méthodes de mise en forme ou de conversion de chaînes incluent un paramètre de type IFormatProvider, mais la valeur de ce paramètre est souvent ignorée lorsque la méthode est appelée. Le tableau suivant répertorie certaines des méthodes de mise en forme qui utilisent le paramètre et le type de l'objet Type qu'elles passent à la méthode IFormatProvider.GetFormat.
Méthode |
Type de paramètre formatType |
|---|---|
Méthode ToString de types numériques |
|
Méthode ToString de types de date et d'heure |
|
| Remarque |
|---|
Les méthodes ToString des types numériques et des types de date et d'heure sont surchargées, et seules certaines des surcharges incluent un paramètre IFormatProvider.Si une méthode n'a pas de paramètre de type IFormatProvider, l'objet retourné par la propriété CultureInfo.CurrentCulture est passé à la place.Par exemple, un appel à la méthode Int32.ToString() par défaut a, pour résultat, un appel de méthode semblable au suivant : Int32.ToString("G", System.Globalization.CultureInfo.CurrentCulture). |
Le .NET Framework propose trois classes qui implémentent IFormatProvider :
DateTimeFormatInfo, une classe qui fournit des informations de mise en forme pour les valeurs de date et d'heure pour une culture spécifique. Son implémentation de IFormatProvider.GetFormat retourne une instance d'elle-même.
NumberFormatInfo, une classe qui fournit des informations de mise en forme des nombres pour une culture spécifique. Son implémentation de IFormatProvider.GetFormat retourne une instance d'elle-même.
CultureInfo. Son implémentation de IFormatProvider.GetFormat peut retourner un objet NumberFormatInfo pour fournir des informations de mise en forme des nombres ou un objet DateTimeFormatInfo pour fournir des informations de mise en forme des valeurs de date et d'heure.
Vous pouvez aussi implémenter votre propre fournisseur de format en remplacement de l'une de ces classes. Toutefois, la méthode GetFormat de votre implémentation doit retourner un objet du type répertorié dans le tableau précédent s'il doit fournir des informations de mise en forme à la méthode ToString.
Retour au début
Interface IFormattable
En règle générale, les types qui surchargent la méthode ToString avec une chaîne de format et un paramètre IFormatProvider implémentent également l'interface IFormattable. Cette interface comprend un seul membre, IFormattable.ToString(String, IFormatProvider), qui inclut comme paramètres une chaîne de format et un fournisseur de format.
L'implémentation de l'interface IFormattable pour votre classe définie par l'application présente deux avantages :
Prise en charge de la conversion de chaînes par la classe Convert. Les appels aux méthodes Convert.ToString(Object) et Convert.ToString(Object, IFormatProvider) appellent automatiquement votre implémentation d'IFormattable.
Prise en charge de la mise en forme composite. Si un élément de mise en forme qui inclut une chaîne de format est utilisé pour mettre en forme votre type personnalisé, le Common Language Runtime appelle automatiquement votre implémentation d'IFormattable et lui passe la chaîne de format. Pour plus d'informations sur la mise en forme composite avec des méthodes telles que String.Format ou Console.WriteLine, consultez la section Mise en forme composite.
L'exemple suivant définit une classe Temperature qui implémente l'interface IFormattable. Il prend en charge les spécificateurs de format "C" ou "G" pour afficher la température en Celsius, le spécificateur de format "F" pour afficher la température en Fahrenheit et le spécificateur de format "K" pour afficher la température en Kelvin.
Imports System.Globalization
Public Class Temperature : Implements IFormattable
Private m_Temp As Decimal
Public Sub New(temperature As Decimal)
Me.m_Temp = temperature
End Sub
Public ReadOnly Property Celsius() As Decimal
Get
Return Me.m_Temp
End Get
End Property
Public ReadOnly Property Kelvin() As Decimal
Get
Return Me.m_Temp + 273.15d
End Get
End Property
Public ReadOnly Property Fahrenheit() As Decimal
Get
Return Math.Round(CDec(Me.m_Temp * 9 / 5 + 32), 2)
End Get
End Property
Public Overrides Function ToString() As String
Return Me.ToString("G", Nothing)
End Function
Public Overloads Function ToString(format As String) As String
Return Me.ToString(format, Nothing)
End Function
Public Overloads Function ToString(format As String, provider As IFormatProvider) As String _
Implements IFormattable.ToString
' Handle null or empty arguments.
If String.IsNullOrEmpty(format) Then format = "G"
' Remove any white space and convert to uppercase.
format = format.Trim().ToUpperInvariant()
If provider Is Nothing Then provider = NumberFormatInfo.CurrentInfo
Select Case format
' Convert temperature to Fahrenheit and return string.
Case "F"
Return Me.Fahrenheit.ToString("N2", provider) & "°F"
' Convert temperature to Kelvin and return string.
Case "K"
Return Me.Kelvin.ToString("N2", provider) & "K"
' Return temperature in Celsius.
Case "C", "G"
Return Me.Celsius.ToString("N2", provider) & "°C"
Case Else
Throw New FormatException(String.Format("The '{0}' format string is not supported.", format))
End Select
End Function
End Class
using System;
using System.Globalization;
public class Temperature : IFormattable
{
private decimal m_Temp;
public Temperature(decimal temperature)
{
this.m_Temp = temperature;
}
public decimal Celsius
{
get { return this.m_Temp; }
}
public decimal Kelvin
{
get { return this.m_Temp + 273.15m; }
}
public decimal Fahrenheit
{
get { return Math.Round((decimal) this.m_Temp * 9 / 5 + 32, 2); }
}
public override string ToString()
{
return this.ToString("G", null);
}
public string ToString(string format)
{
return this.ToString(format, null);
}
public string ToString(string format, IFormatProvider provider)
{
// Handle null or empty arguments.
if (String.IsNullOrEmpty(format)) format = "G";
// Remove any white space and convert to uppercase.
format = format.Trim().ToUpperInvariant();
if (provider == null) provider = NumberFormatInfo.CurrentInfo;
switch (format)
{
// Convert temperature to Fahrenheit and return string.
case "F":
return this.Fahrenheit.ToString("N2", provider) + "°F";
// Convert temperature to Kelvin and return string.
case "K":
return this.Kelvin.ToString("N2", provider) + "K";
// Return temperature in Celsius.
case "C":
case "G":
return this.Celsius.ToString("N2", provider) + "°C";
default:
throw new FormatException(String.Format("The '{0}' format string is not supported.", format));
}
}
}
L'exemple suivant instancie un objet Temperature. Il appelle ensuite la méthode ToString et utilise plusieurs chaînes de format composites pour obtenir des représentations sous forme de chaîne différentes d'un objet Temperature. Chacun de ces appels de méthode appelle, à son tour, l'implémentation d'IFormattable de la classe Temperature.
Public Module Example
Public Sub Main()
Dim temp1 As New Temperature(22d)
Console.WriteLine(Convert.ToString(temp1, New CultureInfo("ja-JP")))
Console.WriteLine("Temperature: {0:K}", temp1)
Console.WriteLine("Temperature: {0:F}", temp1)
Console.WriteLine(String.Format(New CultureInfo("fr-FR"), "Temperature: {0:F}", temp1))
End Sub
End Module
' The example displays the following output:
' 22.00°C
' Temperature: 295.15°K
' Temperature: 71.60°F
' Temperature: 71,60°F
public class Example
{
public static void Main()
{
Temperature temp1 = new Temperature(22m);
Console.WriteLine(Convert.ToString(temp1, new CultureInfo("ja-JP")));
Console.WriteLine("Temperature: {0:K}", temp1);
Console.WriteLine("Temperature: {0:F}", temp1);
Console.WriteLine(String.Format(new CultureInfo("fr-FR"), "Temperature: {0:F}", temp1));
}
}
// The example displays the following output:
// 22.00°C
// Temperature: 295.15°K
// Temperature: 71.60°F
// Temperature: 71,60°F
Retour au début
Mise en forme composite
Certaines méthodes, telles que String.Format et StringBuilder.AppendFormat, prennent en charge la mise en forme composite. Une chaîne de format composite est un genre de modèle retournant une seule chaîne qui incorpore la représentation sous forme de chaîne de zéro, un ou plusieurs objets. Chaque objet est représenté dans la chaîne de format composite par un élément de mise en forme indexé. L'index de l'élément de mise en forme correspond à la position de l'objet qu'il représente dans la liste de paramètres de la méthode. Les index sont de base zéro. Par exemple, dans l'appel de méthode suivant à la méthode String.Format, le premier élément de mise en forme, {0:D}, est remplacé par la représentation sous forme de chaîne de thatDate ; le deuxième élément de mise en forme, {1}, est remplacé par la représentation sous forme de chaîne item1 ; et le troisième élément de mise en forme, {2:C2}, est remplacé par la représentation sous forme de chaîne de item1.Value.
result = String.Format("On {0:d}, the inventory of {1} was worth {2:C2}.", _
thatDate, item1, item1.Value)
Console.WriteLine(result)
' The example displays output like the following if run on a system
' whose current culture is en-US:
' On 5/1/2009, the inventory of WidgetA was worth $107.44.
result = String.Format("On {0:d}, the inventory of {1} was worth {2:C2}.",
thatDate, item1, item1.Value);
Console.WriteLine(result);
// The example displays output like the following if run on a system
// whose current culture is en-US:
// On 5/1/2009, the inventory of WidgetA was worth $107.44.
Pour plus d'informations sur la mise en forme composite, consultez Mise en forme composite.
Retour au début
Mise en forme personnalisée avec ICustomFormatter
Certaines méthodes de mise en forme composite, telles que String.Format(IFormatProvider, String, Object[]) et StringBuilder.AppendFormat(IFormatProvider, String, Object[]), incluent un paramètre de fournisseur de format qui prend en charge la mise en forme personnalisée. Lorsque la méthode de mise en forme est appelée, elle passe à une méthode GetFormat du fournisseur de format un objet Type qui représente une interface ICustomFormatter. La méthode GetFormat est alors chargée de retourner l'implémentation d'ICustomFormatter qui fournit la mise en forme personnalisée.
L'interface ICustomFormatter a une méthode unique, Format(String, Object, IFormatProvider), qui est appelée automatiquement par une méthode de mise en forme composite, une fois pour chaque élément de mise en forme dans une chaîne de format composite. La méthode Format(String, Object, IFormatProvider) a trois paramètres : une chaîne de format, qui représente l'argument formatString dans un élément de mise en forme, un objet à mettre en forme et un objet IFormatProvider qui fournit des services de mise en forme. En général, la classe qui implémente ICustomFormatter implémente également IFormatProvider ; ce dernier paramètre est donc une référence à la classe de mise en forme personnalisée elle-même. La méthode retourne une représentation sous forme de chaîne mise en forme personnalisée de l'objet à mettre en forme. Si la méthode ne peut pas mettre en forme l'objet, elle doit retourner une référence null (Nothing en Visual Basic).
L'exemple suivant fournit une implémentation d'ICustomFormatter nommée ByteByByteFormatter qui affiche des valeurs entières sous la forme d'une séquence de valeurs hexadécimales à deux chiffres suivie d'un espace.
Public Class ByteByByteFormatter : Implements IFormatProvider, ICustomFormatter
Public Function GetFormat(formatType As Type) As Object _
Implements IFormatProvider.GetFormat
If formatType Is GetType(ICustomFormatter) Then
Return Me
Else
Return Nothing
End If
End Function
Public Function Format(fmt As String, arg As Object,
formatProvider As IFormatProvider) As String _
Implements ICustomFormatter.Format
If Not formatProvider.Equals(Me) Then Return Nothing
' Handle only hexadecimal format string.
If Not fmt.StartsWith("X") Then
Return Nothing
End If
' Handle only integral types.
If Not typeof arg Is Byte AndAlso
Not typeof arg Is Int16 AndAlso
Not typeof arg Is Int32 AndAlso
Not typeof arg Is Int64 AndAlso
Not typeof arg Is SByte AndAlso
Not typeof arg Is UInt16 AndAlso
Not typeof arg Is UInt32 AndAlso
Not typeof arg Is UInt64 Then _
Return Nothing
Dim bytes() As Byte = BitConverter.GetBytes(arg)
Dim output As String = Nothing
For ctr As Integer = bytes.Length - 1 To 0 Step -1
output += String.Format("{0:X2} ", bytes(ctr))
Next
Return output.Trim()
End Function
End Class
public class ByteByByteFormatter : IFormatProvider, ICustomFormatter
{
public object GetFormat(Type formatType)
{
if (formatType == typeof(ICustomFormatter))
return this;
else
return null;
}
public string Format(string format, object arg,
IFormatProvider formatProvider)
{
if (! formatProvider.Equals(this)) return null;
// Handle only hexadecimal format string.
if (! format.StartsWith("X")) return null;
byte[] bytes;
string output = null;
// Handle only integral types.
if (arg is Byte)
bytes = BitConverter.GetBytes((Byte) arg);
else if (arg is Int16)
bytes = BitConverter.GetBytes((Int16) arg);
else if (arg is Int32)
bytes = BitConverter.GetBytes((Int32) arg);
else if (arg is Int64)
bytes = BitConverter.GetBytes((Int64) arg);
else if (arg is SByte)
bytes = BitConverter.GetBytes((SByte) arg);
else if (arg is UInt16)
bytes = BitConverter.GetBytes((UInt16) arg);
else if (arg is UInt32)
bytes = BitConverter.GetBytes((UInt32) arg);
else if (arg is UInt64)
bytes = BitConverter.GetBytes((UInt64) arg);
else
return null;
for (int ctr = bytes.Length - 1; ctr >= 0; ctr--)
output += String.Format("{0:X2} ", bytes[ctr]);
return output.Trim();
}
}
L'exemple suivant utilise la classe ByteByByteFormatter pour mettre en forme des valeurs entières. Notez que la méthode ICustomFormatter.Format est appelée plusieurs fois dans le deuxième appel de méthode String.Format(IFormatProvider, String, Object[]), et que le fournisseur NumberFormatInfo par défaut est utilisé dans le troisième appel de méthode, car la méthode .ByteByByteFormatter.Format ne reconnaît pas la chaîne de format "N0" et retourne une référence null (Nothing en Visual Basic).
Public Module Example
Public Sub Main()
Dim value As Long = 3210662321
Dim value1 As Byte = 214
Dim value2 As Byte = 19
Console.WriteLine((String.Format(New ByteByByteFormatter(), "{0:X}", value)))
Console.WriteLine((String.Format(New ByteByByteFormatter(), "{0:X} And {1:X} = {2:X} ({2:000})",
value1, value2, value1 And value2)))
Console.WriteLine(String.Format(New ByteByByteFormatter(), "{0,10:N0}", value))
End Sub
End Module
' The example displays the following output:
' 00 00 00 00 BF 5E D1 B1
' 00 D6 And 00 13 = 00 12 (018)
' 3,210,662,321
public class Example
{
public static void Main()
{
long value = 3210662321;
byte value1 = 214;
byte value2 = 19;
Console.WriteLine(String.Format(new ByteByByteFormatter(), "{0:X}", value));
Console.WriteLine(String.Format(new ByteByByteFormatter(), "{0:X} And {1:X} = {2:X} ({2:000})",
value1, value2, value1 & value2));
Console.WriteLine(String.Format(new ByteByByteFormatter(), "{0,10:N0}", value));
}
}
// The example displays the following output:
// 00 00 00 00 BF 5E D1 B1
// 00 D6 And 00 13 = 00 12 (018)
// 3,210,662,321
Retour au début
Rubriques connexes
Titre |
Définition |
|---|---|
Décrit des chaînes de format standard qui créent des représentations sous forme de chaîne couramment utilisées de valeurs numériques. |
|
Décrit des chaînes de format personnalisées qui créent des formats spécifiques à l'application pour les valeurs numériques. |
|
Décrit des chaînes de format standard qui créent des représentations sous forme de chaîne couramment utilisées de valeurs DateTime. |
|
Décrit des chaînes de format personnalisées qui créent des formats spécifiques à l'application pour les valeurs DateTime. |
|
Décrit des chaînes de format standard qui créent des représentations sous forme de chaîne couramment utilisées d'intervalles de temps. |
|
Décrit des chaînes de format personnalisées qui créent des formats spécifiques à l'application pour les intervalles de temps. |
|
Décrit les chaînes de format standard qui sont utilisées pour créer des représentations sous forme de chaîne de valeurs d'énumération. |
|
Explique comment incorporer une ou plusieurs valeurs mises en forme dans une chaîne. La chaîne peut ensuite être affichée dans la console ou écrite dans un flux. |
|
Répertorie les rubriques qui fournissent des instructions pas à pas pour effectuer des opérations de mise en forme spécifiques. |
|
Décrit comment initialiser des objets aux valeurs décrites par des représentations sous forme de chaîne de ces objets. L'analyse est l'opération inverse de la mise en forme. |
Retour au début