Funções de conversão do tipo (Visual Basic)

Essas funções são compiladas embutidas, o que significa que o código de conversão faz parte do código que avalia a expressão. Às vezes, não há chamada para um procedimento para realizar a conversão, o que melhora o desempenho. Cada função força uma expressão a um tipo de dados específico.

Sintaxe

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)

Parte

expression
Obrigatórios. Qualquer expressão do tipo de dados de origem.

Tipo de dados do valor retornado

O nome da função determina o tipo de dados do valor retornado, conforme mostrado na tabela a seguir.

¹ Partes fracionárias podem estar sujeitas a um tipo especial de arredondamento chamado arredondamento bancário. Confira "Comentários" para obter mais informações.

Comentários

Como regra, você deve usar as funções de conversão de tipo do Visual Basic ao invés dos métodos .NET Framework, como ToString(), na classe Convert ou em uma estrutura ou classe de tipo individual. As funções do Visual Basic foram projetadas para uma interação ideal com o código do Visual Basic e também tornam o código-fonte mais curto e fácil de ler. Além disso, os métodos de conversão do .NET Framework nem sempre produzem os mesmos resultados que as funções do Visual Basic, por exemplo, ao converter Boolean em Integer. Para obter mais informações, consulte Tipos de dados de solução de problemas.

A partir do Visual Basic 15.8, o desempenho da conversão de ponto flutuante em inteiro é otimizado quando você passa o valor Single ou Double retornado pelos métodos a seguir para uma das funções de conversão de inteiro (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)

Essa otimização permite que o código que faz um grande número de conversões de inteiro seja executado duas vezes mais rápido. O exemplo a seguir ilustra estas conversões otimizadas de ponto flutuante em inteiro:

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

Comportamento

• Coerção. Em geral, você pode usar as funções de conversão de tipo de dados para forçar o resultado de uma operação a um tipo de dados específico em vez do tipo de dados padrão. Por exemplo, use CDec para forçar a aritmética decimal nos casos em que a aritmética de precisão única, precisão dupla ou inteiro normalmente ocorreria.

• Conversões com falha. Se expression passado para a função estiver fora do intervalo do tipo de dados ao qual ele deve ser convertido, ocorrerá uma OverflowException.

• Partes fracionárias. Quando você converte um valor não integral em um tipo integral, as funções de conversão de inteiro (CByte, CInt, CLng, CSByte, CShort, CUInt, CULng e CUShort) removem a parte fracionária e arredondam o valor para o inteiro mais próximo.

  Se a parte fracionária for exatamente 0,5, as funções de conversão de inteiro arredondarão para o inteiro par mais próximo. Por exemplo, 0,5 é arredondado para 0 e 1,5 e 2,5 para 2. Isso às vezes é chamado de arredondamento bancário, e seu propósito é compensar um desvio que poderia ser acumulado ao somar muitos desses números.

  CInt e CLng diferem das funções Int e Fix, que truncam, em vez de arredondar, a parte fracionária de um número. Além disso, Fix e Int sempre retorna um valor do mesmo tipo de dados que você passa.

• Conversões de data/hora. Use a função IsDate para determinar se um valor pode ser convertido em uma data e hora. CDate reconhece literais de data e literais de hora, mas não valores numéricos. Para converter um valor Date do Visual Basic 6.0 em um valor Date no Visual Basic 2005 ou versões posteriores, você pode usar o método DateTime.FromOADate.

• Valores de data/hora neutros. O Tipo de Dados de Data sempre contém informações de data e hora. Para fins de conversão de tipo, o Visual Basic considera 1/1/0001 (1º de janeiro do ano 1) como um valor neutro da data e 00:00:00 (meia-noite) como um valor neutro da hora. Se você converter um valor Date em uma cadeia de caracteres, CStr não inclui valores neutros na cadeia de caracteres resultante. Por exemplo, se você converter #January 1, 0001 9:30:00# em uma cadeia de caracteres, o resultado será "9:30:00 AM"; as informações de data serão suprimidas. No entanto, as informações de data ainda estão presentes no valor original Date e podem ser recuperadas com funções como função DatePart.

• Sensibilidade à cultura. As funções de conversão de tipo que envolvem cadeias de caracteres executam conversões com base nas configurações de cultura atuais do aplicativo. Por exemplo, CDate reconhece formatos de data de acordo com a configuração de localidade do sistema. Você deve fornecer o dia, mês e ano na ordem correta para sua localidade ou a data pode não ser interpretada corretamente. Um formato de data longa não será reconhecido se ele contiver uma cadeia de caracteres de um dia da semana, como "quarta-feira".

  Se for necessário converter para ou de uma representação de cadeia de caracteres de um valor em um formato diferente do especificado pela sua localidade, não será possível usar as funções de conversão de tipo do Visual Basic. Para fazer isso, use os métodos ToString(IFormatProvider) e Parse(String, IFormatProvider) desse tipo de valor. Por exemplo, use Double.Parse ao converter uma cadeia de caracteres em Double e use Double.ToString ao converter um valor de tipo Double em uma cadeia de caracteres.

Função CType

A Função CType usa um segundo argumento typename, e força expression a typename, onde typename pode ser qualquer tipo de dados, estrutura, classe ou interface para o qual existe uma conversão válida.

Para obter uma comparação de CType com as outras palavras-chave de conversão de tipo, consulte Operador DirectCast e Operador TryCast.

Exemplo de CBool

O seguinte exemplo usa a função CBool para converter expressões em valores Boolean. Se uma expressão for avaliada como um valor diferente de zero, CBool retornará True; caso contrário, retornará 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)

Exemplo de CByte

O exemplo a seguir usa a função CByte para converter uma expressão em Byte.

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

Exemplo de CChar

O exemplo a seguir usa a função CChar para converter o primeiro caractere de uma expressão String em um tipo Char.

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)

O argumento de entrada de CChar deve ser do tipo de dados Char ou String. Você não pode usar CChar para converter um número em um caractere, porque CChar não pode aceitar um tipo de dados numérico. O exemplo a seguir obtém um número que representa um ponto de código (código de caractere) e o converte no caractere correspondente. Ele usa a função InputBox para obter a cadeia de caracteres de dígitos, CInt para converter a cadeia de caracteres no tipo Integer e ChrW converter o número no tipo 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)

Exemplo de CDate

O seguinte exemplo usa a função CDate para converter cadeias de caracteres em valores Date. Em geral, não é recomendável codificar datas e horas como cadeias de caracteres (conforme mostrado neste exemplo). Use literais de data e de hora, como #Feb 12, 1969# e #4:45:23 PM#

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)

Exemplo de CDbl

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)

Exemplo de CDec

O seguinte exemplo usa a função CDec para converter um valor numérico em 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)

Exemplo de CInt

O seguinte exemplo usa a função CInt para converter um valor em Integer.

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

Exemplo de CLng

O seguinte exemplo usa a função CLng para converter valores em 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)

Exemplo de CObj

O seguinte exemplo usa a função CObj para converter um valor numérico em Object. A variável Object em si contém apenas um ponteiro de quatro bytes, que aponta para o valor Double atribuído a ela.

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)

Exemplo de CSByte

O seguinte exemplo usa a função CSByte para converter um valor numérico em SByte.

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

Exemplo de CShort

O seguinte exemplo usa a função CShort para converter um valor numérico em Short.

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

Exemplo de CSng

O seguinte exemplo usa a função CSng para converter valores em 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)

Exemplo de CStr

O seguinte exemplo usa a função CStr para converter um valor numérico em 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)

O seguinte exemplo usa a função CStr para converter valores Date em valores String.

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 sempre renderiza um valor Date no formato curto padrão da localidade atual, por exemplo, "15/6/2003 4:35:47 PM". No entanto, CStr suprime os valores neutros de 1/1/0001 na data e 00:00:00 na hora.

Para obter mais detalhes sobre os valores retornados por CStr, consulte Valores de Retorno para a Função CStr.

Exemplo de CUInt

O seguinte exemplo usa a função CUInt para converter um valor numérico em UInteger.

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

Exemplo de CULng

O seguinte exemplo usa a função CULng para converter um valor numérico em ULong.

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

Exemplo de CUShort

O seguinte exemplo usa a função CUShort para converter um valor numérico em UShort.

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

Confira também

• Asc
• AscW
• Chr
• ChrW
• Int
• Fix
• Format
• Hex
• Oct
• Str
• Val
• Funções de conversão
• Conversões de tipo no Visual Basic