Type Conversion Functions (Visual Basic)

These functions are compiled inline, meaning the conversion code is part of the code that evaluates the expression. Sometimes there is no call to a procedure to accomplish the conversion, which improves performance. Each function coerces an expression to a specific data type.

Syntax

CBool(expression)
CByte(expression)
CChar(expression)
CDate(expression)
CDbl(expression)
CDec(expression)
CInt(expression)
CLng(expression)
CObj(expression)
CSByte(expression)
CShort(expression)
CSng(expression)
CStr(expression)
CUInt(expression)
CULng(expression)
CUShort(expression)

Part

expression
Required. Any expression of the source data type.

Return Value Data Type

The function name determines the data type of the value it returns, as shown in the following table.

Function name	Return data type	Range for expression argument
CBool	Boolean Data Type	Any valid Char or String or numeric expression.
CByte	Byte Data Type	Byte.MinValue (0) through Byte.MaxValue (255) (unsigned); fractional parts are rounded.1 Starting with Visual Basic 15.8, Visual Basic optimizes the performance of floating-point to byte conversion with the CByte function; see the Remarks section for more information. See the CInt Example section for an example.
CChar	Char Data Type	Any valid Char or String expression; only first character of a String is converted; value can be 0 through 65535 (unsigned).
CDate	Date Data Type	Any valid representation of a date and time.
CDbl	Double Data Type	-1.79769313486231570E+308 through -4.94065645841246544E-324 for negative values; 4.94065645841246544E-324 through 1.79769313486231570E+308 for positive values.
CDec	Decimal Data Type	+/-79,228,162,514,264,337,593,543,950,335 for zero-scaled numbers, that is, numbers with no decimal places. For numbers with 28 decimal places, the range is +/-7.9228162514264337593543950335. The smallest possible non-zero number is 0.0000000000000000000000000001 (+/-1E-28).
CInt	Integer Data Type	Int32.MinValue (-2,147,483,648) through Int32.MaxValue (2,147,483,647); fractional parts are rounded.1 Starting with Visual Basic 15.8, Visual Basic optimizes the performance of floating-point to integer conversion with the CInt function; see the Remarks section for more information. See the CInt Example section for an example.
CLng	Long Data Type	Int64.MinValue (-9,223,372,036,854,775,808) through Int64.MaxValue (9,223,372,036,854,775,807); fractional parts are rounded.1 Starting with Visual Basic 15.8, Visual Basic optimizes the performance of floating-point to 64-bit integer conversion with the CLng function; see the Remarks section for more information. See the CInt Example section for an example.
CObj	Object Data Type	Any valid expression.
CSByte	SByte Data Type	SByte.MinValue (-128) through SByte.MaxValue (127); fractional parts are rounded.1 Starting with Visual Basic 15.8, Visual Basic optimizes the performance of floating-point to signed byte conversion with the CSByte function; see the Remarks section for more information. See the CInt Example section for an example.
CShort	Short Data Type	Int16.MinValue (-32,768) through Int16.MaxValue (32,767); fractional parts are rounded.1 Starting with Visual Basic 15.8, Visual Basic optimizes the performance of floating-point to 16-bit integer conversion with the CShort function; see the Remarks section for more information. See the CInt Example section for an example.
CSng	Single Data Type	-3.402823E+38 through -1.401298E-45 for negative values; 1.401298E-45 through 3.402823E+38 for positive values.
CStr	String Data Type	Returns for CStr depend on the expression argument. See Return Values for the CStr Function.
CUInt	UInteger Data Type	UInt32.MinValue (0) through UInt32.MaxValue (4,294,967,295) (unsigned); fractional parts are rounded.1 Starting with Visual Basic 15.8, Visual Basic optimizes the performance of floating-point to unsigned integer conversion with the CUInt function; see the Remarks section for more information. See the CInt Example section for an example.
CULng	ULong Data Type	UInt64.MinValue (0) through UInt64.MaxValue (18,446,744,073,709,551,615) (unsigned); fractional parts are rounded.1 Starting with Visual Basic 15.8, Visual Basic optimizes the performance of floating-point to unsigned long integer conversion with the CULng function; see the Remarks section for more information. See the CInt Example section for an example.
CUShort	UShort Data Type	UInt16.MinValue (0) through UInt16.MaxValue (65,535) (unsigned); fractional parts are rounded.1 Starting with Visual Basic 15.8, Visual Basic optimizes the performance of floating-point to unsigned 16-bit integer conversion with the CUShort function; see the Remarks section for more information. See the CInt Example section for an example.

¹ Fractional parts can be subject to a special type of rounding called banker's rounding. See "Remarks" for more information.

Remarks

As a rule, you should use the Visual Basic type conversion functions in preference to the .NET Framework methods such as ToString(), either on the Convert class or on an individual type structure or class. The Visual Basic functions are designed for optimal interaction with Visual Basic code, and they also make your source code shorter and easier to read. In addition, the .NET Framework conversion methods do not always produce the same results as the Visual Basic functions, for example when converting Boolean to Integer. For more information, see Troubleshooting Data Types.

Starting with Visual Basic 15.8, the performance of floating-point-to-integer conversion is optimized when you pass the Single or Double value returned by the following methods to one of the integer conversion functions (CByte, CShort, CInt, CLng, CSByte, CUShort, CUInt, CULng):

• Conversion.Fix(Double)
• Conversion.Fix(Object)
• Conversion.Fix(Single)
• Conversion.Int(Double)
• Conversion.Int(Object)
• Conversion.Int(Single)
• Math.Ceiling(Double)
• Math.Floor(Double)
• Math.Round(Double)
• Math.Truncate(Double)

This optimization allows code that does a large number of integer conversions to run up to twice as fast. The following example illustrates these optimized floating-point-to-integer conversions:

Dim s As Single = 173.7619
Dim d As Double = s

Dim i1 As Integer = CInt(Fix(s))               ' Result: 173
Dim b1 As Byte = CByte(Int(d))                 ' Result: 173
Dim s1 AS Short = CShort(Math.Truncate(s))     ' Result: 173
Dim i2 As Integer = CInt(Math.Ceiling(d))      ' Result: 174
Dim i3 As Integer = CInt(Math.Round(s))        ' Result: 174

Behavior

• Coercion. In general, you can use the data type conversion functions to coerce the result of an operation to a particular data type rather than the default data type. For example, use CDec to force decimal arithmetic in cases where single-precision, double-precision, or integer arithmetic would normally take place.

• Failed Conversions. If the expression passed to the function is outside the range of the data type to which it is to be converted, an OverflowException occurs.

• Fractional Parts. When you convert a nonintegral value to an integral type, the integer conversion functions (CByte, CInt, CLng, CSByte, CShort, CUInt, CULng, and CUShort) remove the fractional part and round the value to the closest integer.

  If the fractional part is exactly 0.5, the integer conversion functions round it to the nearest even integer. For example, 0.5 rounds to 0, and 1.5 and 2.5 both round to 2. This is sometimes called banker's rounding, and its purpose is to compensate for a bias that could accumulate when adding many such numbers together.

  CInt and CLng differ from the Int and Fix functions, which truncate, rather than round, the fractional part of a number. Also, Fix and Int always return a value of the same data type as you pass in.

• Date/Time Conversions. Use the IsDate function to determine if a value can be converted to a date and time. CDate recognizes date literals and time literals but not numeric values. To convert a Visual Basic 6.0 Date value to a Date value in Visual Basic 2005 or later versions, you can use the DateTime.FromOADate method.

• Neutral Date/Time Values. The Date Data Type always contains both date and time information. For purposes of type conversion, Visual Basic considers 1/1/0001 (January 1 of the year 1) to be a neutral value for the date, and 00:00:00 (midnight) to be a neutral value for the time. If you convert a Date value to a string, CStr does not include neutral values in the resulting string. For example, if you convert #January 1, 0001 9:30:00# to a string, the result is "9:30:00 AM"; the date information is suppressed. However, the date information is still present in the original Date value and can be recovered with functions such as DatePart function.

• Culture Sensitivity. The type conversion functions involving strings perform conversions based on the current culture settings for the application. For example, CDate recognizes date formats according to the locale setting of your system. You must provide the day, month, and year in the correct order for your locale, or the date might not be interpreted correctly. A long date format is not recognized if it contains a day-of-the-week string, such as "Wednesday".

  If you need to convert to or from a string representation of a value in a format other than the one specified by your locale, you cannot use the Visual Basic type conversion functions. To do this, use the ToString(IFormatProvider) and Parse(String, IFormatProvider) methods of that value's type. For example, use Double.Parse when converting a string to a Double, and use Double.ToString when converting a value of type Double to a string.

CType Function

The CType Function takes a second argument, typename, and coerces expression to typename, where typename can be any data type, structure, class, or interface to which there exists a valid conversion.

For a comparison of CType with the other type conversion keywords, see DirectCast Operator and TryCast Operator.

CBool Example

The following example uses the CBool function to convert expressions to Boolean values. If an expression evaluates to a nonzero value, CBool returns True; otherwise, it returns False.

Dim a, b, c As Integer
Dim check As Boolean
a = 5
b = 5
' The following line of code sets check to True.
check = CBool(a = b)
c = 0
' The following line of code sets check to False.
check = CBool(c)

CByte Example

The following example uses the CByte function to convert an expression to a Byte.

Dim aDouble As Double
Dim aByte As Byte
aDouble = 125.5678
' The following line of code sets aByte to 126.
aByte = CByte(aDouble)

CChar Example

The following example uses the CChar function to convert the first character of a String expression to a Char type.

Dim aString As String
Dim aChar As Char
' CChar converts only the first character of the string.
aString = "BCD"
' The following line of code sets aChar to "B".
aChar = CChar(aString)

The input argument to CChar must be of data type Char or String. You cannot use CChar to convert a number to a character, because CChar cannot accept a numeric data type. The following example obtains a number representing a code point (character code) and converts it to the corresponding character. It uses the InputBox function to obtain the string of digits, CInt to convert the string to type Integer, and ChrW to convert the number to type Char.

Dim someDigits As String
Dim codePoint As Integer
Dim thisChar As Char
someDigits = InputBox("Enter code point of character:")
codePoint = CInt(someDigits)
' The following line of code sets thisChar to the Char value of codePoint.
thisChar = ChrW(codePoint)

CDate Example

The following example uses the CDate function to convert strings to Date values. In general, hard-coding dates and times as strings (as shown in this example) is not recommended. Use date literals and time literals, such as #Feb 12, 1969# and #4:45:23 PM#, instead.

Dim aDateString, aTimeString As String
Dim aDate, aTime As Date
aDateString = "February 12, 1969"
aTimeString = "4:35:47 PM"
' The following line of code sets aDate to a Date value.
aDate = CDate(aDateString)
' The following line of code sets aTime to Date value.
aTime = CDate(aTimeString)

CDbl Example

Dim aDec As Decimal
Dim aDbl As Double
' The following line of code uses the literal type character D to make aDec a Decimal.
aDec = 234.456784D
' The following line of code sets aDbl to 1.9225456288E+1.
aDbl = CDbl(aDec * 8.2D * 0.01D)

CDec Example

The following example uses the CDec function to convert a numeric value to Decimal.

Dim aDouble As Double
Dim aDecimal As Decimal
aDouble = 10000000.0587
' The following line of code sets aDecimal to 10000000.0587.
aDecimal = CDec(aDouble)

CInt Example

The following example uses the CInt function to convert a value to Integer.

Dim aDbl As Double
Dim anInt As Integer
aDbl = 2345.5678
' The following line of code sets anInt to 2346.
anInt = CInt(aDbl)

CLng Example

The following example uses the CLng function to convert values to Long.

Dim aDbl1, aDbl2 As Double
Dim aLng1, aLng2 As Long
aDbl1 = 25427.45
aDbl2 = 25427.55
' The following line of code sets aLng1 to 25427.
aLng1 = CLng(aDbl1)
' The following line of code sets aLng2 to 25428.
aLng2 = CLng(aDbl2)

CObj Example

The following example uses the CObj function to convert a numeric value to Object. The Object variable itself contains only a four-byte pointer, which points to the Double value assigned to it.

Dim aDouble As Double
Dim anObject As Object
aDouble = 2.7182818284
' The following line of code sets anObject to a pointer to aDouble.
anObject = CObj(aDouble)

CSByte Example

The following example uses the CSByte function to convert a numeric value to SByte.

Dim aDouble As Double
Dim anSByte As SByte
aDouble = 39.501
' The following line of code sets anSByte to 40.
anSByte = CSByte(aDouble)

CShort Example

The following example uses the CShort function to convert a numeric value to Short.

Dim aByte As Byte
Dim aShort As Short
aByte = 100
' The following line of code sets aShort to 100.
aShort = CShort(aByte)

CSng Example

The following example uses the CSng function to convert values to Single.

Dim aDouble1, aDouble2 As Double
Dim aSingle1, aSingle2 As Single
aDouble1 = 75.3421105
aDouble2 = 75.3421567
' The following line of code sets aSingle1 to 75.34211.
aSingle1 = CSng(aDouble1)
' The following line of code sets aSingle2 to 75.34216.
aSingle2 = CSng(aDouble2)

CStr Example

The following example uses the CStr function to convert a numeric value to String.

Dim aDouble As Double
Dim aString As String
aDouble = 437.324
' The following line of code sets aString to "437.324".
aString = CStr(aDouble)

The following example uses the CStr function to convert Date values to String values.

Dim aDate As Date
Dim aString As String
' The following line of code generates a COMPILER ERROR because of invalid format.
' aDate = #February 12, 1969 00:00:00#
' Date literals must be in the format #m/d/yyyy# or they are invalid.
' The following line of code sets the time component of aDate to midnight.
aDate = #2/12/1969#
' The following conversion suppresses the neutral time value of 00:00:00.
' The following line of code sets aString to "2/12/1969".
aString = CStr(aDate)
' The following line of code sets the time component of aDate to one second past midnight.
aDate = #2/12/1969 12:00:01 AM#
' The time component becomes part of the converted value.
' The following line of code sets aString to "2/12/1969 12:00:01 AM".
aString = CStr(aDate)

CStr always renders a Date value in the standard short format for the current locale, for example, "6/15/2003 4:35:47 PM". However, CStr suppresses the neutral values of 1/1/0001 for the date and 00:00:00 for the time.

For more detail on the values returned by CStr, see Return Values for the CStr Function.

CUInt Example

The following example uses the CUInt function to convert a numeric value to UInteger.

Dim aDouble As Double
Dim aUInteger As UInteger
aDouble = 39.501
' The following line of code sets aUInteger to 40.
aUInteger = CUInt(aDouble)

CULng Example

The following example uses the CULng function to convert a numeric value to ULong.

Dim aDouble As Double
Dim aULong As ULong
aDouble = 39.501
' The following line of code sets aULong to 40.
aULong = CULng(aDouble)

CUShort Example

The following example uses the CUShort function to convert a numeric value to UShort.

Dim aDouble As Double
Dim aUShort As UShort
aDouble = 39.501
' The following line of code sets aUShort to 40.
aUShort = CUShort(aDouble)

See also

• Asc
• AscW
• Chr
• ChrW
• Int
• Fix
• Format
• Hex
• Oct
• Str
• Val
• Conversion Functions
• Type Conversions in Visual Basic