Compartilhar via

Classe System.Convert

  • Artigo

Este artigo fornece observações complementares à documentação de referência para essa 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, Int32Int16UInt16UInt32UInt64Int64ByteDoubleDecimalSingleDateTime e .String Além disso, a Convert classe inclui métodos para dar suporte a outros tipos de conversões.

Conversões de e para tipos base

Existe um método de conversão para converter todos os tipos base em todos os outros tipos base. No entanto, a chamada real para um método de conversão específico pode produzir um dos cinco resultados, dependendo do valor do tipo base em tempo de execução e do tipo base de destino. Esses cinco resultados são:

  • Sem conversão. Isso ocorre quando é feita uma tentativa de converter 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 é lançado para as seguintes conversões:

  • Um FormatException. Isso ocorre quando a tentativa de converter um valor de cadeia de caracteres em 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 string a ser convertida em um Boolean valor não é igual a 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 válido de data e hora.

  • 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 restrição 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 restrição resulta em 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 retornado do método de conversão específico.

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

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 integrais primitivos compatíveis com CLS em uma cadeia de caracteres e um para converter uma cadeia de caracteres em cada um dos tipos integrais primitivos:

O exemplo a seguir converte o valor de em uma cadeia de Int16.MaxValue caracteres em todos os formatos numéricos com suporte. 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("{0} --> {1} (base {2}) --> {3}",
                           value, s, 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 dar suporte a conversões entre os tipos base, o Convert método dá suporte à conversão de qualquer tipo personalizado em 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 em cada um dos tipos base. As conversões que não são suportadas por um tipo específico devem gerar um InvalidCastException.

Quando o ChangeType método é passado um tipo personalizado como seu primeiro parâmetro, ou quando o Convert.Tométodo Type (como Convert.ToInt32(Object) or Convert.ToDouble(Object, IFormatProvider) é chamado e passado uma instância de um tipo personalizado como seu primeiro parâmetro, o Convert método, por sua vez, chama a implementação do IConvertible tipo personalizado para executar a conversão. Para obter mais informações, confira 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 duas sobrecargas a seguir:

O IFormatProvider parâmetro pode fornecer informações de formatação específicas da cultura para auxiliar no 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 null IFormatProvider 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 implemente IConvertible pode usar o IFormatProvider parâmetro.

Codificação Base64

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

  • 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 têm suporte pelos métodos estáticos da Convert classe. Estão incluídos:

  • 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 em tipos de dados primitivos.

  • Codificação e decodificaçã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 em 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 {0}",
                         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))