System.Convert classe

Observação

Este artigo fornece observações complementares à documentação de referência para esta API.

A classe estática Convert contém métodos que são usados principalmente para dar suporte à conversão de e para os tipos de dados base no .NET. Os tipos de base suportados são Boolean, Char, SByte, Byte, Int16, Int32, Int64, UInt16, UInt32, UInt64, Single, Double, Decimal, DateTime e String. Além disso, a Convert classe inclui métodos para suportar outros tipos de conversões.

Conversões de e para tipos base

Existe um método de conversão para converter cada tipo de base em todos os outros tipos de base. No entanto, a chamada real a um determinado método de conversão pode produzir um de cinco resultados, dependendo do valor do tipo base em tempo de execução e do tipo base alvo. Estes cinco resultados são:

  • Sem conversão. Isso ocorre quando é feita uma tentativa de conversão de um tipo para si mesmo (por exemplo, chamando Convert.ToInt32(Int32) com um argumento do tipo Int32). Nesse caso, o método simplesmente retorna uma instância do tipo original.

  • Um InvalidCastException. Isso ocorre quando uma conversão específica não é suportada. Um InvalidCastException é gerado para as seguintes conversões:

  • Um FormatException. Isso ocorre quando a tentativa de converter um valor de cadeia de caracteres para qualquer outro tipo base falha porque a cadeia de caracteres não está no formato adequado. A exceção é lançada para as seguintes conversões:

    • Uma cadeia de caracteres a ser convertida em um Boolean valor não é igual Boolean.TrueString ou Boolean.FalseString.
    • Uma cadeia de caracteres a ser convertida em um Char valor consiste em vários caracteres.
    • Uma cadeia de caracteres a ser convertida em qualquer tipo numérico não é reconhecida como um número válido.
    • Uma cadeia de caracteres a ser convertida em um DateTime não é reconhecida como um valor de data e hora válido.

  • Uma conversão bem-sucedida. Para conversões entre dois tipos de base diferentes não listados nos resultados anteriores, todas as conversões de ampliação, bem como todas as conversões de estreitamento que não resultem em perda de dados serão bem-sucedidas e o método retornará um valor do tipo de base de destino.

  • Um OverflowException. Isso ocorre quando uma conversão de estreitamento resulta em uma perda de dados. Por exemplo, tentar converter uma Int32 instância cujo valor é 10000 em um Byte tipo gera um OverflowException porque 10000 está fora do intervalo do tipo de Byte dados.

Uma exceção não será lançada se a conversão de um tipo numérico resultar em uma perda de precisão (ou seja, a perda de alguns dígitos menos significativos). No entanto, uma exceção será lançada se o resultado for maior do que pode ser representado pelo tipo de valor de retorno do método de conversão específico.

Por exemplo, quando um Double é convertido em um Single, pode ocorrer uma perda de precisão, mas nenhuma exceção é lançada. No entanto, se a magnitude de Double for demasiado grande para ser representada por um Single, é lançada uma exceção de overflow.

Números não decimais

A Convert classe inclui métodos estáticos que você pode chamar para converter valores integrais em representações de cadeia de caracteres não decimais e para converter cadeias de caracteres que representam números não decimais em valores integrais. Cada um desses métodos de conversão inclui um base argumento que permite especificar o sistema numérico: binário (base 2), octal (base 8) e hexadecimal (base 16), bem como decimal (base 10). Há um conjunto de métodos para converter cada um dos tipos de integrais primitivas compatíveis com CLS em uma cadeia de caracteres e um para converter uma cadeia de caracteres em cada um dos tipos de integrais primitivas:

O exemplo a seguir converte o valor de Int16.MaxValue para uma cadeia de caracteres em todos os formatos numéricos suportados. Em seguida, ele converte o valor da cadeia de caracteres de volta em um Int16 valor.

using System;

public class Example
{
   public static void Main()
   {
      int[] baseValues = { 2, 8, 10, 16 };
      short value = Int16.MaxValue;
      foreach (var baseValue in baseValues) {
         String s = Convert.ToString(value, baseValue);
         short value2 = Convert.ToInt16(s, baseValue);

         Console.WriteLine($"{value} --> {s} (base {baseValue}) --> {value2}");
      }
   }
}
// The example displays the following output:
//     32767 --> 111111111111111 (base 2) --> 32767
//     32767 --> 77777 (base 8) --> 32767
//     32767 --> 32767 (base 10) --> 32767
//     32767 --> 7fff (base 16) --> 32767

open System

let baseValues = [ 2; 8; 10; 16 ]
let value = Int16.MaxValue
for baseValue in baseValues do
    let s = Convert.ToString(value, baseValue)
    let value2 = Convert.ToInt16(s, baseValue)
    printfn $"{value} --> {s} (base {baseValue}) --> {value2}"

// The example displays the following output:
//     32767 --> 111111111111111 (base 2) --> 32767
//     32767 --> 77777 (base 8) --> 32767
//     32767 --> 32767 (base 10) --> 32767
//     32767 --> 7fff (base 16) --> 32767

Module Example2
    Public Sub Main()
        Dim baseValues() As Integer = {2, 8, 10, 16}
        Dim value As Short = Int16.MaxValue
        For Each baseValue In baseValues
            Dim s As String = Convert.ToString(value, baseValue)
            Dim value2 As Short = Convert.ToInt16(s, baseValue)

            Console.WriteLine("{0} --> {1} (base {2}) --> {3}",
                           value, s, baseValue, value2)
        Next
    End Sub
End Module
' The example displays the following output:
'     32767 --> 111111111111111 (base 2) --> 32767
'     32767 --> 77777 (base 8) --> 32767
'     32767 --> 32767 (base 10) --> 32767
'     32767 --> 7fff (base 16) --> 32767

Conversões de objetos personalizados para tipos base

Além de suportar conversões entre os tipos base, o método suporta a conversão Convert de qualquer tipo personalizado para qualquer tipo base. Para fazer isso, o tipo personalizado deve implementar a IConvertible interface, que define métodos para converter o tipo de implementação para cada um dos tipos base. As conversões que não são suportadas por um tipo específico devem lançar um InvalidCastException.

Quando o ChangeType método recebe um tipo personalizado como seu primeiro parâmetro, ou quando o Convert.Tométodo Type (como Convert.ToInt32(Object) ou Convert.ToDouble(Object, IFormatProvider)) é chamado e recebe uma instância de um tipo personalizado como seu primeiro parâmetro, o Convert método, por sua vez, chama a implementação da conversão do tipo personalizado IConvertible para executar a conversão. Para obter mais informações, consulte Conversão de tipo no .NET.

Informações de formatação específicas da cultura

Todos os métodos de conversão de tipo base e o ChangeType método incluem sobrecargas que têm um parâmetro do tipo IFormatProvider. Por exemplo, o Convert.ToBoolean método tem as seguintes duas sobrecargas:

O IFormatProvider parâmetro pode fornecer informações de formatação específicas da cultura para auxiliar o processo de conversão. No entanto, ele é ignorado pela maioria dos métodos de conversão de tipo base. Ele é usado apenas pelos seguintes métodos de conversão de tipo base. Se um nullIFormatProvider argumento for passado para esses métodos, o CultureInfo objeto que representa a cultura atual será usado.

No entanto, qualquer tipo definido pelo usuário que implementa IConvertible pode fazer uso do IFormatProvider parâmetro.

Codificação Base64

A codificação Base64 converte dados binários em uma cadeia de caracteres. Os dados expressos como dígitos de base 64 podem ser facilmente transmitidos através de canais de dados que só podem transmitir caracteres de 7 bits. A Convert classe inclui os seguintes métodos para suportar a codificação base64: um conjunto de métodos suporta a conversão de uma matriz de bytes para e de um String ou para e de uma matriz de caracteres Unicode composta por caracteres de dígitos em base 64.

  • ToBase64String, que converte uma matriz de bytes em uma cadeia de caracteres codificada em base64.
  • ToBase64CharArray, que converte uma matriz de bytes em uma matriz de caracteres codificada em base64.
  • FromBase64String, que converte uma cadeia de caracteres codificada em base64 em uma matriz de bytes.
  • FromBase64CharArray, que converte uma matriz de caracteres codificada em base64 em uma matriz de bytes.

Outras conversões comuns

Você pode usar outras classes .NET para executar algumas conversões que não são suportadas pelos métodos estáticos da Convert classe. Estes são, entre outros:

  • Conversão em matrizes de bytes

    A BitConverter classe fornece métodos que convertem os tipos numéricos primitivos (incluindo Boolean) em matrizes de bytes e de matrizes de bytes de volta para tipos de dados primitivos.

  • Codificação e descodificação de caracteres

    A Encoding classe e suas classes derivadas (como UnicodeEncoding e UTF8Encoding) fornecem métodos para codificar uma matriz de caracteres ou uma cadeia de caracteres (ou seja, para convertê-los em uma matriz de bytes em uma codificação específica) e para decodificar uma matriz de bytes codificada (ou seja, converter uma matriz de bytes de volta para caracteres Unicode codificados em UTF16). Para obter mais informações, consulte Codificação de caracteres no .NET.

Exemplos

O exemplo a seguir demonstra alguns dos métodos de conversão na Convert classe, incluindo ToInt32, ToBoolean, e ToString.

double dNumber = 23.15;

try {
    // Returns 23
    int    iNumber = System.Convert.ToInt32(dNumber);
}
catch (System.OverflowException) {
    System.Console.WriteLine(
                "Overflow in double to int conversion.");
}
// Returns True
bool   bNumber = System.Convert.ToBoolean(dNumber);

// Returns "23.15"
string strNumber = System.Convert.ToString(dNumber);

try {
    // Returns '2'
    char chrNumber = System.Convert.ToChar(strNumber[0]);
}
catch (System.ArgumentNullException) {
    System.Console.WriteLine("String is null");
}
catch (System.FormatException) {
    System.Console.WriteLine("String length is greater than 1.");
}

// System.Console.ReadLine() returns a string and it
// must be converted.
int newInteger = 0;
try {
    System.Console.WriteLine("Enter an integer:");
    newInteger = System.Convert.ToInt32(
                        System.Console.ReadLine());
}
catch (System.ArgumentNullException) {
    System.Console.WriteLine("String is null.");
}
catch (System.FormatException) {
    System.Console.WriteLine("String does not consist of an " +
                    "optional sign followed by a series of digits.");
}
catch (System.OverflowException) {
    System.Console.WriteLine(
    "Overflow in string to int conversion.");
}

System.Console.WriteLine($"Your integer as a double is {System.Convert.ToDouble(newInteger)}");

let dNumber = 23.15

try
    // Returns 23
    Convert.ToInt32 dNumber
    |> ignore
with :? OverflowException ->
    printfn "Overflow in double to int conversion."
// Returns True
let bNumber = System.Convert.ToBoolean dNumber

// Returns "23.15"
let strNumber = System.Convert.ToString dNumber

try
    // Returns '2'
    System.Convert.ToChar strNumber[0]
    |> ignore
with
| :? ArgumentNullException ->
    printfn "String is null"
| :? FormatException ->
    printfn "String length is greater than 1."

// System.Console.ReadLine() returns a string and it
// must be converted.
let newInteger =
    try
        printfn "Enter an integer:"
        System.Convert.ToInt32(Console.ReadLine())
    with
    | :? ArgumentNullException ->
        printfn "String is null."
        0
    | :? FormatException ->
        printfn "String does not consist of an optional sign followed by a series of digits."
        0
    | :? OverflowException ->
        printfn "Overflow in string to int conversion."
        0

printfn $"Your integer as a double is {System.Convert.ToDouble newInteger}"

Dim dNumber As Double
dNumber = 23.15

Try
   ' Returns 23
   Dim iNumber As Integer
   iNumber = System.Convert.ToInt32(dNumber)
Catch exp As System.OverflowException
   System.Console.WriteLine("Overflow in double to int conversion.")
End Try

' Returns True
Dim bNumber As Boolean
bNumber = System.Convert.ToBoolean(dNumber)

' Returns "23.15"
Dim strNumber As String
strNumber = System.Convert.ToString(dNumber)

Try
   ' Returns '2'
   Dim chrNumber As Char
   chrNumber = System.Convert.ToChar(strNumber.Chars(1))
Catch exp As System.ArgumentNullException
   System.Console.WriteLine("String is null.")
Catch exp As System.FormatException
   System.Console.WriteLine("String length is greater than 1.")
End Try

' System.Console.ReadLine() returns a string and it
' must be converted.
Dim newInteger As Integer
newInteger = 0
Try
   System.Console.WriteLine("Enter an integer:")
   newInteger = System.Convert.ToInt32(System.Console.ReadLine())
Catch exp As System.ArgumentNullException
   System.Console.WriteLine("String is null.")
Catch exp As System.FormatException
   System.Console.WriteLine("String does not consist of an " + _
       "optional sign followed by a series of digits.")
Catch exp As System.OverflowException
   System.Console.WriteLine("Overflow in string to int conversion.")
End Try

System.Console.WriteLine("Your integer as a double is {0}", _
                         System.Convert.ToDouble(newInteger))
  • Last updated on