Customizing Format Strings

Customizing Format Strings

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Developer's Guide

Customizing Format Strings

The .NET Framework supports extending its built-in formatting mechanism so you can create your own ToString method that accepts user-defined format strings, or create a format provider that invokes your own Format method to perform custom formatting of a type. You create your own ToString method by implementing the IFormattable interface, and your own Format method by implementing the ICustomFormatter and IFormatProvider interfaces.

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.

Adding Custom Format Strings for Custom Types

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 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 ToString method of the IFormattable interface takes a format string parameter and a format provider parameter. If the format string parameter is an empty string or null (Nothing in Visual Basic), perform default formatting. If the format provider is null, use a default format provider.

If a custom format string is passed to your custom version of ToString, perform the appropriate formatting; otherwise, 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 of Convert.ToString 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 System.Int32.ToString method.

Visual Basic

Public Class MyType
    Implements IFormattable
    ' Assign a value for the class.
    Private myValue As Integer    

    ' Add a constructor.
    Public Sub New(value As Integer)
        myValue = value
    End Sub

    ' Write a custom Format method for the type.
    Public Overloads Function ToString(format As String, _
                                       fp As IFormatProvider) As String _
                              Implements IFormattable.ToString

        If format.Equals("b") Then
            Return Convert.ToString(myValue, 2)
        Else
            Return myValue.ToString(format, fp)
        End If
    End Function
End Class

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);
            }
        else
            {
            return myValue.ToString(format, fp);
            }
    }
}

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

Visual Basic

Dim mtype As New MyType(42)
Dim myString As String = mtype.ToString("b", Nothing)
Dim yourString As String = mtype.ToString("d", Nothing)
Console.WriteLine(myString)
Console.WriteLine(yourString)
' The example produces the following output:
'       101010
'       42

MyType mtype = new MyType(42);
String myString = mtype.ToString("b", null);
String yourString = mtype.ToString("d", null);
Console.WriteLine(myString);
Console.WriteLine(yourString);
// The example produces the following output:
//       101010
//       42

Adding Custom Format Strings to Existing Types

You can control how an existing base type is formatted, and provide additional codes for formatting, by creating a format provider class that implements ICustomFormatter and IFormatProvider.

When you pass a format provider to the ToString method of a base type, the base type uses the passed format provider to define its formatting rules rather than the default format provider. To create a custom format provider, you should do the following:

Define a class that implements the two previously mentioned interfaces and overrides GetFormat and Format.
Pass that class into a method (like String.Format) that takes the IFormatProvider as a parameter. Doing so causes String.Format to recognize the custom format scheme defined in the new format provider class.

The following example defines a class that adds a custom Format method that can produce different base values of an integer.

Visual Basic

Public Class MyFormat
    Implements IFormatProvider
    Implements ICustomFormatter

    ' String.Format calls this method to get an instance of an
    ' ICustomFormatter to handle the formatting.
    Public Function GetFormat(service As Type) As Object _
    Implements IFormatProvider.GetFormat

        If service.ToString() = GetType(ICustomFormatter).ToString() Then
            Return Me
        Else
            Return Nothing
        End If
    End Function

    ' After String.Format gets the ICustomFormatter, it calls this format
    ' method on each argument.
    Public Function Format(theformat As String, arg As Object, _
                           provider As IFormatProvider) As String _
                    Implements ICustomFormatter.Format

        If theformat Is Nothing Then
            Return String.Format("{0}", arg)
        End If
        Dim i As Integer = theformat.Length
            ' If the object to be formatted supports the IFormattable
            ' interface, pass the format specifier to the 
            ' object's ToString method for formatting.
        If Not theformat.StartsWith("B") Then
            ' If the object to be formatted supports the IFormattable
            ' interface, pass the format specifier to the 
            ' object's ToString method for formatting.
            If TypeOf arg Is IFormattable Then
                return CType(arg, IFormattable).ToString(theformat, provider)
            ' If the object does not support IFormattable, 
            ' call the object's ToString method with no additional
            ' formatting. 
            ElseIf (arg IsNot Nothing) Then
                return arg.ToString()
            End If
        End If
        ' Uses the format string to
        ' form the output string.
        theformat = theformat.Trim(New Char() {"B"c})
        Dim b As Integer = Convert.ToInt32(theformat)
        Return Convert.ToString(CInt(arg), b)
    End Function
End Class

public class MyFormat : IFormatProvider, ICustomFormatter
{
    // String.Format calls this method to get an instance of an
    // ICustomFormatter to handle the formatting.
    public object GetFormat (Type service)
    {
        if (service == typeof (ICustomFormatter))
        {
            return this;
        }
        else
        {
            return null;
        }
    }
    // After String.Format gets the ICustomFormatter, it calls this format
    // method on each argument.
    public string Format(string format, object arg, IFormatProvider provider) 
    {
        if (format == null)
        {
            return String.Format ("{0}", arg);
        }
        // If the format is not a defined custom code,
        // use the formatting support in ToString.
        if (!format.StartsWith("B")) 
        {
            //If the object to be formatted supports the IFormattable
            //interface, pass the format specifier to the 
            //object's ToString method for formatting.
            if (arg is IFormattable) 
            {
                return ((IFormattable)arg).ToString(format, provider);
            } 
            //If the object does not support IFormattable, 
            //call the object's ToString method with no additional
            //formatting. 
            else if (arg != null) 
            {
                return arg.ToString();
            }
        }
        // Uses the format string to
        // form the output string.
        format = format.Trim (new char [] {'B'});
        int b = Convert.ToInt32 (format);
        return Convert.ToString ((int)arg, b);
    }
}

In the following example, the Format method uses the custom Format method defined in MyFormat to display the base 16 representation of MyInt.

Visual Basic

Dim myInt As Integer = 42
Dim myString As String = String.Format(New MyFormat(), _
                         "{0} in the custom B16 format is {1:B16}", _
                         New Object() {MyInt, MyInt})
Console.WriteLine(myString)
' The example displays the following output:
'      42 in the custom B16 format is 2a

int MyInt = 42;
string myString = String.Format(new MyFormat(), 
                         "{0} in the custom B16 format is {1:B16}", 
                         new object[] {MyInt, MyInt});
Console.WriteLine(myString);                               
// The example displays the following output: 
//       42 in custom B16 format is 2a

Reference

IFormattable

IFormatProvider

ICustomFormatter

Other Resources

Formatting Types