Udostępnij za pośrednictwem

klasa System.Convert

Ten artykuł zawiera dodatkowe uwagi dotyczące dokumentacji referencyjnej dla tego interfejsu API.

Klasa statyczna Convert zawiera metody, które są używane głównie do obsługi konwersji na i z podstawowych typów danych na platformie .NET. Obsługiwane typy podstawowe to Boolean, Char, SByte, Byte, Int16, Int32, Int64, UInt16, UInt32, UInt64, Single, Double, Decimal, DateTime i String. Ponadto Convert klasa zawiera metody obsługi innych rodzajów konwersji.

Konwersje do i z typów podstawowych

Istnieje metoda konwersji, aby przekonwertować każdy typ podstawowy na każdy inny typ podstawowy. Jednak rzeczywiste wywołanie określonej metody konwersji może wygenerować jeden z pięciu wyników, w zależności od wartości typu podstawowego w czasie wykonywania i docelowego typu podstawowego. Te pięć wyników to:

  • Brak konwersji. Dzieje się tak, gdy próbuje się przekonwertować typ na ten sam typ (na przykład poprzez wywołanie Convert.ToInt32(Int32) z argumentem typu Int32). W takim przypadku metoda po prostu zwraca wystąpienie oryginalnego typu.

  • Jeden InvalidCastException. Dzieje się tak, gdy określona konwersja nie jest obsługiwana. Element InvalidCastException jest zgłaszany dla następujących konwersji:

  • Klasa FormatException. Dzieje się tak, gdy próba przekonwertowania wartości ciągu na inny typ podstawowy kończy się niepowodzeniem, ponieważ ciąg nie jest w odpowiednim formacie. Wyjątek jest zgłaszany dla następujących konwersji:

    • Ciąg znaków, który ma zostać przekonwertowany na wartość Boolean, nie jest równy Boolean.TrueString ani Boolean.FalseString.
    • Ciąg, który ma zostać przekonwertowany na Char wartość, składa się z wielu znaków.
    • Ciąg, który ma zostać przekonwertowany na dowolny typ liczbowy, nie jest rozpoznawany jako prawidłowa liczba.
    • Ciąg, który ma zostać przekonwertowany na element DateTime , nie jest rozpoznawany jako prawidłowa wartość daty i godziny.

  • Pomyślna konwersja. W przypadku konwersji między dwoma różnymi typami podstawowymi, które nie zostały wymienione w poprzednich wynikach, wszystkie konwersje rozszerzające, a także wszystkie konwersje zawężające, które nie powodują utraty danych, powiedzie się, a metoda zwróci wartość docelowego typu podstawowego.

  • Jeden OverflowException. Do utraty danych dochodzi, gdy konwersja redukująca powoduje zmniejszenie ich dokładności. Na przykład próba konwersji instancji Int32, której wartość wynosi 10000, do typu Byte zgłasza OverflowException, ponieważ 10000 znajduje się poza zakresem typu danych Byte.

Wyjątek nie zostanie zgłoszony, jeśli konwersja typu liczbowego spowoduje utratę dokładności (czyli utratę co najmniej znaczących cyfr). Jednak wyjątek zostanie zgłoszony, jeśli wynik jest większy niż może być reprezentowany przez typ wartości zwracanej określonej metody konwersji.

Na przykład gdy element Double jest konwertowany na wartość Single, może wystąpić utrata precyzji, ale nie jest zgłaszany żaden wyjątek. Jeśli jednak wielkość Double jest zbyt duża, aby być reprezentowana przez element Single, zgłaszany jest wyjątek przepełnienia.

Liczby niedziesiętne

Klasa Convert zawiera metody statyczne, które można wywołać w celu przekonwertowania wartości całkowitych na reprezentacje ciągów innych niż dziesiętne, oraz do konwertowania ciągów reprezentujących liczby nieliczne dziesiętne na wartości całkowite. Każda z tych metod konwersji zawiera base argument, który pozwala określić system liczbowy; binarny (base 2), ósemkowy (base 8) i szesnastkowy (base 16), a także dziesiętny (base 10). Istnieje zestaw metod konwertowania każdego z typów całkowitych zgodnych ze specyfikacją CLS na ciąg, a jeden do konwersji ciągu na każdy z pierwotnych typów całkowitych:

Poniższy przykład konwertuje wartość Int16.MaxValue na ciąg we wszystkich obsługiwanych formatach liczbowych. Następnie konwertuje wartość ciągu z powrotem na Int16 wartość.

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

Konwersje z obiektów niestandardowych na typy podstawowe

Oprócz obsługi konwersji między typami Convert podstawowymi metoda obsługuje konwersję dowolnego typu niestandardowego na dowolny typ podstawowy. W tym celu typ niestandardowy musi implementować IConvertible interfejs, który definiuje metody konwertowania typu implementowania na każdy z typów podstawowych. Konwersje, które nie są obsługiwane przez określony typ, powinny zgłaszać wartość InvalidCastException.

Gdy do metody ChangeType przekazuje się typ niestandardowy jako pierwszy parametr, lub gdy metoda Convert.To (na przykład lub Convert.ToInt32(Object)) jest wywoływana i przyjmuje wystąpienie typu niestandardowego jako pierwszy parametr, metoda Convert.ToDouble(Object, IFormatProvider) z kolei używa implementacji typu niestandardowego Convert w celu przeprowadzenia konwersji. Aby uzyskać więcej informacji, zobacz Konwersja typów na platformie .NET.

Informacje o formatowaniu specyficznym dla kultury

Wszystkie podstawowe metody konwersji typów i ChangeType metoda obejmują przeciążenia, które mają parametr typu IFormatProvider. Na przykład Convert.ToBoolean metoda ma następujące dwa przeciążenia:

Parametr IFormatProvider może dostarczać informacje o formatowaniu specyficznym dla kultury, aby ułatwić proces konwersji. Jednak jest on ignorowany przez większość metod konwersji typu podstawowego. Jest on używany tylko przez następujące metody konwersji typu podstawowego. null IFormatProvider Jeśli argument jest przekazywany do tych metod, CultureInfo używany jest obiekt reprezentujący bieżącą kulturę.

Jednak każdy typ zdefiniowany przez użytkownika, który implementuje IConvertible , może korzystać z parametru IFormatProvider .

Kodowanie Base64

Kodowanie Base64 konwertuje dane binarne na ciąg. Dane wyrażone jako cyfry base-64 można łatwo przekazywać za pośrednictwem kanałów danych, które mogą przesyłać tylko 7-bitowe znaki. Klasa Convert zawiera następujące metody obsługi kodowania base64: zestaw metod obsługuje konwertowanie tablicy bajtów na i z String lub do i z tablicy znaków Unicode składających się z znaków base-64.

  • ToBase64String, który konwertuje tablicę bajtów na ciąg zakodowany w formacie base64.
  • ToBase64CharArray, który konwertuje tablicę bajtów na tablicę znaków zakodowaną w formacie base64.
  • FromBase64String, który konwertuje ciąg zakodowany w formacie base64 na tablicę bajtów.
  • FromBase64CharArray, który konwertuje tablicę znaków zakodowaną w formacie base64 na tablicę bajtów.

Inne typowe konwersje

Możesz użyć innych klas platformy .NET do wykonania niektórych konwersji, które nie są obsługiwane przez metody Convert statyczne klasy. Są to:

  • Konwersja na tablice bajtów

    Klasa BitConverter udostępnia metody, które konwertują pierwotne typy liczbowe (w tym Boolean) na tablice bajtów i z tablic bajtów z powrotem na typy danych pierwotnych.

  • Kodowanie znaków i dekodowanie

    Klasa Encoding i jej klasy pochodne (takie jak UnicodeEncoding i UTF8Encoding) udostępniają metody kodowania tablicy znaków lub ciągu (czyli konwertowania ich na tablicę bajtów w określonym kodowaniu) i dekodowania zakodowanej tablicy bajtów (czyli konwertowania tablicy bajtów z powrotem na znaki Unicode zakodowane w formacie UTF16). Aby uzyskać więcej informacji, zobacz Kodowanie znaków na platformie .NET.

Przykłady

W poniższym przykładzie pokazano niektóre metody konwersji w Convert klasie, w tym ToInt32, ToBooleani 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))