IFormattable.ToString, méthode

La méthode ToString convertit une valeur en représentation sous forme de chaîne qui peut être exprimée de plusieurs façons. Son format précis dépend de symboles spécifiques ou d'un ordre spécifié défini par les cultures, les professions ou les industries spécifiques. Vous pouvez appeler la méthode directement. Il est également 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, telles que String.Format(String, Object[]), Console.WriteLine(String, Object[]) et StringBuilder.AppendFormat(String, Object[]). (Pour plus d'informations, consultez Mise en forme composite.)

Les méthodes de mise en forme composite appellent la méthode ToString une fois pour chaque élément de mise en forme dans une chaîne de format. Les paramètres passés à la méthode dépendent de la méthode de mise en forme spécifique qui est appelée et du contenu de l'élément de mise en forme, comme suit :

• Si l'élément de mise en forme n'inclut pas de chaîne de mise en forme (par exemple, si l'élément de mise en forme est simplement {0}), null est considéré comme valeur du paramètre System.String.

• Si l'élément de mise en forme inclut une chaîne de mise en forme (par exemple, {0:G}), cette chaîne de mise en forme est passée comme valeur du paramètre System.String.

• Si l'appel de méthode d'origine n'inclut pas de paramètre System.IFormatProvider, CultureInfo.CurrentCulture est passé comme valeur du paramètre System.IFormatProvider.

• Si l'appel de méthode d'origine inclut un paramètre System.IFormatProvider, le fournisseur fourni dans l'appel de méthode est passé comme valeur du paramètre System.IFormatProvider.

Remarque
L'implémentation de ToString d'un objet est appelée par les méthodes de mise en forme composite uniquement si un fournisseur de format ICustomFormatter ne leur est pas passé, ou si la méthode Format du fournisseur de format personnalisé retourne null.

Le .NET Framework inclut trois fournisseurs de format, qui implémentent tous l'interface IFormatProvider :

• NumberFormatInfo fournit des informations de mise en forme des nombres, telles que les caractères à utiliser comme séparateurs décimaux et de groupes, ainsi que l'orthographe et le positionnement des symboles monétaires dans les valeurs monétaires.

• DateTimeFormatInfo fournit des informations de mise en forme de la date et de l'heure, telles que la position du mois, du jour et de l'année dans le modèle de date.

• CultureInfo contient les informations de mise en forme par défaut dans une culture spécifique, telles que les informations de mise en forme des nombres, ainsi que de la date et de l'heure.

De plus, vous pouvez définir votre propre fournisseur de format personnalisé.

La méthode ToString 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 montre une classe Temperature qu'implémente la méthode ToString. Cet exemple de code fait partie d'un exemple plus complet fourni pour la classe IFormattable.

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));
      }
   }
}

.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