Análise de cadeias de caracteres numéricas no .NETParsing Numeric Strings in NET

Todos os tipos numéricos têm dois métodos de análise estáticos, Parse e TryParse, que podem ser usados para converter a representação de cadeia de caracteres de um número em um tipo numérico.All numeric types have two static parsing methods, Parse and TryParse, that you can use to convert the string representation of a number into a numeric type. Esses métodos permitem analisar cadeias de caracteres que foram produzidas usando as cadeias de caracteres de formato documentadas em Cadeias de caracteres de formato numérico padrão e Cadeias de caracteres de formato numérico personalizadas.These methods enable you to parse strings that were produced by using the format strings documented in Standard Numeric Format Strings and Custom Numeric Format Strings. Por padrão, os métodos Parse e TryParse conseguem converter cadeias de caracteres que contêm dígitos decimais integrais somente em valores inteiros.By default, the Parse and TryParse methods can successfully convert strings that contain integral decimal digits only to integer values. Podem converter cadeias de caracteres que contêm dígitos decimais integrais e dígitos fracionários, separadores de grupo e um separador decimal em valores de ponto flutuante.They can successfully convert strings that contain integral and fractional decimal digits, group separators, and a decimal separator to floating-point values. O método Parse lança uma exceção se a operação falhar, enquanto o método TryParse retorna false.The Parse method throws an exception if the operation fails, whereas the TryParse method returns false.

Provedores de análise e formatoParsing and Format Providers

Normalmente, as representações de cadeia de caracteres de valores numéricos diferem por cultura.Typically, the string representations of numeric values differ by culture. Elementos de separadores de cadeias de caracteres numéricas, como símbolos de moeda, separadores de grupo (ou milhares) e separadores decimais, variam por cultura.Elements of numeric strings such as currency symbols, group (or thousands) separators, and decimal separators all vary by culture. Os métodos de análise usam, implícita ou explicitamente, um provedor de formato que reconhece essas variações específicas da cultura.Parsing methods either implicitly or explicitly use a format provider that recognizes these culture-specific variations. Se nenhum provedor de formato for especificado em uma chamada ao método Parse ou TryParse, será usado o provedor de formato associado à cultura do thread atual (o objeto NumberFormatInfo retornado pela propriedade NumberFormatInfo.CurrentInfo).If no format provider is specified in a call to the Parse or TryParse method, the format provider associated with the current thread culture (the NumberFormatInfo object returned by the NumberFormatInfo.CurrentInfo property) is used.

Um provedor de formato é representado por uma implementação IFormatProvider.A format provider is represented by an IFormatProvider implementation. Essa interface tem um único membro, o método GetFormat, cujo único parâmetro é um objeto Type que representa o tipo a ser formatado.This interface has a single member, the GetFormat method, whose single parameter is a Type object that represents the type to be formatted. Esse método retorna um objeto que fornece informações de formatação.This method returns the object that provides formatting information. O .NET dá suporte às duas implementações IFormatProvider a seguir para analisar cadeias de caracteres numéricas:.NET supports the following two IFormatProvider implementations for parsing numeric strings:

O exemplo a seguir tenta converter cada cadeia de caracteres em uma matriz em um valor Double.The following example tries to convert each string in an array to a Double value. Em primeiro lugar, tenta analisar a cadeia de caracteres usando um provedor de formato que reflete as convenções da cultura do inglês (Estados Unidos).It first tries to parse the string by using a format provider that reflects the conventions of the English (United States) culture. Se essa operação lançar um FormatException, tentará analisar a cadeia de caracteres usando um provedor de formato que reflita as convenções da cultura de francês (França).If this operation throws a FormatException, it tries to parse the string by using a format provider that reflects the conventions of the French (France) culture.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      string[] values = { "1,304.16", "$1,456.78", "1,094", "152", 
                          "123,45 €", "1 304,16", "Ae9f" };
      double number;
      CultureInfo culture = null;
      
      foreach (string value in values) {
         try {
            culture = CultureInfo.CreateSpecificCulture("en-US");
            number = Double.Parse(value, culture);
            Console.WriteLine("{0}: {1} --> {2}", culture.Name, value, number);
         }   
         catch (FormatException) {
            Console.WriteLine("{0}: Unable to parse '{1}'.", 
                              culture.Name, value);
            culture = CultureInfo.CreateSpecificCulture("fr-FR");
            try {
               number = Double.Parse(value, culture);
               Console.WriteLine("{0}: {1} --> {2}", culture.Name, value, number);
            }
            catch (FormatException) {
               Console.WriteLine("{0}: Unable to parse '{1}'.", 
                                 culture.Name, value);
            }
         }
         Console.WriteLine();
      }   
   }
}
// The example displays the following output:
//    en-US: 1,304.16 --> 1304.16
//    
//    en-US: Unable to parse '$1,456.78'.
//    fr-FR: Unable to parse '$1,456.78'.
//    
//    en-US: 1,094 --> 1094
//    
//    en-US: 152 --> 152
//    
//    en-US: Unable to parse '123,45 €'.
//    fr-FR: Unable to parse '123,45 €'.
//    
//    en-US: Unable to parse '1 304,16'.
//    fr-FR: 1 304,16 --> 1304.16
//    
//    en-US: Unable to parse 'Ae9f'.
//    fr-FR: Unable to parse 'Ae9f'.
Imports System.Globalization

Module Example
   Public Sub Main()
      Dim values() As String = { "1,304.16", "$1,456.78", "1,094", "152", 
                                 "123,45 €", "1 304,16", "Ae9f" }
      Dim number As Double
      Dim culture As CultureInfo = Nothing
      
      For Each value As String In values
         Try
            culture = CultureInfo.CreateSpecificCulture("en-US")
            number = Double.Parse(value, culture)
            Console.WriteLine("{0}: {1} --> {2}", culture.Name, value, number)
         Catch e As FormatException
            Console.WriteLine("{0}: Unable to parse '{1}'.", 
                              culture.Name, value)
            culture = CultureInfo.CreateSpecificCulture("fr-FR")
            Try
               number = Double.Parse(value, culture)
               Console.WriteLine("{0}: {1} --> {2}", culture.Name, value, number)
            Catch ex As FormatException
               Console.WriteLine("{0}: Unable to parse '{1}'.", 
                                 culture.Name, value)
            End Try
         End Try
         Console.WriteLine()
      Next
   End Sub
End Module
' The example displays the following output:
'    en-US: 1,304.16 --> 1304.16
'    
'    en-US: Unable to parse '$1,456.78'.
'    fr-FR: Unable to parse '$1,456.78'.
'    
'    en-US: 1,094 --> 1094
'    
'    en-US: 152 --> 152
'    
'    en-US: Unable to parse '123,45 €'.
'    fr-FR: Unable to parse '123,45 €'.
'    
'    en-US: Unable to parse '1 304,16'.
'    fr-FR: 1 304,16 --> 1304.16
'    
'    en-US: Unable to parse 'Ae9f'.
'    fr-FR: Unable to parse 'Ae9f'.

Análise e valores NumberStylesParsing and NumberStyles Values

Os elementos de estilo (como espaço em branco, separadores de grupo e separador decimal) que a operação de análise pode manipular são definidos por um valor de enumeração NumberStyles.The style elements (such as white space, group separators, and decimal separator) that the parse operation can handle are defined by a NumberStyles enumeration value. Por padrão, as cadeias de caracteres que representam valores inteiros são analisadas usando o valor NumberStyles.Integer, que permite apenas dígitos numéricos, espaço em branco à esquerda e à direita e um sinal à esquerda.By default, strings that represent integer values are parsed by using the NumberStyles.Integer value, which permits only numeric digits, leading and trailing white space, and a leading sign. Cadeias de caracteres que representam valores de ponto flutuante são analisadas usando uma combinação dos valores NumberStyles.Float e NumberStyles.AllowThousands. Esse estilo de composição permite dígitos decimais junto com o espaço em branco à esquerda e à direita, um sinal à esquerda, um separador decimal, um separador de grupo e um expoente.Strings that represent floating-point values are parsed using a combination of the NumberStyles.Float and NumberStyles.AllowThousands values; this composite style permits decimal digits along with leading and trailing white space, a leading sign, a decimal separator, a group separator, and an exponent. Chamando uma sobrecarga do método Parse ou TryParse que inclui um parâmetro do tipo NumberStyles e definindo um ou mais sinalizadores NumberStyles, é possível controlar os elementos de estilo que podem estar presentes na cadeia de caracteres para que a operação de análise seja bem-sucedida.By calling an overload of the Parse or TryParse method that includes a parameter of type NumberStyles and setting one or more NumberStyles flags, you can control the style elements that can be present in the string for the parse operation to succeed.

Por exemplo, uma cadeia de caracteres que contém um separador de grupo não pode ser convertida em um valor Int32 usando o método Int32.Parse(String).For example, a string that contains a group separator cannot be converted to an Int32 value by using the Int32.Parse(String) method. No entanto, a conversão será bem-sucedida se você usar o sinalizador NumberStyles.AllowThousands, como mostra o exemplo a seguir.However, the conversion succeeds if you use the NumberStyles.AllowThousands flag, as the following example illustrates.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      string value = "1,304";
      int number;
      IFormatProvider provider = CultureInfo.CreateSpecificCulture("en-US");
      if (Int32.TryParse(value, out number))
         Console.WriteLine("{0} --> {1}", value, number);
      else
         Console.WriteLine("Unable to convert '{0}'", value);
            
      if (Int32.TryParse(value, NumberStyles.Integer | NumberStyles.AllowThousands, 
                        provider, out number))
         Console.WriteLine("{0} --> {1}", value, number);
      else
         Console.WriteLine("Unable to convert '{0}'", value);
   }
}
// The example displays the following output:
//       Unable to convert '1,304'
//       1,304 --> 1304
Imports System.Globalization

Module Example
   Public Sub Main()
      Dim value As String = "1,304"
      Dim number As Integer
      Dim provider As IFormatProvider = CultureInfo.CreateSpecificCulture("en-US")
      If Int32.TryParse(value, number) Then
         Console.WriteLine("{0} --> {1}", value, number)
      Else
         Console.WriteLine("Unable to convert '{0}'", value)
      End If
            
      If Int32.TryParse(value, NumberStyles.Integer Or NumberStyles.AllowThousands, 
                        provider, number) Then
         Console.WriteLine("{0} --> {1}", value, number)
      Else
         Console.WriteLine("Unable to convert '{0}'", value)
      End If
   End Sub
End Module
' The example displays the following output:
'       Unable to convert '1,304'
'       1,304 --> 1304

Aviso

A operação de análise sempre usa as convenções de formatação de uma determinada cultura.The parse operation always uses the formatting conventions of a particular culture. Se você não especificar uma cultura passando um objeto CultureInfo ou NumberFormatInfo, a cultura associada ao thread atual será usada.If you do not specify a culture by passing a CultureInfo or NumberFormatInfo object, the culture associated with the current thread is used.

A tabela a seguir lista os membros da enumeração NumberStyles e descreve o efeito que eles têm sobre a operação de análise.The following table lists the members of the NumberStyles enumeration and describes the effect that they have on the parsing operation.

Valor NumberStylesNumberStyles value Efeito sobre a cadeia de caracteres a ser analisadaEffect on the string to be parsed
NumberStyles.None São permitidos apenas dígitos numéricos.Only numeric digits are permitted.
NumberStyles.AllowDecimalPoint O separador decimal e dígitos fracionários são permitidos.The decimal separator and fractional digits are permitted. Para valores inteiros, apenas zero é permitido como um dígito fracionário.For integer values, only zero is permitted as a fractional digit. Os separadores decimais válidos são determinados pela propriedade NumberFormatInfo.NumberDecimalSeparator ou NumberFormatInfo.CurrencyDecimalSeparator.Valid decimal separators are determined by the NumberFormatInfo.NumberDecimalSeparator or NumberFormatInfo.CurrencyDecimalSeparator property.
NumberStyles.AllowExponent O caractere “e” ou “E” pode ser usado para indicar notação exponencial.The "e" or "E" character can be used to indicate exponential notation. Para saber mais, confira NumberStyles.See NumberStyles for additional information.
NumberStyles.AllowLeadingWhite É permitido um espaço em branco à esquerda.Leading white space is permitted.
NumberStyles.AllowTrailingWhite É permitido um espaço em branco à direita.Trailing white space is permitted.
NumberStyles.AllowLeadingSign Um sinal positivo ou negativo pode anteceder dígitos numéricos.A positive or negative sign can precede numeric digits.
NumberStyles.AllowTrailingSign Um sinal positivo ou negativo pode seguir dígitos numéricos.A positive or negative sign can follow numeric digits.
NumberStyles.AllowParentheses Parênteses podem ser usados para indicar valores negativos.Parentheses can be used to indicate negative values.
NumberStyles.AllowThousands É permitido um separador de grupo.The group separator is permitted. O caractere separador de grupo é determinado pela propriedade NumberFormatInfo.NumberGroupSeparator ou NumberFormatInfo.CurrencyGroupSeparator.The group separator character is determined by the NumberFormatInfo.NumberGroupSeparator or NumberFormatInfo.CurrencyGroupSeparator property.
NumberStyles.AllowCurrencySymbol É permitido o símbolo de moeda.The currency symbol is permitted. O símbolo de moeda é definido pela propriedade NumberFormatInfo.CurrencySymbol.The currency symbol is defined by the NumberFormatInfo.CurrencySymbol property.
NumberStyles.AllowHexSpecifier A cadeia de caracteres a ser analisada é interpretada como um número hexadecimal.The string to be parsed is interpreted as a hexadecimal number. Pode incluir os dígitos decimais 0-9, A-F e a-f.It can include the hexadecimal digits 0-9, A-F, and a-f. Este sinalizador pode ser usado apenas para analisar valores inteiros.This flag can be used only to parse integer values.

Além disso, a enumeração NumberStyles oferece os estilos de composição a seguir, que incluem vários sinalizadores NumberStyles.In addition, the NumberStyles enumeration provides the following composite styles, which include multiple NumberStyles flags.

Valor NumberStyles de composiçãoComposite NumberStyles value Inclui membrosIncludes members
NumberStyles.Integer Inclui os estilos NumberStyles.AllowLeadingWhite, NumberStyles.AllowTrailingWhite e NumberStyles.AllowLeadingSign.Includes the NumberStyles.AllowLeadingWhite, NumberStyles.AllowTrailingWhite, and NumberStyles.AllowLeadingSign styles. É o estilo padrão usado para analisar valores inteiros.This is the default style used to parse integer values.
NumberStyles.Number Inclui os estilos NumberStyles.AllowLeadingWhite, NumberStyles.AllowTrailingWhite, NumberStyles.AllowLeadingSign, NumberStyles.AllowTrailingSign, NumberStyles.AllowDecimalPoint e NumberStyles.AllowThousands.Includes the NumberStyles.AllowLeadingWhite, NumberStyles.AllowTrailingWhite, NumberStyles.AllowLeadingSign, NumberStyles.AllowTrailingSign, NumberStyles.AllowDecimalPoint, and NumberStyles.AllowThousands styles.
NumberStyles.Float Inclui os estilos NumberStyles.AllowLeadingWhite, NumberStyles.AllowTrailingWhite, NumberStyles.AllowLeadingSign, NumberStyles.AllowDecimalPoint e NumberStyles.AllowExponent.Includes the NumberStyles.AllowLeadingWhite, NumberStyles.AllowTrailingWhite, NumberStyles.AllowLeadingSign, NumberStyles.AllowDecimalPoint, and NumberStyles.AllowExponent styles.
NumberStyles.Currency Inclui todos os estilos, exceto NumberStyles.AllowExponent e NumberStyles.AllowHexSpecifier.Includes all styles except NumberStyles.AllowExponent and NumberStyles.AllowHexSpecifier.
NumberStyles.Any Inclui todos os estilos, exceto NumberStyles.AllowHexSpecifier.Includes all styles except NumberStyles.AllowHexSpecifier.
NumberStyles.HexNumber Inclui os estilos NumberStyles.AllowLeadingWhite, NumberStyles.AllowTrailingWhite e NumberStyles.AllowHexSpecifier.Includes the NumberStyles.AllowLeadingWhite, NumberStyles.AllowTrailingWhite, and NumberStyles.AllowHexSpecifier styles.

Análise e Dígitos UnicodeParsing and Unicode Digits

O padrão Unicode define pontos de código para dígitos em diversos sistemas de escrita.The Unicode standard defines code points for digits in various writing systems. Por exemplo, os pontos de código de U+0030 a U+0039 representam os dígitos latinos básicos 0 a 9; os pontos de código de U+09E6 a U+09EF representam os dígitos bengali de 0 a 9; e os pontos de código de U+FF10 a U+FF19 representam os dígitos de largura inteira 0 a 9.For example, code points from U+0030 to U+0039 represent the basic Latin digits 0 through 9, code points from U+09E6 to U+09EF represent the Bangla digits 0 through 9, and code points from U+FF10 to U+FF19 represent the Fullwidth digits 0 through 9. No entanto, os únicos dígitos numéricos reconhecidos pelos métodos de análise são os dígitos latinos básicos 0-9 com os pontos de código de U+0030 a U+0039.However, the only numeric digits recognized by parsing methods are the basic Latin digits 0-9 with code points from U+0030 to U+0039. Se um método de análise numérica passar uma cadeia de caracteres que contenha outros dígitos, o método lançará um FormatException.If a numeric parsing method is passed a string that contains any other digits, the method throws a FormatException.

O exemplo a seguir usa o método Int32.Parse para analisar cadeias de caracteres que consistem em dígitos em diferentes sistemas de escrita.The following example uses the Int32.Parse method to parse strings that consist of digits in different writing systems. Como mostra a saída do exemplo, a tentativa de analisar os dígitos latinos básicos é bem-sucedida, mas a tentativa de analisar os dígitos de largura inteira, indo-arábicos e bengali.As the output from the example shows, the attempt to parse the basic Latin digits succeeds, but the attempt to parse the Fullwidth, Arabic-Indic, and Bangla digits fails.

using System;

public class Example
{
   public static void Main()
   {
      string value;
      // Define a string of basic Latin digits 1-5.
      value = "\u0031\u0032\u0033\u0034\u0035";
      ParseDigits(value);

      // Define a string of Fullwidth digits 1-5.
      value = "\uFF11\uFF12\uFF13\uFF14\uFF15";
      ParseDigits(value);
      
      // Define a string of Arabic-Indic digits 1-5.
      value = "\u0661\u0662\u0663\u0664\u0665";
      ParseDigits(value);
      
      // Define a string of Bangla digits 1-5.
      value = "\u09e7\u09e8\u09e9\u09ea\u09eb";
      ParseDigits(value);
   }

   static void ParseDigits(string value)
   {
      try {
         int number = Int32.Parse(value);
         Console.WriteLine("'{0}' --> {1}", value, number);
      }   
      catch (FormatException) {
         Console.WriteLine("Unable to parse '{0}'.", value);      
      }     
   }
}
// The example displays the following output:
//       '12345' --> 12345
//       Unable to parse '12345'.
//       Unable to parse '١٢٣٤٥'.
//       Unable to parse '১২৩৪৫'.
Module Example
   Public Sub Main()
      Dim value As String
      ' Define a string of basic Latin digits 1-5.
      value = ChrW(&h31) + ChrW(&h32) + ChrW(&h33) + ChrW(&h34) + ChrW(&h35)
      ParseDigits(value)

      ' Define a string of Fullwidth digits 1-5.
      value = ChrW(&hff11) + ChrW(&hff12) + ChrW(&hff13) + ChrW(&hff14) + ChrW(&hff15)
      ParseDigits(value)
      
      ' Define a string of Arabic-Indic digits 1-5.
      value = ChrW(&h661) + ChrW(&h662) + ChrW(&h663) + ChrW(&h664) + ChrW(&h665)
      ParseDigits(value)
      
      ' Define a string of Bangla digits 1-5.
      value = ChrW(&h09e7) + ChrW(&h09e8) + ChrW(&h09e9) + ChrW(&h09ea) + ChrW(&h09eb)
      ParseDigits(value)
   End Sub

   Sub ParseDigits(value As String)
      Try
         Dim number As Integer = Int32.Parse(value)
         Console.WriteLine("'{0}' --> {1}", value, number)
      Catch e As FormatException
         Console.WriteLine("Unable to parse '{0}'.", value)      
      End Try     
   End Sub
End Module
' The example displays the following output:
'       '12345' --> 12345
'       Unable to parse '12345'.
'       Unable to parse '١٢٣٤٥'.
'       Unable to parse '১২৩৪৫'.

Consulte tambémSee also