System.Convert classe

  • 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 oferecer suporte à conversão de e para os tipos de dados base no .NET. Os tipos base suportados são Boolean, Char, SByte, Byte, Int32Int64Int16UInt16, UInt32, UInt64, DoubleDecimalSingleDateTime e .String Além disso, a Convert classe inclui métodos para oferecer suporte a outros tipos de conversões.

Conversões de e para tipos de base

Existe um método de conversão para converter cada tipo base em qualquer outro tipo 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 uma tentativa é feita para 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 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 a 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 resultam em perda de dados, serão bem-sucedidas e o método retornará um valor do tipo 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 lança 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 do for muito grande para ser representada por um Single, uma exceção de Double estouro é 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, 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 oferecer suporte a conversões entre os tipos base, o Convert método oferece 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 para cada um dos tipos base. As conversões que não são suportadas por um tipo específico devem lançar um InvalidCastExceptionarquivo .

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) ou 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 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 null IFormatProvider argumento for passado para esses métodos, o CultureInfo objeto que representa a cultura atual será usado.

  • Por métodos que convertem um valor em um tipo numérico. O IFormatProvider parâmetro é usado pela sobrecarga que tem parâmetros do tipo String e IFormatProvider. Ele também é usado pela sobrecarga que tem parâmetros do tipo Object e IFormatProvider se o tipo de tempo de execução do objeto for um Stringarquivo .

  • Por métodos que convertem um valor em data e hora. O IFormatProvider parâmetro é usado pela sobrecarga que tem parâmetros do tipo String e IFormatProvider. Ele também é usado pela sobrecarga que tem parâmetros do tipo Object e IFormatProvider se o tipo de tempo de execução do objeto for um Stringarquivo .

  • Pelas Convert.ToString sobrecargas que incluem um IFormatProvider parâmetro e que convertem um valor numérico em uma cadeia de caracteres ou um DateTime valor em uma cadeia de caracteres.

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 oferecer suporte à codificação base64: Um conjunto de métodos oferece suporte à conversão de uma matriz de bytes de e para um String ou para e de uma matriz de caracteres Unicode que consiste em caracteres de dígitos de 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. 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 para 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, convertê-los em uma matriz de bytes em uma codificação específica) e 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, ToBooleane 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))