This documentation is archived and is not being maintained.

Convert.ToString Method (Object, IFormatProvider)

Converts the value of the specified object to its equivalent string representation using the specified culture-specific formatting information.

Namespace:  System
Assembly:  mscorlib (in mscorlib.dll)

Public Shared Function ToString ( _
	value As Object, _
	provider As IFormatProvider _
) As String


Type: System.Object
An object that supplies the value to convert, or Nothing.
Type: System.IFormatProvider
An object that supplies culture-specific formatting information.

Return Value

Type: System.String
The string representation of value, or String.Empty if value is Nothing.

If the value parameter implements the IConvertible interface, the method calls the IConvertible.ToString(IFormatProvider) implementation of value. Otherwise, if the value parameter implements the IFormattable interface, the method calls its IFormattable.ToString(String, IFormatProvider) implementation. If value implements neither interface, the method calls the value parameter's ToString() method.

The provider parameter is used if the value parameter implements the IConvertible or IFormattable interface. The provider parameter specifies culture-specific information used in the conversion of value. For example, if the value parameter is a negative decimal number, the provider parameter can supply culture-specific information about the notation used for the negative sign and decimal separator.

The following example defines a class named DummyProvider that simply intercepts method calls made by the ToString(Object, IFormatProvider) method to the provider parameter's IFormatProvider.GetFormat implementation, and then displays the type name of the object that the IFormatProvider.GetFormat method is expected to return. When the ToString(Object, IFormatProvider) method is passed a number of different data types in an object array, the output indicates whether the method actually uses the provider parameter with that particular data type. The output illustrates that the provider parameter is used when converting numeric and DateTime values to strings, but that it is not used with Boolean, character, string, or TimeSpan values.

Option Strict On

Imports System.Globalization

Public Class DummyProvider : Implements IFormatProvider
    ' Normally, GetFormat returns an object of the requested type
    ' (usually itself) if it is able; otherwise, it returns Nothing. 
    Public Function GetFormat(argType As Type) As Object _
        Implements IFormatProvider.GetFormat

        ' Display the type of argType and return Nothing.
        Console.Write( "{0,-25}", argType.Name)
        Return Nothing
    End Function 
End Class

Public Module Example
    Public Sub Main()
        ' Create an instance of the IFormatProvider.
        Dim provider  As New DummyProvider()

        ' Values to convert using DummyProvider
        Dim int32A As Integer  = -252645135   
        Dim doubleA As Double   = 61680.3855
        Dim objDouble As Object   = CObj(-98765.4321)
        Dim dayTimeA As DateTime = #9/11/2009 13:45#
        Dim boolA As Boolean = True
        Dim stringA As String = "Qwerty"
        Dim charA As Char = "$"c
        Dim tSpanA As New TimeSpan(0, 18, 0)
        Dim objOther As Object = provider

        Dim objects() As Object = { int32A, doubleA, objDouble, dayTimeA, _
                                    boolA, stringA, charA, tSpanA, objOther }

        ' Call Convert.ToString(Object, provider) method for each value.
        For Each value As Object In objects 
           Console.WriteLine("{0,-20}  -->  {1,20}", _
                             value, Convert.ToString(value, provider))    
    End Sub
End Module
' The example displays the following output:
'    NumberFormatInfo         -252645135            -->            -252645135
'    NumberFormatInfo         61680.3855            -->            61680.3855
'    NumberFormatInfo         -98765.4321           -->           -98765.4321
'    DateTimeFormatInfo       9/11/2009 1:45:00 PM  -->  9/11/2009 1:45:00 PM
'    True                  -->                  True
'    Qwerty                -->                Qwerty
'    $                     -->                     $
'    00:18:00              -->              00:18:00
'    DummyProvider         -->         DummyProvider

The following example defines a Temperature class that overrides the Object.ToString method but does not implement the IConvertible interface. The example illustrates how calls to the Convert.ToString(Object, IFormatProvider) method, in turn, call the Temperature.ToString method.

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
         Return Me.m_Temp
      End Get   
   End Property

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

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

   Public Overrides Function ToString() As String
      Return m_Temp.ToString("N2") & " °C"
   End Function
End Class

Module Example
   Public Sub Main()
      Dim cold As New Temperature(-40)
      Dim freezing As New Temperature(0)
      Dim boiling As New Temperature(100)

      Console.WriteLine(Convert.ToString(cold, Nothing))
      Console.WriteLine(Convert.ToString(freezing, Nothing))
      Console.WriteLine(Convert.ToString(boiling, Nothing))
   End Sub
End Module
' The example displays the following output:
'       -40.00 °C
'       0.00 °C
'       100.00 °C

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.