Edit

CType Function (Visual Basic)

  • Article

Returns the result of explicitly converting an expression to a specified data type, object, structure, class, or interface.

Syntax

CType(expression, typename)

Parts

expression Any valid expression. If the value of expression is outside the range allowed by typename, Visual Basic throws an exception.

typename Any expression that is legal within an As clause in a Dim statement, that is, the name of any data type, object, structure, class, or interface.

Remarks

Tip

You can also use the following functions to perform a type conversion:

  • Type conversion functions such as CByte, CDbl, and CInt that perform a conversion to a specific data type. For more information, see Type Conversion Functions.
  • DirectCast Operator or TryCast Operator. These operators require that one type inherit from or implement the other type. They can provide somewhat better performance than CType when converting to and from the Object data type.

CType is compiled inline, which means that the conversion code is part of the code that evaluates the expression. In some cases, the code runs faster because no procedures are called to perform the conversion.

If no conversion is defined from expression to typename (for example, from Integer to Date), Visual Basic displays a compile-time error message.

If a conversion fails at run time, the appropriate exception is thrown. If a narrowing conversion fails, an OverflowException is the most common result. If the conversion is undefined, an InvalidCastException in thrown. For example, this can happen if expression is of type Object and its run-time type has no conversion to typename.

If the data type of expression or typename is a class or structure you've defined, you can define CType on that class or structure as a conversion operator. This makes CType act as an overloaded operator. If you do this, you can control the behavior of conversions to and from your class or structure, including the exceptions that can be thrown.

Conversion Keywords

A comparison of the type conversion keywords is as follows.

Keyword Data types Argument relationship Run-time failure
CType Any data types Widening or narrowing conversion must be defined between the two data types Throws InvalidCastException
DirectCast Operator Any data types One type must inherit from or implement the other type Throws InvalidCastException
TryCast Reference types only One type must inherit from or implement the other type Returns Nothing

Overloading

The CType operator can also be overloaded on a class or structure defined outside your code. If your code converts to or from such a class or structure, be sure you understand the behavior of its CType operator. For more information, see Operator Procedures.

Converting Dynamic Objects

Type conversions of dynamic objects are performed by user-defined dynamic conversions that use the TryConvert or BindConvert methods. If you're working with dynamic objects, use the CTypeDynamic method to convert the dynamic object.

Example

The following example uses the CType function to convert an expression to the Single data type.

Dim testNumber As Long = 1000
' The following line of code sets testNewType to 1000.0.
Dim testNewType As Single = CType(testNumber, Single)

For additional examples, see Implicit and Explicit Conversions.

See also