This documentation is archived and is not being maintained.

Convert.ToString Method (Object, IFormatProvider)

.NET Framework 1.1

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

[Visual Basic]
Overloads Public Shared Function ToString( _
   ByVal value As Object, _
   ByVal provider As IFormatProvider _
) As String
[C#]
public static string ToString(
 object value,
 IFormatProvider provider
);
[C++]
public: static String* ToString(
 Object* value,
 IFormatProvider* provider
);
[JScript]
public static function ToString(
   value : Object,
 provider : IFormatProvider
) : String;

Parameters

value
An Object or a null reference (Nothing in Visual Basic).
provider
An IFormatProvider interface implementation that supplies culture-specific formatting information.

Return Value

The String representation of the value of value, or String.Empty if value is a null reference (Nothing in Visual Basic).

Remarks

provider enables the user to specify culture-specific conversion information about the contents of value. For example, if value is a String that represents a number, provider could supply culture-specific information about the notation used to represent that number.

The base types ignore provider; however, it is honored if value is a user-defined type that implements the IConvertible interface.

The return value is the result of invoking the IConvertible.ToString method of the underlying type of value if the underlying type implements the IConvertible interface; otherwise, the return value is the result of invoking the ToString method of the underlying type.

Example

[Visual Basic, C#, C++] The following code example converts a non-numeric Object and a boxed numeric value to String s with the ToString method, using an IFormatProvider object that displays the type of the format provider for which it is called. The example shows that for the non-numeric Object, the IFormatProvider object is not referenced.

[Visual Basic] 
' Example of Convert.ToString( non-numeric types, IFormatProvider ).
Imports System
Imports System.Globalization
Imports Microsoft.VisualBasic

' An instance of this class can be passed to methods that require 
' an IFormatProvider.
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

        ' Here, the type of argType is displayed, and GetFormat
        ' always returns Nothing.
        Console.Write( "{0,-40}", argType.ToString( ) )
        Return Nothing

    End Function 
End Class

Module ConvertNonNumericProviderDemo

    Sub Main( )

        ' Create an instance of the IFormatProvider.
        Dim provider    As New DummyProvider( )
        Dim converted   As String

        ' Convert these values using DummyProvider.
        Dim Int32A      As Integer  = -252645135   
        Dim DoubleA     As Double   = 61680.3855
        Dim ObjDouble   As Object   = CType( -98765.4321, Object )
        Dim DayTimeA    As DateTime = _
                            new DateTime( 2001, 9, 11, 13, 45, 0 )

        Dim BoolA       As Boolean  = True
        Dim StringA     As String   = "Qwerty"
        Dim CharA       As Char     = "$"c
        Dim TSpanA      As TimeSpan = New TimeSpan( 0, 18, 0 )
        Dim ObjOther    As Object   = CType( provider, Object )

        Console.WriteLine( "This example of " & _
            "Convert.ToString( non-numeric, IFormatProvider ) " & _
            vbCrLf & "generates the following output. The " & _
            "provider type, argument type, " & vbCrLf & "and " & _
            "argument value are displayed." )
        Console.WriteLine( vbCrLf & _
            "Note: The IFormatProvider object is not called for " & _
            "Boolean, String, " & vbCrLf & "Char, TimeSpan, " & _
            "and non-numeric Object." )

        ' The format provider is called for these conversions.
        Console.WriteLine( )
        converted =  Convert.ToString( Int32A, provider )
        Console.WriteLine( "Int32    {0}", converted )
        converted =  Convert.ToString( DoubleA, provider )
        Console.WriteLine( "Double   {0}", converted )
        converted =  Convert.ToString( ObjDouble, provider )
        Console.WriteLine( "Object   {0}", converted )
        converted =  Convert.ToString( DayTimeA, provider )
        Console.WriteLine( "DateTime {0}", converted )

        ' The format provider is not called for these conversions.
        Console.WriteLine( )
        converted =  Convert.ToString( BoolA, provider )
        Console.WriteLine( "Boolean  {0}", converted )
        converted =  Convert.ToString( StringA, provider )
        Console.WriteLine( "String   {0}", converted )
        converted =  Convert.ToString( CharA, provider )
        Console.WriteLine( "Char     {0}", converted )
        converted =  Convert.ToString( TSpanA, provider )
        Console.WriteLine( "TimeSpan {0}", converted )
        converted =  Convert.ToString( ObjOther, provider )
        Console.WriteLine( "Object   {0}", converted )

    End Sub
End Module

' This example of Convert.ToString( non-numeric, IFormatProvider )
' generates the following output. The provider type, argument type,
' and argument value are displayed.
'
' Note: The IFormatProvider object is not called for Boolean, String,
' Char, TimeSpan, and non-numeric Object.
' 
' System.Globalization.NumberFormatInfo   Int32    -252645135
' System.Globalization.NumberFormatInfo   Double   61680.3855
' System.Globalization.NumberFormatInfo   Object   -98765.4321
' System.Globalization.DateTimeFormatInfo DateTime 9/11/2001 1:45:00 PM
' 
' Boolean  True
' String   Qwerty
' Char     $
' TimeSpan 00:18:00
' Object   DummyProvider

[C#] 
// Example of Convert.ToString( non-numeric types, IFormatProvider ).
using System;
using System.Globalization;

// An instance of this class can be passed to methods that require 
// an IFormatProvider.
public class DummyProvider : IFormatProvider
{
    // Normally, GetFormat returns an object of the requested type
    // (usually itself) if it is able; otherwise, it returns Nothing. 
    public object GetFormat( Type argType )
    {
        // Here, the type of argType is displayed, and GetFormat
        // always returns Nothing.
        Console.Write( "{0,-40}", argType.ToString( ) );
        return null;
    }
}

class ConvertNonNumericProviderDemo
{
    static void Main( )
    {
        // Create an instance of the IFormatProvider.
        DummyProvider provider = new DummyProvider( );
        string converted;

        // Convert these values using DummyProvider.
        int      Int32A     = -252645135;
        double   DoubleA    = 61680.3855;
        object   ObjDouble  = (object)( -98765.4321 );
        DateTime DayTimeA   = new DateTime( 2001, 9, 11, 13, 45, 0 );

        bool     BoolA      = true;
        string   StringA    = "Qwerty";
        char     CharA      = '$';
        TimeSpan TSpanA     = new TimeSpan( 0, 18, 0 );
        object   ObjOther   = (object)provider;

        Console.WriteLine( "This example of " +
            "Convert.ToString( non-numeric, IFormatProvider ) \n" +
            "generates the following output. The provider type, " +
            "argument type, \nand argument value are displayed." );
        Console.WriteLine( "\nNote: The IFormatProvider object is " +
            "not called for Boolean, String, \nChar, TimeSpan, " +
            "and non-numeric Object." );

        // The format provider is called for these conversions.
        Console.WriteLine( );
        converted = Convert.ToString( Int32A, provider );
        Console.WriteLine( "int      {0}", converted );
        converted = Convert.ToString( DoubleA, provider );
        Console.WriteLine( "double   {0}", converted );
        converted = Convert.ToString( ObjDouble, provider );
        Console.WriteLine( "object   {0}", converted );
        converted = Convert.ToString( DayTimeA, provider );
        Console.WriteLine( "DateTime {0}", converted );

        // The format provider is not called for these conversions.
        Console.WriteLine( );
        converted = Convert.ToString( BoolA, provider );
        Console.WriteLine( "bool     {0}", converted );
        converted = Convert.ToString( StringA, provider );
        Console.WriteLine( "string   {0}", converted );
        converted = Convert.ToString( CharA, provider );
        Console.WriteLine( "char     {0}", converted );
        converted = Convert.ToString( TSpanA, provider );
        Console.WriteLine( "TimeSpan {0}", converted );
        converted = Convert.ToString( ObjOther, provider );
        Console.WriteLine( "object   {0}", converted );
    }
}

/*
This example of Convert.ToString( non-numeric, IFormatProvider )
generates the following output. The provider type, argument type,
and argument value are displayed.

Note: The IFormatProvider object is not called for Boolean, String,
Char, TimeSpan, and non-numeric Object.

System.Globalization.NumberFormatInfo   int      -252645135
System.Globalization.NumberFormatInfo   double   61680.3855
System.Globalization.NumberFormatInfo   object   -98765.4321
System.Globalization.DateTimeFormatInfo DateTime 9/11/2001 1:45:00 PM

bool     True
string   Qwerty
char     $
TimeSpan 00:18:00
object   DummyProvider

*/ 

[C++] 
// Example of Convert::ToString( non-numeric types, IFormatProvider ).
#using <mscorlib.dll>
using namespace System;
using namespace System::Globalization;

#define null (Object*)0

// An instance of this class can be passed to methods that require 
// an IFormatProvider.
__gc class DummyProvider : public IFormatProvider
{
    // Normally, GetFormat returns an object of the requested type
    // (usually itself) if it is able; otherwise, it returns Nothing. 
    public: Object* GetFormat( Type* argType )
    {
        // Here, the type of argType is displayed, and GetFormat
        // always returns Nothing.
        Console::Write( S"{0,-40}", argType->ToString( ) );
        return null;
    }
};

void main( )
{
    // Create an instance of the IFormatProvider.
    DummyProvider*  provider = new DummyProvider( );
    String*         converted;

    // Convert these values using DummyProvider.
    int         Int32A     = -252645135;
    double      DoubleA    = 61680.3855;
    Object*     ObjDouble  = __box( -98765.4321 );
    DateTime    DayTimeA   = DateTime( 2001, 9, 11, 13, 45, 0 );

    bool        BoolA      = true;
    String*     StringA    = S"Qwerty";
    Char        CharA      = '$';
    TimeSpan    TSpanA     = TimeSpan( 0, 18, 0 );
    Object*     ObjOther   = static_cast<Object*>( provider );

    Console::WriteLine( S"This example of " 
        S"Convert::ToString( non-numeric, IFormatProvider* ) \n" 
        S"generates the following output. The provider type, " 
        S"argument type, \nand argument value are displayed." );
    Console::WriteLine( S"\nNote: The IFormatProvider object is " 
        S"not called for Boolean, String, \nChar, TimeSpan, " 
        S"and non-numeric Object." );

    // The format provider is called for these conversions.
    Console::WriteLine( );
    converted = Convert::ToString( Int32A, provider );
    Console::WriteLine( S"int      {0}", converted );
    converted = Convert::ToString( DoubleA, provider );
    Console::WriteLine( S"double   {0}", converted );
    converted = Convert::ToString( ObjDouble, provider );
    Console::WriteLine( S"Object   {0}", converted );
    converted = Convert::ToString( DayTimeA, provider );
    Console::WriteLine( S"DateTime {0}", converted );

    // The format provider is not called for these conversions.
    Console::WriteLine( );
    converted = Convert::ToString( BoolA, provider );
    Console::WriteLine( S"bool     {0}", converted );
    converted = Convert::ToString( StringA, provider );
    Console::WriteLine( S"String   {0}", converted );
    converted = Convert::ToString( CharA, provider );
    Console::WriteLine( S"Char     {0}", converted );
    converted = Convert::ToString( __box( TSpanA ), provider );
    Console::WriteLine( S"TimeSpan {0}", converted );
    converted = Convert::ToString( ObjOther, provider );
    Console::WriteLine( S"Object   {0}", converted );
}

/*
This example of Convert::ToString( non-numeric, IFormatProvider* )
generates the following output. The provider type, argument type,
and argument value are displayed.

Note: The IFormatProvider object is not called for Boolean, String,
Char, TimeSpan, and non-numeric Object.

System.Globalization.NumberFormatInfo   int      -252645135
System.Globalization.NumberFormatInfo   double   61680.3855
System.Globalization.NumberFormatInfo   Object   -98765.4321
System.Globalization.DateTimeFormatInfo DateTime 9/11/2001 1:45:00 PM

bool     True
String   Qwerty
Char     $
TimeSpan 00:18:00
Object   DummyProvider
*/ 

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

See Also

Convert Class | Convert Members | System Namespace | Convert.ToString Overload List

Show: