IFormattable, interface

L'interface IFormattable convertit un objet en sa représentation sous forme de chaîne selon une chaîne de format et un fournisseur de format.

Une chaîne de mise en forme définit en général l'apparence générale d'un objet. Par exemple, le .NET Framework prend en charge les éléments suivants :

• Chaînes de format standard pour la mise en forme de valeurs d'énumération (consultez Chaînes de format d'énumération).

• Chaînes de format standard et personnalisées pour la mise en forme de valeurs numériques (consultez Chaînes de format numériques standard et Chaînes de format numériques personnalisées).

• Chaînes de format standard et personnalisées pour la mise en forme de valeurs de date et d'heure (consultez Chaînes de format de date et d'heure standard et Chaînes de format de date et d'heure personnalisées).

• Chaînes de format standard et personnalisées pour la mise en forme d'intervalles de temps (consultez Chaînes de format TimeSpan standard. et Chaînes de format TimeSpan personnalisées).

Vous pouvez également définir vos propres chaînes de mise en forme pour prendre en charge la mise en forme de vos types définis par l'application.

Un fournisseur de format retourne un objet de mise en forme qui en général définit les symboles utilisés pour la conversion d'un objet en sa représentation sous forme de chaîne. Par exemple, lorsque vous convertissez un nombre en une valeur monétaire, un fournisseur de format définit le symbole monétaire qui s'affiche dans la chaîne de résultat. Le .NET Framework définit trois fournisseurs de format :

• Classe System.Globalization.CultureInfo, qui retourne un objet NumberFormatInfo pour la mise en forme de valeurs numériques ou un objet DateTimeFormatInfo pour la mise en forme de valeurs de date et d'heure.

• Classe System.Globalization.NumberFormatInfo qui retourne une instance d'elle-même pour la mise en forme de valeurs numériques.

• Classe System.Globalization.DateTimeFormatInfo qui retourne une instance d'elle-même pour la mise en forme de valeurs de date et d'heure.

De plus, vous pouvez définir vos propres fournisseurs de format personnalisés pour fournir des informations spécifiques à la culture, à la profession ou à l'industrie utilisées pour la mise en forme. Pour plus d'informations sur l'implémentation de la mise en forme personnalisée à l'aide d'un fournisseur de format personnalisé, consultez ICustomFormatter.

L'interface IFormattable définit une méthode unique, ToString, qui fournit des services de mise en forme pour le type d'implémentation. La méthode ToString peut être appelée directement. De plus, il est appelé automatiquement par les méthodes Convert.ToString(Object) et Convert.ToString(Object, IFormatProvider), et par les méthodes qui utilisent la fonctionnalité de mise en forme composite dans le .NET Framework. Ces méthodes incluent notamment Console.WriteLine(String, Object), String.Format et StringBuilder.AppendFormat(String, Object). La méthode ToString est appelée pour chaque élément de mise en forme dans la chaîne de mise en forme de la méthode.

L'interface IFormattable est implémentée par les types de données de base.

Les classes qui ont besoin de plus de contrôle sur la mise en forme des chaînes que ce que fournit Object.ToString doivent implémenter IFormattable.

Une classe implémentant IFormattable doit prendre en charge le spécificateur de format « G » (général). Outre le spécificateur « G », la classe peut définir la liste des spécificateurs de format qu'elle prend en charge. De plus, la classe doit être préparée à gérer un spécificateur de format qui est null. Pour plus d'informations sur la mise en forme et les codes de mise en forme, consultez Mise en forme des types.

L'exemple suivant définit une classe Temperature qui implémente l'interface IFormattable. La classe prend en charge quatre spécificateurs de format : « G » et « C », qui indiquent que la température sera affichée en degrés Celsius ; « F », qui indique que la température sera affichée en degrés Fahrenheit ; et « K », qui indique que la température sera affichée en degrés Kelvin. De plus, l'implémentation IFormattable.ToString peut également gérer une chaîne de mise en forme qui est null ou vide. Les deux autres méthodes ToString définies par la classe Temperature incluent simplement dans un wrapper un appel à l'implémentation IFormattable.ToString.

using System;
using System.Globalization;

public class Temperature : IFormattable
{
   private decimal temp;

   public Temperature(decimal temperature)
   {
      if (temperature < -273.15m) 
        throw new ArgumentOutOfRangeException(String.Format("{0} is less than absolute zero.", 
                                              temperature));
      this.temp = temperature;
   }

   public decimal Celsius
   {
      get { return temp; }
   }

   public decimal Fahrenheit
   {
      get { return temp * 9 / 5 + 32; }
   }

   public decimal Kelvin
   {
      get { return temp + 273.15m; }
   }

   public override string ToString()
   {
      return this.ToString("G", CultureInfo.CurrentCulture);
   }

   public string ToString(string format)
   {
      return this.ToString(format, CultureInfo.CurrentCulture);
   }

   public string ToString(string format, IFormatProvider provider) 
   {
      if (String.IsNullOrEmpty(format)) format = "G";
      if (provider == null) provider = CultureInfo.CurrentCulture;

      switch (format.ToUpperInvariant())
      {
         case "G":
         case "C":
            return temp.ToString("F2", provider) + " °C"; 
         case "F":
            return Fahrenheit.ToString("F2", provider) + " °F";
         case "K":
            return Kelvin.ToString("F2", provider) + " K";
         default:
            throw new FormatException(String.Format("The {0} format string is not supported.", format));
      }
   }
}

L'exemple suivant appelle ensuite l'implémentation IFormattable.ToString directement ou au moyen d'une chaîne de format composite.

public class Example
{
   public static void Main()
   {
      // Use composite formatting with format string in the format item.
      Temperature temp1 = new Temperature(0);
      Console.WriteLine("{0:C} (Celsius) = {0:K} (Kelvin) = {0:F} (Fahrenheit)\n", temp1);

      // Use composite formatting with a format provider.
      temp1 = new Temperature(-40);
      Console.WriteLine(String.Format(CultureInfo.CurrentCulture, "{0:C} (Celsius) = {0:K} (Kelvin) = {0:F} (Fahrenheit)", temp1));
      Console.WriteLine(String.Format(new CultureInfo("fr-FR"), "{0:C} (Celsius) = {0:K} (Kelvin) = {0:F} (Fahrenheit)\n", temp1));

      // Call ToString method with format string.
      temp1 = new Temperature(32);
      Console.WriteLine("{0} (Celsius) = {1} (Kelvin) = {2} (Fahrenheit)\n", 
                        temp1.ToString("C"), temp1.ToString("K"), temp1.ToString("F"));

      // Call ToString with format string and format provider
      temp1 = new Temperature(100)      ;
      NumberFormatInfo current = NumberFormatInfo.CurrentInfo;
      CultureInfo nl = new CultureInfo("nl-NL"); 
      Console.WriteLine("{0} (Celsius) = {1} (Kelvin) = {2} (Fahrenheit)", 
                        temp1.ToString("C", current), temp1.ToString("K", current), temp1.ToString("F", current));
      Console.WriteLine("{0} (Celsius) = {1} (Kelvin) = {2} (Fahrenheit)", 
                        temp1.ToString("C", nl), temp1.ToString("K", nl), temp1.ToString("F", nl));
   }
}
// The example displays the following output:
//    0.00 °C (Celsius) = 273.15 K (Kelvin) = 32.00 °F (Fahrenheit)
//    
//    -40.00 °C (Celsius) = 233.15 K (Kelvin) = -40.00 °F (Fahrenheit)
//    -40,00 °C (Celsius) = 233,15 K (Kelvin) = -40,00 °F (Fahrenheit)
//    
//    32.00 °C (Celsius) = 305.15 K (Kelvin) = 89.60 °F (Fahrenheit)
//    
//    100.00 °C (Celsius) = 373.15 K (Kelvin) = 212.00 °F (Fahrenheit)
//    100,00 °C (Celsius) = 373,15 K (Kelvin) = 212,00 °F (Fahrenheit)

.NET Framework

.NET Framework Client Profile

Windows 7, Windows Vista SP1 ou ultérieur, Windows XP SP3, Windows XP SP2 Édition x64, Windows Server 2008 (installation minimale non prise en charge), Windows Server 2008 R2 (installation minimale prise en charge avec SP1 ou version ultérieure), Windows Server 2003 SP2

Référence

Autres ressources