Classe System.Convert

  • Article

Cet article vous offre des remarques complémentaires à la documentation de référence pour cette API.

La classe statique Convert contient des méthodes principalement utilisées pour prendre en charge la conversion vers et à partir des types de données de base dans .NET. Les types de base pris en charge sont Boolean, , Char, Int64Int16Int32UInt16ByteSByteUInt32UInt64, Single, , DecimalDoubleDateTime et .String En outre, la Convert classe inclut des méthodes pour prendre en charge d’autres types de conversions.

Conversions vers et depuis des types de base

Une méthode de conversion existe pour convertir chaque type de base en un autre type de base. Toutefois, l’appel réel à une méthode de conversion particulière peut produire l’un des cinq résultats, en fonction de la valeur du type de base au moment de l’exécution et du type de base cible. Ces cinq résultats sont les suivants :

  • Aucune conversion. Cela se produit lorsqu’une tentative de conversion d’un type en lui-même (par exemple, en appelant Convert.ToInt32(Int32) avec un argument de type Int32). Dans ce cas, la méthode retourne simplement une instance du type d’origine.

  • InvalidCastException. Cela se produit lorsqu’une conversion particulière n’est pas prise en charge. Une InvalidCastException exception est levée pour les conversions suivantes :

  • FormatException. Cela se produit lorsque la tentative de conversion d’une valeur de chaîne en tout autre type de base échoue, car la chaîne n’est pas au format approprié. L’exception est levée pour les conversions suivantes :

    • Une chaîne à convertir en Boolean valeur n’est pas égale Boolean.TrueString ou Boolean.FalseString.
    • Une chaîne à convertir en Char valeur se compose de plusieurs caractères.
    • Une chaîne à convertir en un type numérique n’est pas reconnue comme un nombre valide.
    • Une chaîne à convertir en valeur DateTime n’est pas reconnue comme une valeur de date et d’heure valide.

  • Conversion réussie. Pour les conversions entre deux types de base différents non répertoriés dans les résultats précédents, toutes les conversions étendues ainsi que toutes les conversions restrictives qui n’entraînent pas de perte de données réussissent et la méthode retourne une valeur du type de base ciblé.

  • OverflowException. Cela se produit lorsqu’une conversion étroite entraîne une perte de données. Par exemple, la tentative de conversion d’une Int32 instance dont la valeur est 10000 en type lève OverflowException unByte, car 10000 est en dehors de la plage du Byte type de données.

Une exception ne sera pas levée si la conversion d’un type numérique entraîne une perte de précision (autrement dit, la perte de quelques chiffres moins significatifs). Toutefois, une exception est levée si le résultat est supérieur à celui pouvant être représenté par le type de valeur de retour de la méthode de conversion spécifique.

Par exemple, lorsqu’un Double élément est converti en un Single, une perte de précision peut se produire, mais aucune exception n’est levée. Toutefois, si l’ampleur de la valeur Double est trop grande pour être représentée par un Single, une exception de dépassement de capacité est levée.

Nombres non décimaux

La Convert classe inclut des méthodes statiques que vous pouvez appeler pour convertir des valeurs intégrales en représentations de chaîne non décimales et pour convertir des chaînes qui représentent des nombres non décimaux en valeurs intégrales. Chacune de ces méthodes de conversion inclut un base argument qui vous permet de spécifier le système numérique ; binaire (base 2), octal (base 8) et hexadécimal (base 16), ainsi que décimal (base 10). Il existe un ensemble de méthodes pour convertir chacun des types intégraux primitifs conformes CLS en chaîne, et un pour convertir une chaîne en chacun des types intégraux primitifs :

L’exemple suivant convertit la valeur d’une Int16.MaxValue chaîne dans tous les formats numériques pris en charge. Elle convertit ensuite la valeur de chaîne en valeur Int16 .

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

Conversions d’objets personnalisés en types de base

Outre la prise en charge des conversions entre les types de base, la méthode prend en charge la Convert conversion de n’importe quel type personnalisé en n’importe quel type de base. Pour ce faire, le type personnalisé doit implémenter l’interface IConvertible , qui définit des méthodes pour convertir le type d’implémentation en chacun des types de base. Les conversions qui ne sont pas prises en charge par un type particulier doivent lever un InvalidCastException.

Lorsque la ChangeType méthode est passée à un type personnalisé en tant que premier paramètre, ou lorsque laConvert.To méthode Type (par Convert.ToInt32(Object) exemple, Convert.ToDouble(Object, IFormatProvider) est appelée et passée une instance d’un type personnalisé en tant que premier paramètre, la Convert méthode appelle à son tour l’implémentation du IConvertible type personnalisé pour effectuer la conversion. Pour plus d’informations, consultez Conversion de type dans .NET.

Informations de mise en forme propres à la culture

Toutes les méthodes de conversion de type de base et la ChangeType méthode incluent des surcharges qui ont un paramètre de type IFormatProvider. Par exemple, la Convert.ToBoolean méthode a les deux surcharges suivantes :

Le IFormatProvider paramètre peut fournir des informations de mise en forme spécifiques à la culture pour faciliter le processus de conversion. Toutefois, elle est ignorée par la plupart des méthodes de conversion de type de base. Il est utilisé uniquement par les méthodes de conversion de type de base suivantes. Si un nullIFormatProvider argument est passé à ces méthodes, l’objet CultureInfo qui représente la culture actuelle est utilisé.

  • Par méthodes qui convertissent une valeur en type numérique. Le IFormatProvider paramètre est utilisé par la surcharge qui a des paramètres de type String et IFormatProvider. Elle est également utilisée par la surcharge qui a des paramètres de type Object et IFormatProvider si le type d’exécution de l’objet est un String.

  • Par méthodes qui convertissent une valeur en date et heure. Le IFormatProvider paramètre est utilisé par la surcharge qui a des paramètres de type String et IFormatProvider. Elle est également utilisée par la surcharge qui a des paramètres de type Object et IFormatProvider si le type d’exécution de l’objet est un String.

  • Par les Convert.ToString surcharges qui incluent un IFormatProvider paramètre et qui convertissent une valeur numérique en chaîne ou une DateTime valeur en chaîne.

Toutefois, tout type défini par l’utilisateur qui implémente IConvertible peut utiliser le IFormatProvider paramètre.

Encodage Base64

L’encodage Base64 convertit les données binaires en chaîne. Les données exprimées sous forme de chiffres de base 64 peuvent être facilement transmises sur des canaux de données qui ne peuvent transmettre que des caractères de 7 bits. La Convert classe inclut les méthodes suivantes pour prendre en charge l’encodage base64 : un ensemble de méthodes prend en charge la conversion d’un tableau d’octets vers et depuis un String ou vers un tableau de caractères Unicode composés de caractères à chiffres de base 64.

  • ToBase64String, qui convertit un tableau d’octets en chaîne codée en base64.
  • ToBase64CharArray, qui convertit un tableau d’octets en tableau de caractères codé en base64.
  • FromBase64String, qui convertit une chaîne encodée en base64 en tableau d’octets.
  • FromBase64CharArray, qui convertit un tableau de caractères encodé en base64 en tableau d’octets.

Autres conversions courantes

Vous pouvez utiliser d’autres classes .NET pour effectuer certaines conversions qui ne sont pas prises en charge par les méthodes statiques de la Convert classe. Il s’agit notamment des paramètres suivants :

  • Conversion en tableaux d’octets

    La BitConverter classe fournit des méthodes qui convertissent les types numériques primitifs (y compris Boolean) en tableaux d’octets et à partir de tableaux d’octets en types de données primitifs.

  • Encodage et décodage de caractères

    La Encoding classe et ses classes dérivées (telles que UnicodeEncoding et UTF8Encoding) fournissent des méthodes pour encoder un tableau de caractères ou une chaîne (autrement dit, pour les convertir en tableau d’octets dans un encodage particulier) et pour décoder un tableau d’octets encodé (autrement dit, convertir un tableau d’octets en caractères Unicode codés en UTF16). Pour plus d’informations, consultez Encodage de caractères dans .NET.

Exemples

L’exemple suivant illustre certaines des méthodes de conversion dans la Convert classe, notamment ToInt32, ToBooleanet 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))