System.Convert Class

Converts a base data type to another base data type.

See Also: Convert Members


public static 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 bool, char, sbyte, byte, short, int, long, ushort, uint, ulong, float, 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:

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 float, 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 float, 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 erload:System.Convert.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 Type Conversion in the .NET Framework.

Culture-Specific Formatting Information

All the base type conversion methods and the erload:System.Convert.ChangeType method include overloads that have a parameter of type IFormatProvider. For example, the erload:System.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. If a null IFormatProvider argument is passed to these methods, the System.Globalization.CultureInfo object that represents the current thread culture is used.

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.

Thread Safety

All public static members of this type are safe for multithreaded operations. No instance members are guaranteed to be thread safe.


Namespace: System
Assembly: mscorlib (in mscorlib.dll)
Assembly Versions: 1.0.5000.0,,