Export (0) Print
Expand All

Convert Class

Updated: April 2009

Converts a base data type to another base data type.

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

public final class Convert

The static methods of the Convert class are used to support conversion to and from the base data types in the .NET Framework. The supported base types are Boolean, Char, SByte, Byte, Int16, Int32, Int64, UInt16, UInt32, UInt64, Single, Double, Decimal, DateTime and String.

Conversions to and from Base Types

A conversion method exists to convert every base type to every other base type. However, the actual call to a particular conversion method can produce one of five outcomes, depending on the value of the base type at run time and the target base type. These five outcomes are:

  • No conversion. This occurs when an attempt is made to convert from a type to itself (for example, by calling Convert.ToInt32(Int32) with an argument of type Int32). In this case, the method simply returns an instance of the original type.

  • An InvalidCastException. This occurs when a particular conversion is not supported. An InvalidCastException is thrown for the following conversions:

  • A FormatException. This occurs when the attempt to convert a string value to any other base type fails because the string is not in the proper format. The exception is thrown for the following conversions:

    • A string to be converted to a Boolean value does not equal Boolean.TrueString or Boolean.FalseString.

    • A string to be converted to a Char value consists of multiple characters.

    • A string to be converted to any numeric type is not recognized as a valid number.

    • A string to be converted to a DateTime is not recognized as a valid date and time value.

  • A successful conversion. For conversions between two different base types not listed in the previous outcomes, all widening conversions as well as all narrowing conversions that do not result in a loss of data will succeed and the method will return a value of the targeted base type.

  • An OverflowException. This occurs when a narrowing conversion results in a loss of data. For example, trying to convert a Int32 instance whose value is 10000 to a Byte type throws an OverflowException because 10000 is outside the range of the Byte data type.

An exception will not be thrown if the conversion of a numeric type results in a loss of precision (that is, the loss of some least significant digits). However, an exception will be thrown if the result is larger than can be represented by the particular conversion method's return value type.

For example, when a Double is converted to a Single, a loss of precision might occur but no exception is thrown. However, if the magnitude of the Double is too large to be represented by a Single, an overflow exception is thrown.

Conversions from Custom Objects to Base Types

In addition to supporting conversions between the base types, the Convert method supports conversion of any custom type to any base type. To do this, the custom type must implement the IConvertible interface, which defines methods for converting the implementing type to each of the base types. Conversions that are not supported by a particular type should throw an InvalidCastException.

When the ChangeType method is passed a custom type as its first parameter, or when the Convert.ToType method (such as Convert.ToInt32(Object) or Convert.ToDouble(Object, IFormatProvider) is called and passed an instance of a custom type as its first parameter, the Convert method, in turn, calls the custom type's IConvertible implementation to perform the conversion. For more information, see Converting Overview.

Culture-Specific Formatting Information

All the base type conversion methods and the ChangeType method include overloads that have a parameter of type IFormatProvider. For example, the Convert.ToBoolean method has the following two overloads:

The IFormatProvider parameter can supply culture-specific formatting information to assist the conversion process. However, it is ignored by most of the base type conversion methods. It is used only by the following base type conversion methods:

However, any user-defined type that implements IConvertible can make use of the IFormatProvider parameter.

Other Conversion Methods

A set of methods support converting an array of bytes to and from a String or to and from an array of Unicode characters consisting of base-64 digit characters. Data expressed as base-64 digits can be easily conveyed over data channels that can only transmit 7-bit characters.

The following example demonstrates some of the conversion methods in the Convert class, including ToInt32, ToBoolean, and ToString.

No code example is currently available or this language may not be supported.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

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

.NET Framework

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

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0

Date

History

Reason

April 2009

Extensively revised and expanded the Remarks section for the class and individual members, and added examples for individual members.

Information enhancement.

Community Additions

ADD
Show:
© 2014 Microsoft