Formatting Types

The basic mechanism for formatting is the default implementation of the Object.ToString method, which is discussed in the Default Formatting Using the ToString Method section later in this topic. However, the .NET Framework provides several ways to modify and extend its default formatting support. These include the following:

• Overriding the Object.ToString method to define a custom string representation of an object’s value. For more information, see the Overriding the ToString Method section later in this topic.

• Defining format specifiers that enable the string representation of an object’s value to take multiple forms. For example, the "X" format specifier in the following statement converts an integer to the string representation of a hexadecimal value.

  C#

  VB

  Copy

  Dim integerValue As Integer = 60312
  Console.WriteLine(integerValue.ToString("X"))   ' Displays EB98.
  

  For more information about format specifiers, see the ToString Method and Format Strings section.

• Using format providers to take advantage of the formatting conventions of a specific culture. For example, the following statement displays a currency value by using the formatting conventions of the en-US culture.

  C#

  VB

  Copy

  Dim cost As Double = 1632.54
  Console.WriteLine(cost.ToString("C", New System.Globalization.CultureInfo("en-US")))
  ' The example displays the following output: 
  '       $1,632.54
  

  For more information about formatting with format providers, see the Format Providers and the IFormatProvider Interface section.

• Implementing the IFormattable interface to support both string conversion with the Convert class and composite formatting. For more information, see the IFormattable Interface section.

• Using composite formatting to embed the string representation of a value in a larger string. For more information, see the Composite Formatting section.

• Implementing ICustomFormatter and IFormatProvider to provide a complete custom formatting solution. For more information, see the Custom Formatting with ICustomFormatter section.

The following sections examine these methods for converting an object to its string representation.

Back to top

Every type that is derived from System.Object automatically inherits a parameterless ToString method, which returns the name of the type by default. The following example illustrates the default ToString method. It defines a class named Automobile that has no implementation. When the class is instantiated and its ToString method is called, it displays its type name.

Public Class Automobile
   ' No implementation. All members are inherited from Object. 
End Class 

Module Example
   Public Sub Main()
      Dim firstAuto As New Automobile()
      Console.WriteLine(firstAuto)
   End Sub 
End Module 
' The example displays the following output: 
'       Automobile

Caution
Starting with , the Windows Runtime includes an IStringable interface with a single method, IStringable.ToString, which provides default formatting support. However, we recommend that managed types do not implement the IStringable interface. For more information, see "The Windows Runtime and the IStringable Interface" section on the Object.ToString reference page.

Because all types other than interfaces are derived from Object, this functionality is automatically provided to your custom classes or structures. However, the functionality offered by the default ToString method, is limited: Although it identifies the type, it fails to provide any information about an instance of the type. To provide a string representation of an object that provides information about that object, you must override the ToString method.

Note
Structures inherit from ValueType, which in turn is derived from Object. Although ValueType overrides Object.ToString, its implementation is identical.

Back to top

Displaying the name of a type is often of limited use and does not allow consumers of your types to differentiate one instance from another. However, you can override the ToString method to provide a more useful representation of an object’s value. The following example defines a Temperature object and overrides its ToString method to display the temperature in degrees Celsius.

Public Class Temperature
   Private temp As Decimal 

   Public Sub New(temperature As Decimal)
      Me.temp = temperature
   End Sub 

   Public Overrides Function ToString() As String 
      Return Me.temp.ToString("N1") + "°C"    
   End Function 
End Class 

Module Example
   Public Sub Main()
      Dim currentTemperature As New Temperature(23.6d)
      Console.WriteLine("The current temperature is {0}.", currentTemperature)
   End Sub 
End Module 
' The example displays the following output: 
'       The current temperature is 23.6°C.

In the .NET Framework, the ToString method of each primitive value type has been overridden to display the object’s value instead of its name. The following table shows the override for each primitive type. Note that most of the overridden methods call another overload of the ToString method and pass it the "G" format specifier, which defines the general format for its type, and an IFormatProvider object that represents the current culture.

Back to top

Relying on the default ToString method or overriding ToString is appropriate when an object has a single string representation. However, the value of an object often has multiple representations. For example, a temperature can be expressed in degrees Fahrenheit, degrees Celsius, or kelvins. Similarly, the integer value 10 can be represented in numerous ways, including 10, 10.0, 1.0e01, or $10.00.

To enable a single value to have multiple string representations, the .NET Framework uses format strings. A format string is a string that contains one or more predefined format specifiers, which are single characters or groups of characters that define how the ToString method should format its output. The format string is then passed as a parameter to the object's ToString method and determines how the string representation of that object's value should appear.

All numeric types, date and time types, and enumeration types in the .NET Framework support a predefined set of format specifiers. You can also use format strings to define multiple string representations of your application-defined data types.

Dim thisDay As DayOfWeek = DayOfWeek.Monday
Dim formatStrings() As String = {"G", "F", "D", "X"}

For Each formatString As String In formatStrings
   Console.WriteLine(thisDay.ToString(formatString))
Next 
' The example displays the following output: 
'       Monday 
'       Monday 
'       1 
'       00000001

Dim byteValues() As Byte = { 12, 163, 255 }
For Each byteValue As Byte In byteValues
   Console.WriteLine(byteValue.ToString("X4"))
Next 
' The example displays the following output: 
'       000C 
'       00A3 
'       00FF

Imports System.Globalization

Module Example
   Public Sub Main()
      Dim date1 As Date = #6/30/2009#
      Console.WriteLine("D Format Specifier:     {0:D}", date1)
      Dim longPattern As String = CultureInfo.CurrentCulture.DateTimeFormat.LongDatePattern
      Console.WriteLine("'{0}' custom format string:     {1}", _
                        longPattern, date1.ToString(longPattern))
   End Sub 
End Module 
' The example displays the following output when run on a system whose 
' current culture is en-US: 
'    D Format Specifier:     Tuesday, June 30, 2009 
'    'dddd, MMMM dd, yyyy' custom format string:     Tuesday, June 30, 2009

Public Class Temperature
   Private m_Temp As Decimal 

   Public Sub New(temperature As Decimal)
      Me.m_Temp = temperature
   End Sub 

   Public ReadOnly Property Celsius() As Decimal 
      Get 
         Return Me.m_Temp
      End Get    
   End Property 

   Public ReadOnly Property Kelvin() As Decimal 
      Get 
         Return Me.m_Temp + 273.15d   
      End Get 
   End Property 

   Public ReadOnly Property Fahrenheit() As Decimal 
      Get 
         Return Math.Round(CDec(Me.m_Temp * 9 / 5 + 32), 2)
      End Get       
   End Property 

   Public Overrides Function ToString() As String 
      Return Me.ToString("C")
   End Function 

   Public Overloads Function ToString(format As String) As String   
      ' Handle null or empty string. 
      If String.IsNullOrEmpty(format) Then format = "C" 
      ' Remove spaces and convert to uppercase.
      format = format.Trim().ToUpperInvariant()      

      ' Convert temperature to Fahrenheit and return string. 
      Select Case format
         Case "F" 
            Return Me.Fahrenheit.ToString("N2") & " °F" 
         ' Convert temperature to Kelvin and return string. 
         Case "K" 
            Return Me.Kelvin.ToString("N2") & " K" 
         ' Return temperature in Celsius. 
         Case "C" 
            Return Me.Celsius.ToString("N2") & " °C" 
         Case Else 
            Throw New FormatException(String.Format("The '{0}' format string is not supported.", format))
      End Select       
   End Function 
End Class 

Public Module Example
   Public Sub Main()
      Dim temp1 As New Temperature(0d)
      Console.WriteLine(temp1.ToString())
      Console.WriteLine(temp1.ToString("C"))
      Console.WriteLine(temp1.ToString("F"))
      Console.WriteLine(temp1.ToString("K"))
      Dim temp2 As New Temperature(-40d)
      Console.WriteLine(temp2.ToString())
      Console.WriteLine(temp2.ToString("C"))
      Console.WriteLine(temp2.ToString("F"))
      Console.WriteLine(temp2.ToString("K"))
      Dim temp3 As New Temperature(16d)
      Console.WriteLine(temp3.ToString())
      Console.WriteLine(temp3.ToString("C"))
      Console.WriteLine(temp3.ToString("F"))
      Console.WriteLine(temp3.ToString("K"))

      Console.WriteLine(String.Format("The temperature is now {0:F}.", temp3))
   End Sub 
End Module 
' The example displays the following output: 
'       0.00 °C 
'       0.00 °C 
'       32.00 °F 
'       273.15 K 
'       -40.00 °C 
'       -40.00 °C 
'       -40.00 °F 
'       233.15 K 
'       16.00 °C 
'       16.00 °C 
'       60.80 °F 
'       289.15 K 
'       The temperature is now 16.00 °C.

Dim date1 As Date = #09/08/2009#
Console.WriteLine(date1.ToString("%M"))      ' Displays 9

Dim customFormat As String = "MMMM dd, yyyy (dddd)" 
Dim date1 As Date = #8/28/2009#
Console.WriteLine(date1.ToString(customFormat))   
' The example displays the following output if run on a system 
' whose language is English: 
'       August 28, 2009 (Friday)      

Module Example
   Public Sub Main()
      Dim number As Long = 8009999999
      Dim fmt As String = "000-000-0000"
      Console.WriteLine(number.ToString(fmt))
   End Sub 
End Module 
' The example displays the following output: 

' The example displays the following output: 
'       800-999-9999

Although format specifiers let you customize the formatting of objects, producing a meaningful string representation of objects often requires additional formatting information. For example, formatting a number as a currency value by using either the "C" standard format string or a custom format string such as "$ #,#.00" requires, at a minimum, information about the correct currency symbol, group separator, and decimal separator to be available to include in the formatted string. In the .NET Framework, this additional formatting information is made available through the IFormatProvider interface, which is provided as a parameter to one or more overloads of the ToString method of numeric types and date and time types. IFormatProvider implementations are used in the .NET Framework to support culture-specific formatting. The following example illustrates how the string representation of an object changes when it is formatted with three IFormatProvider objects that represent different cultures.

Imports System.Globalization

Public Module Example
   Public Sub Main()
      Dim value As Decimal = 1603.42d
      Console.WriteLine(value.ToString("C3", New CultureInfo("en-US")))
      Console.WriteLine(value.ToString("C3", New CultureInfo("fr-FR")))
      Console.WriteLine(value.ToString("C3", New CultureInfo("de-DE")))
   End Sub 
End Module 
' The example displays the following output: 
'       $1,603.420 
'       1 603,420 € 
'       1.603,420 €

The IFormatProvider interface includes one method, GetFormat(Type), which has a single parameter that specifies the type of object that provides formatting information. If the method can provide an object of that type, it returns it. Otherwise, it returns a null reference (Nothing in Visual Basic).

IFormatProvider.GetFormat is a callback method. When you call a ToString method overload that includes an IFormatProvider parameter, it calls the GetFormat method of that IFormatProvider object. The GetFormat method is responsible for returning an object that provides the necessary formatting information, as specified by its formatType parameter, to the ToString method.

A number of formatting or string conversion methods include a parameter of type IFormatProvider, but in many cases the value of the parameter is ignored when the method is called. The following table lists some of the formatting methods that use the parameter and the type of the Type object that they pass to the IFormatProvider.GetFormat method.

Note

The ToString methods of the numeric types and date and time types are overloaded, and only some of the overloads include an IFormatProvider parameter. If a method does not have a parameter of type IFormatProvider, the object that is returned by the CultureInfo.CurrentCulture property is passed instead. For example, a call to the default Int32.ToString method ultimately results in a method call such as the following: Int32.ToString("G", System.Globalization.CultureInfo.CurrentCulture).

The .NET Framework provides three classes that implement IFormatProvider:

• DateTimeFormatInfo , a class that provides formatting information for date and time values for a specific culture. Its IFormatProvider.GetFormat implementation returns an instance of itself.

• NumberFormatInfo , a class that provides numeric formatting information for a specific culture. Its IFormatProvider.GetFormat implementation returns an instance of itself.

• CultureInfo . Its IFormatProvider.GetFormat implementation can return either a NumberFormatInfo object to provide numeric formatting information or a DateTimeFormatInfo object to provide formatting information for date and time values.

You can also implement your own format provider to replace any one of these classes. However, your implementation’s GetFormat method must return an object of the type listed in the previous table if it has to provide formatting information to the ToString method.

Back to top

Imports System.Globalization
Imports System.Threading 

Module Example
   Public Sub Main()
      Dim cultureNames() As String = { "en-US", "fr-FR", "es-MX", "de-DE" }
      Dim value As Decimal = 1043.17d 

      For Each cultureName In cultureNames
         ' Change the current thread culture.
         Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName)
         Console.WriteLine("The current culture is {0}", 
                           Thread.CurrentThread.CurrentCulture.Name)
         Console.WriteLine(value.ToString("C2"))
         Console.WriteLine()
      Next                   
   End Sub 
End Module 
' The example displays the following output: 
'       The current culture is en-US 
'       $1,043.17 
'        
'       The current culture is fr-FR 
'       1 043,17 € 
'        
'       The current culture is es-MX 
'       $1,043.17 
'        
'       The current culture is de-DE 
'       1.043,17 €

Imports System.Globalization

Module Example
   Public Sub Main()
      Dim value As Double = 1043.62957
      Dim cultureNames() As String = { "en-US", "en-GB", "ru", "fr" }

      For Each name In cultureNames
         Dim nfi As NumberFormatInfo = CultureInfo.CreateSpecificCulture(name).NumberFormat
         Console.WriteLine("{0,-6} {1}", name + ":", value.ToString("N3", nfi))
      Next    
   End Sub 
End Module 
' The example displays the following output: 
'       en-US: 1,043.630 
'       en-GB: 1,043.630 
'       ru:    1 043,630 
'       fr:    1 043,630

Imports System.Globalization
Imports System.Threading 

Module Example
   Public Sub Main()
      Dim cultureNames() As String = { "en-US", "fr-FR", "es-MX", "de-DE" }
      Dim dateToFormat As Date = #5/28/2012 11:30AM#

      For Each cultureName In cultureNames
         ' Change the current thread culture.
         Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName)
         Console.WriteLine("The current culture is {0}", 
                           Thread.CurrentThread.CurrentCulture.Name)
         Console.WriteLine(dateToFormat.ToString("F"))
         Console.WriteLine()
      Next                   
   End Sub 
End Module 
' The example displays the following output: 
'       The current culture is en-US 
'       Monday, May 28, 2012 11:30:00 AM 
'        
'       The current culture is fr-FR 
'       lundi 28 mai 2012 11:30:00 
'        
'       The current culture is es-MX 
'       lunes, 28 de mayo de 2012 11:30:00 a.m. 
'        
'       The current culture is de-DE 
'       Montag, 28. Mai 2012 11:30:00 

Imports System.Globalization

Module Example
   Public Sub Main()
      Dim dat1 As Date = #5/28/2012 11:30AM#
      Dim cultureNames() As String = { "en-US", "en-GB", "ru", "fr" }

      For Each name In cultureNames
         Dim dtfi As DateTimeFormatInfo = CultureInfo.CreateSpecificCulture(name).DateTimeFormat
         Console.WriteLine("{0}: {1}", name, dat1.ToString(dtfi))
      Next    
   End Sub 
End Module 
' The example displays the following output: 
'       en-US: 5/28/2012 11:30:00 AM 
'       en-GB: 28/05/2012 11:30:00 
'       ru: 28.05.2012 11:30:00 
'       fr: 28/05/2012 11:30:00

Typically, types that overload the ToString method with a format string and an IFormatProvider parameter also implement the IFormattable interface. This interface has a single member, IFormattable.ToString(String, IFormatProvider), that includes both a format string and a format provider as parameters.

Implementing the IFormattable interface for your application-defined class offers two advantages:

• Support for string conversion by the Convert class. Calls to the Convert.ToString(Object) and Convert.ToString(Object, IFormatProvider) methods call your IFormattable implementation automatically.

• Support for composite formatting. If a format item that includes a format string is used to format your custom type, the common language runtime automatically calls your IFormattable implementation and passes it the format string. For more information about composite formatting with methods such as String.Format or Console.WriteLine, see the Composite Formatting section.

The following example defines a Temperature class that implements the IFormattable interface. It supports the "C" or "G" format specifiers to display the temperature in Celsius, the "F" format specifier to display the temperature in Fahrenheit, and the "K" format specifier to display the temperature in Kelvin.

Imports System.Globalization

Public Class Temperature : Implements IFormattable
   Private m_Temp As Decimal 

   Public Sub New(temperature As Decimal)
      Me.m_Temp = temperature
   End Sub 

   Public ReadOnly Property Celsius() As Decimal 
      Get 
         Return Me.m_Temp
      End Get    
   End Property 

   Public ReadOnly Property Kelvin() As Decimal 
      Get 
         Return Me.m_Temp + 273.15d   
      End Get 
   End Property 

   Public ReadOnly Property Fahrenheit() As Decimal 
      Get 
         Return Math.Round(CDec(Me.m_Temp * 9 / 5 + 32), 2)
      End Get       
   End Property 

   Public Overrides Function ToString() As String 
      Return Me.ToString("G", Nothing)
   End Function 

   Public Overloads Function ToString(format As String) As String 
      Return Me.ToString(format, Nothing)
   End Function 

   Public Overloads Function ToString(format As String, provider As IFormatProvider) As String _  
      Implements IFormattable.ToString

      ' Handle null or empty arguments. 
      If String.IsNullOrEmpty(format) Then format = "G" 
      ' Remove any white space and convert to uppercase.
      format = format.Trim().ToUpperInvariant()

      If provider Is Nothing Then provider = NumberFormatInfo.CurrentInfo

      Select Case format
         ' Convert temperature to Fahrenheit and return string. 
         Case "F" 
            Return Me.Fahrenheit.ToString("N2", provider) & "°F" 
         ' Convert temperature to Kelvin and return string. 
         Case "K" 
            Return Me.Kelvin.ToString("N2", provider) & "K" 
         ' Return temperature in Celsius. 
         Case "C", "G" 
            Return Me.Celsius.ToString("N2", provider) & "°C" 
         Case Else 
            Throw New FormatException(String.Format("The '{0}' format string is not supported.", format))
      End Select       
   End Function 
End Class

The following example instantiates a Temperature object. It then calls the ToString method and uses several composite format strings to obtain different string representations of a Temperature object. Each of these method calls, in turn, calls the IFormattable implementation of the Temperature class.

Public Module Example
   Public Sub Main()
      Dim temp1 As New Temperature(22d)
      Console.WriteLine(Convert.ToString(temp1, New CultureInfo("ja-JP")))
      Console.WriteLine("Temperature: {0:K}", temp1)
      Console.WriteLine("Temperature: {0:F}", temp1)
      Console.WriteLine(String.Format(New CultureInfo("fr-FR"), "Temperature: {0:F}", temp1)) 
   End Sub 
End Module 
' The example displays the following output: 
'       22.00°C 
'       Temperature: 295.15°K 
'       Temperature: 71.60°F 
'       Temperature: 71,60°F

Back to top

Some methods, such as String.Format and StringBuilder.AppendFormat, support composite formatting. A composite format string is a kind of template that returns a single string that incorporates the string representation of zero, one, or more objects. Each object is represented in the composite format string by an indexed format item. The index of the format item corresponds to the position of the object that it represents in the method's parameter list. Indexes are zero-based. For example, in the following call to the String.Format method, the first format item, {0:D}, is replaced by the string representation of thatDate; the second format item, {1}, is replaced by the string representation of item1; and the third format item, {2:C2}, is replaced by the string representation of item1.Value.

result = String.Format("On {0:d}, the inventory of {1} was worth {2:C2}.", _
                       thatDate, item1, item1.Value)
Console.WriteLine(result)                            
' The example displays output like the following if run on a system 
' whose current culture is en-US: 
'       On 5/1/2009, the inventory of WidgetA was worth $107.44.

For more information about composite formatting, see Composite Formatting.

Back to top

Some composite formatting methods, such as String.Format(IFormatProvider, String, Object()) and StringBuilder.AppendFormat(IFormatProvider, String, Object()),include a format provider parameter that supports custom formatting. When the formatting method is called, it passes a Type object that represents an ICustomFormatter interface to the format provider’s GetFormat method. The GetFormat method is then responsible for returning the ICustomFormatter implementation that provides custom formatting.

The ICustomFormatter interface has a single method, Format(String, Object, IFormatProvider), that is called automatically by a composite formatting method, once for each format item in a composite format string. The Format(String, Object, IFormatProvider) method has three parameters: a format string, which represents the formatString argument in a format item, an object to format, and an IFormatProvider object that provides formatting services. Typically, the class that implements ICustomFormatter also implements IFormatProvider, so this last parameter is a reference to the custom formatting class itself. The method returns a custom formatted string representation of the object to be formatted. If the method cannot format the object, it should return a null reference (Nothing in Visual Basic).

The following example provides an ICustomFormatter implementation named ByteByByteFormatter that displays integer values as a sequence of two-digit hexadecimal values followed by a space.

Public Class ByteByByteFormatter : Implements IFormatProvider, ICustomFormatter
   Public Function GetFormat(formatType As Type) As Object _
                   Implements IFormatProvider.GetFormat
      If formatType Is GetType(ICustomFormatter) Then 
         Return Me 
      Else 
         Return Nothing 
      End If 
   End Function 

   Public Function Format(fmt As String, arg As Object, 
                          formatProvider As IFormatProvider) As String _
                          Implements ICustomFormatter.Format

      If Not formatProvider.Equals(Me) Then Return Nothing 

      ' Handle only hexadecimal format string. 
      If Not fmt.StartsWith("X") Then  
            Return Nothing 
      End If 

      ' Handle only integral types. 
      If Not typeof arg Is Byte AndAlso 
         Not typeof arg Is Int16 AndAlso 
         Not typeof arg Is Int32 AndAlso 
         Not typeof arg Is Int64 AndAlso 
         Not typeof arg Is SByte AndAlso 
         Not typeof arg Is UInt16 AndAlso 
         Not typeof arg Is UInt32 AndAlso 
         Not typeof arg Is UInt64 Then _
            Return Nothing 

      Dim bytes() As Byte = BitConverter.GetBytes(arg)
      Dim output As String = Nothing 

      For ctr As Integer = bytes.Length - 1 To 0 Step -1
         output += String.Format("{0:X2} ", bytes(ctr))   
      Next 

      Return output.Trim()
   End Function 
End Class

The following example uses the ByteByByteFormatter class to format integer values. Note that the ICustomFormatter.Format method is called more than once in the second String.Format(IFormatProvider, String, Object()) method call, and that the default NumberFormatInfo provider is used in the third method call because the .ByteByByteFormatter.Format method does not recognize the "N0" format string and returns a null reference (Nothing in Visual Basic).

Public Module Example
   Public Sub Main()
      Dim value As Long = 3210662321 
      Dim value1 As Byte = 214
      Dim value2 As Byte = 19

      Console.WriteLine((String.Format(New ByteByByteFormatter(), "{0:X}", value)))
      Console.WriteLine((String.Format(New ByteByByteFormatter(), "{0:X} And {1:X} = {2:X} ({2:000})", 
                                      value1, value2, value1 And value2)))                                
      Console.WriteLine(String.Format(New ByteByByteFormatter(), "{0,10:N0}", value))
   End Sub 
End Module 
' The example displays the following output: 
'       00 00 00 00 BF 5E D1 B1 
'       00 D6 And 00 13 = 00 12 (018) 
'       3,210,662,321

Back to top

Back to top

System.IFormattable

System.IFormatProvider

System.ICustomFormatter