Customizing Format Strings

[Note: This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

The .NET Framework supports extending its built-in formatting mechanism by allowing you to create your own ToString method that accepts user-defined format strings. You create your own ToString method by implementing the IFormattable interface.

The information in this section is limited to adding custom format strings to user-defined types and existing base types, but the principles described can be applied to any type.

If you create your own custom type, you can add support for processing your own custom format strings by implementing the IFormattable interface and that interface's IFormattable.ToString method. This means you can control what format strings are recognized by your custom type. The benefit of implementing the IFormattable interface instead of merely adding a ToString method to your custom type is that you can guarantee users of your ToString method a predefined calling syntax and return type.

The IFormattable.ToString method takes a format string parameter and a format provider parameter. If the format string parameter is an empty string or null, the method should perform default formatting. If the format provider is null, the method should use a default format provider.

If a custom format string is passed to your custom version of ToString, your method should perform the appropriate formatting; otherwise, it should call a suitable .NET Framework method to perform standard formatting.

In the following example, the MyType custom type implements the IFormattable interface. If you create a new instance of the MyType class, and pass the "b" custom format string to the instance's ToString method, an overload ofToString(Int32, Int32) returns the binary (base 2) string representation of the value of the instance. If "b" is not passed, the value of the instance is formatted by its own ToString method; that is, integer myValue is formatted by the ToString(String) method.

public class MyType : IFormattable
   // Assign a value for the class.
   private int myValue;

   // Add a constructor.
   public MyType(int value)
      myValue = value;
   // Write a custom Format method for the type.
   public string ToString(string format, IFormatProvider fp)
      if (format.Equals("b"))
         return Convert.ToString(myValue, 2);
         return myValue.ToString(format, fp);

The following example demonstrates how the MyType class and "b" format string are used.

MyType mtype = new MyType(42);
String myString = mtype.ToString("b", null);
String yourString = mtype.ToString("d", null);
outputBlock.Text += myString + "\n";
outputBlock.Text += yourString + "\n";
// The example produces the following output:
//       101010
//       42