IFormatProvider, interface

L'interface IFormatProvider propose un objet qui fournit des information de mise en forme pour les opérations de mise en forme et d'analyse. Les opérations de mise en forme convertissent la valeur d'un type en la représentation sous forme de chaîne de cette valeur. Les méthodes de mise en forme typiques sont les méthodes ToString d'un type, ainsi que Format. Les opérations d'analyse convertissent la représentation sous forme de chaîne d'une valeur en un type ayant cette valeur. Les méthodes d'analyse typiques sont Parse et TryParse.

L'interface IFormatProvider se compose d'une méthode unique, IFormatProvider.GetFormat. GetFormat est une méthode de rappel : la méthode d'analyse ou de mise en forme l'appelle et lui passe un objet Type qui représente le type d'objet censé fournir les informations de mise en forme. La méthode GetFormat est chargée du retour d'un objet de ce type.

Les implémentations IFormatProvider sont souvent utilisées implicitement en mettant en forme et en analysant des méthodes. Par exemple, la méthode DateTime.ToString(String) utilise implicitement une implémentation IFormatProvider qui représente la culture actuelle du système. Les implémentations IFormatProvider peuvent également être spécifiées explicitement par les méthodes qui ont un paramètre de type IFormatProvider, telles que Int32.Parse(String, IFormatProvider) et String.Format(IFormatProvider, String, Object[]).

Le .NET Framework inclut les trois implémentations IFormatProvider prédéfinies suivantes pour fournir des informations spécifiques à la culture utilisées pour la mise en forme ou l'analyse numérique et les valeurs de date et d'heure :

• Classe NumberFormatInfo, qui fournit des informations qui permettent de mettre en forme des nombres, tels que les symboles de devise, de séparateur des milliers et de séparateur décimal, pour une culture spécifique.

• Classe DateTimeFormatInfo qui fournit des informations utilisées pour mettre en forme les dates et les heures, notamment les symboles du séparateur de la date et de l'heure pour une culture particulière, ou l'ordre et le format des composants année, mois et jour d'une date.

• Classe CultureInfo qui représente une culture particulière. Sa méthode GetFormat retourne un objet NumberFormatInfo ou DateTimeFormatInfo spécifique à la culture selon que l'objet CultureInfo est utilisé dans une opération de mise en forme ou d'analyse qui implique des nombres, des dates ou des heures.

Le .NET Framework prend également en charge la mise en forme personnalisée. Cela implique en général la création d'une classe de mise en forme qui implémente IFormatProvider et ICustomFormatter. Puis une instance de cette classe est passée comme paramètre à une méthode qui exécute une opération de mise en forme personnalisée, telle que String.Format(IFormatProvider, String, Object[]). L'exemple fournit une illustration d'une telle implémentation personnalisée qui met en forme un nombre comme un numéro de compte de 12 chiffres.

L'exemple suivant illustre comment une implémentation IFormatProvider peut modifier la représentation d'une valeur de date et d'heure. Dans ce cas, une date unique est affichée à l'aide des objets CultureInfo qui représentent quatre cultures différentes.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      DateTime dateValue = new DateTime(2009, 6, 1, 4, 37, 0);
      CultureInfo[] cultures = { new CultureInfo("en-US"), 
                                 new CultureInfo("fr-FR"),
                                 new CultureInfo("it-IT"),
                                 new CultureInfo("de-DE") };
      foreach (CultureInfo culture in cultures)
         Console.WriteLine("{0}: {1}", culture.Name, dateValue.ToString(culture));
   }
}
// The example displays the following output:
//       en-US: 6/1/2009 4:37:00 PM
//       fr-FR: 01/06/2009 16:37:00
//       it-IT: 01/06/2009 16.37.00
//       de-DE: 01.06.2009 16:37:00

L'exemple suivant illustre l'utilisation d'une classe qui implémente l'interface IFormatProvider et la méthode GetFormat. La classe AcctNumberFormat convertit une valeur Int64 qui représente un numéro de compte en numéro de compte à 12 chiffres mis en forme. Sa méthode GetFormat retourne une référence à l'instance actuelle d'AcctNumberFormat si le paramètre formatType fait référence à une classe qui implémente ICustomFormatter ; sinon, GetFormat retourne null.

public class AcctNumberFormat : IFormatProvider, ICustomFormatter
{
   private const int ACCT_LENGTH = 12;

   public object GetFormat(Type formatType)
   {
      if (formatType == typeof(ICustomFormatter))
         return this;
      else
         return null;
   }

   public string Format(string fmt, object arg, IFormatProvider formatProvider) 
   {
      // Provide default formatting if arg is not an Int64.
      if (arg.GetType() != typeof(Int64))
         try {
            return HandleOtherFormats(fmt, arg); 
         }
         catch (FormatException e) {
            throw new FormatException(String.Format("The format of '{0}' is invalid.", fmt), e);
         }

      // Provide default formatting for unsupported format strings.
      string ufmt = fmt.ToUpper(CultureInfo.InvariantCulture);
      if (! (ufmt == "H" || ufmt == "I")) 
         try {
            return HandleOtherFormats(fmt, arg);
         }
         catch (FormatException e) {
            throw new FormatException(String.Format("The format of '{0}' is invalid.", fmt), e);
         }

      // Convert argument to a string.
      string result = arg.ToString();

      // If account number is less than 12 characters, pad with leading zeroes.
      if (result.Length < ACCT_LENGTH)
         result = result.PadLeft(ACCT_LENGTH, '0');
      // If account number is more than 12 characters, truncate to 12 characters.
      if (result.Length > ACCT_LENGTH)
         result = result.Substring(0, ACCT_LENGTH);   

      if (ufmt == "I")                    // Integer-only format. 
         return result;
      // Add hyphens for H format specifier.
      else                                         // Hyphenated format.
         return result.Substring(0, 5) + "-" + result.Substring(5, 3) + "-" + result.Substring(8);
   }

   private string HandleOtherFormats(string format, object arg)
   {
      if (arg is IFormattable) 
         return ((IFormattable)arg).ToString(format, CultureInfo.CurrentCulture);
      else if (arg != null)
         return arg.ToString();
      else
         return String.Empty;
   }
}

La classe qui implémente IFormatProvider peut ensuite être utilisée dans un appel à une opération de mise en forme et d'analyse. Par exemple, le code suivant appelle la méthode String.Format(IFormatProvider, String, Object[]) pour générer une chaîne qui contient un numéro de compte à 12 chiffres mis en forme.

using System;
using System.Globalization;

public enum DaysOfWeek { Monday=1, Tuesday=2 };

public class TestFormatting
{
   public static void Main()
   {
      long acctNumber;
      double balance; 
      DaysOfWeek wday; 
      string output;

      acctNumber = 104254567890;
      balance = 16.34;
      wday = DaysOfWeek.Monday;

      output = String.Format(new AcctNumberFormat(), 
                             "On {2}, the balance of account {0:H} was {1:C2}.", 
                             acctNumber, balance, wday);
      Console.WriteLine(output);

      wday = DaysOfWeek.Tuesday;
      output = String.Format(new AcctNumberFormat(), 
                             "On {2}, the balance of account {0:I} was {1:C2}.", 
                             acctNumber, balance, wday);
      Console.WriteLine(output);
   }
}
// The example displays the following output:
//       On Monday, the balance of account 10425-456-7890 was $16.34.
//       On Tuesday, the balance of account 104254567890 was $16.34.

.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