StringBuilder.AppendFormat, méthode (IFormatProvider, String, Object[])

Cette méthode utilise la fonctionnalité de mise en forme composite du .NET Framework pour convertir la valeur d'un objet en sa représentation textuelle et incorporer cette représentation dans l'objet StringBuilder actuel.

Le paramètre format se compose de zéro ou de plusieurs exécutions de texte associées à zéro ou de plusieurs espaces réservés indexés, appelés éléments de format, qui correspondent aux objets de la liste de paramètres de cette méthode. Le processus de mise en forme remplace chaque élément de mise en forme par la représentation sous forme de chaîne de l'objet correspondant.

La syntaxe d'un élément de mise en forme est la suivante :

{index[,length][:formatString]}

Les éléments entre crochets sont facultatifs. Le tableau suivant décrit les différents éléments.

Remarque

Pour connaître les chaînes de format standard et personnalisées utilisées avec les 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. Pour connaître les chaînes de format standard et personnalisées utilisées avec les valeurs numériques, consultez Chaînes de format numériques standard et Chaînes de format numériques personnalisées. Pour connaître les chaînes de format standard utilisées avec les énumérations, consultez Chaînes de format d'énumération.

Le paramètre provider spécifie une implémentation IFormatProvider qui peut fournir des informations de mise en forme pour les objets dans args. provider peut être :

• Objet CultureInfo qui fournit des informations de format spécifiques à la culture.

• Objet NumberFormatInfo qui fournit des informations de mise en forme spécifiques à la culture pour les valeurs numériques dans args.

• Objet DateTimeFormatInfo qui fournit information de mise en forme spécifique à la culture pour les valeurs date et heure dans args.

• Implémentation IFormatProvider personnalisée qui fournit les informations de mise en forme pour un ou plusieurs objets dans args. En général, une telle implémentation implémente également l'interface ICustomFormatter. Le deuxième exemple de la section suivante illustre un appel de la méthode StringBuilder.AppendFormat(IFormatProvider, String, Object[]) avec une implémentation IFormatProvider personnalisée.

Si le paramètre provider est null, les informations de fournisseur de format sont obtenues à partir de la culture en cours.

args représente les objets à mettre en forme. Chaque élément de mise en forme dans format est remplacé par la représentation sous forme de chaîne de l'objet correspondant dans args. Si l'élément de mise en forme inclut formatString et l'objet correspondant dans args implémente l'interface IFormattable, alors args[index].Format(formatString, provider) définit la mise en forme. Dans le cas contraire, args[index].ToString(provider) définit la mise en forme.

Dans .NET Framework 4 et .NET Framework 4.5, lorsque vous instanciez l'objet d' StringBuilder en appelant le constructeur d' StringBuilder(Int32, Int32) , la longueur et l'instance d' StringBuilder peuvent étendre au delà de la valeur de sa propriété d' MaxCapacity . Cela peut se produire en particulier lorsque vous appelez des méthodes d' Append et d' AppendFormat pour ajouter des petites chaînes.

L'exemple de code suivant illustre la méthode AppendFormat.

using System;
using System.Text;
using System.Globalization;

class Sample 
{
    static StringBuilder sb = new StringBuilder();

    public static void Main() 
    {
    int    var1   = 111;
    float  var2   = 2.22F;
    string var3   = "abcd";
    object[] var4 = {3, 4.4, 'X'};

    Console.WriteLine();
    Console.WriteLine("StringBuilder.AppendFormat method:");
    sb.AppendFormat("1) {0}", var1);
    Show(sb);
    sb.AppendFormat("2) {0}, {1}", var1, var2);
    Show(sb);
    sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3);
    Show(sb);
    sb.AppendFormat("4) {0}, {1}, {2}", var4);
    Show(sb);
    CultureInfo ci = new CultureInfo("es-ES", true);
    sb.AppendFormat(ci, "5) {0}", var2);
    Show(sb);
    }

    public static void Show(StringBuilder sbs)
    {
    Console.WriteLine(sbs.ToString());
    sb.Length = 0;
    }
}
/*
This example produces the following results:

StringBuilder.AppendFormat method:
1) 111
2) 111, 2.22
3) 111, 2.22, abcd
4) 3, 4.4, X
5) 2,22
*/

L'exemple suivant définit une implémentation IFormatProvider personnalisée nommée CustomerFormatter qui met en forme un numéro de client de 10 chiffres avec des traits d'union après le quatrième chiffre et le septième chiffre. Il est passé à la méthode StringBuilder.AppendFormat(IFormatProvider, String, Object[]) pour créer une chaîne qui inclut le numéro et le nom de client mis en forme.

using System;
using System.Text;

public class Customer
{
   private string custName;
   private int custNumber;

   public Customer(string name, int number)
   {
      this.custName = name;
      this.custNumber = number;
   }

   public string Name
   {
      get { return this.custName; }
   }

   public int CustomerNumber
   {
      get { return this.custNumber; }
   }
}

public class CustomerNumberFormatter : IFormatProvider, ICustomFormatter
{   
   public object GetFormat(Type formatType)
   {
      if (formatType == typeof(ICustomFormatter))
         return this;
      return null;
   }

   public string Format(string format, object arg, IFormatProvider provider)
   {
      if (arg is Int32)
      {
         string custNumber = ((int) arg).ToString("D10");
         return custNumber.Substring(0, 4) + "-" + custNumber.Substring(4, 3) + 
                "-" + custNumber.Substring(7, 3);
      }
      else
      {
         return null;
      }
   }                   
}

public class Example
{
   public static void Main()
   {
      Customer customer = new Customer("A Plus Software", 903654);
      StringBuilder sb = new StringBuilder();
      sb.AppendFormat(new CustomerNumberFormatter(), "{0}: {1}", 
                      customer.CustomerNumber, customer.Name);
      Console.WriteLine(sb.ToString());
   }
}
// The example displays the following output:
//      0000-903-654: A Plus Software

.NET Framework

.NET Framework Client Profile

Bibliothèque de classes portable

.NET pour les applications du Windows Store

Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (rôle principal du serveur non pris en charge), Windows Server 2008 R2 (rôle principal du serveur pris en charge avec SP1 ou version ultérieure ; Itanium non pris en charge)

Référence

Autres ressources