Formatando números

Flash Player 10.1 e posterior, Adobe AIR 2.0 e posterior

O formato de exibição de valores numéricos variam muito de região para região. Por exemplo, o número 123456.78 é formatado para certas localidades da seguinte maneira:

Localidade

Formato do número

en-US (English, USA)

-123,456.78

de-DE (German, Germany)

-123.456,78

fr-FR (France, French)

-123 456,78

de-CH (German, Switzerland)

-123'456.78

en-IN (English, India)

-1,23,456.78

Várias localidades Árabes

123,456.78-

Existem vários fatores que influenciam formatos de número, incluindo:

  • Separadores. O separador decimal é colocado entre as partes inteira e fracionário de um número. Pode ser um ponto, uma vírgula ou outro caractere. O separador de agrupamento ou de milhares pode ser um ponto, uma vírgula, um espaço sem quebra ou outro caractere.

  • Padrões de agrupamento. O número de dígitos entre cada separador de agrupamento à esquerda do ponto decimal pode ser dois ou três ou outro valor.

  • Indicadores de números negativos. Números negativos podem ser mostrados com um sinal de menos à esquerda ou à direita do número, ou dentro de parênteses para aplicativos financeiros. Por exemplo, 19 negativo pode ser mostrado como -19, 19- ou (19).

  • Zeros à esquerda e à direita. Algumas convenções culturais adicionam zeros à esquerda ou à direita em números exibidos. Por exemplo, o valor 0.17 pode ser exibido como .17, 0.17, ou 0.170, entre outras opções.

  • Conjunto de caracteres de dígito. Muitas linguagens, incluindo Hindi, Árabe e Japonês utilizam diferentes conjuntos de caracteres de dígitos. O pacote flash.globalization suporta quaisquer conjuntos de caracteres de dígitos que mapeiam para os dígitos 0-9.

A classe NumberFormatter considera todos estes fatores ao formatar valores numéricos.

Utilizando a classe NumberFormatter

A classe NumberFormatter formata valores numéricos (do tipo int, uint, ou Number) de acordo com as convenções de uma localidade especifica.

O exemplo a seguir mostra a maneira mais simples de formatar um número utilizando as propriedades de formatação padrão fornecidas pelo sistema operacional do usuário: 

var nf:NumberFormatter = new NumberFormatter(LocaleID.DEFAULT); 
trace(nf.formatNumber(-123456.789))

O resultado pode variar com base nas configurações de localidade e das preferências do usuário. Por exemplo, se a localidade do usuário é fr-FR o valor formatado deve ser:

-123.456,789

Caso você queira apenas formatar um número para uma localidade especifica, independente das configurações de usuário, defina o nome da localidade especificamente. Por exemplo: 

var nf:NumberFormatter = new NumberFormatter("de-CH"); 
trace(nf.formatNumber(-123456.789));

Nesse caso, o resultado é:

-123'456.789

O método formatNumber() obtém um Number como parâmetro. A classe NumberFormatter também tem um método formatInt() que obtém um int (inteiro) como entrada e um método formatUint() que obtém um uint.

Você pode controlar explicitamente a lógica de formatação definindo as propriedades da classe NumberFormatter, como mostra este exemplo: 

var nf:NumberFormatter = new NumberFormatter("de-CH"); 
nf.negativeNumberFormat = 0; 
nf.fractionalDigits = 5; 
nf.trailingZeros = true; 
nf.decimalSeparator = ","; 
nf.useGrouping = false; 
trace(nf.formatNumber(-123456.789)); //(123456.78900)

Este exemplo cria primeiro um objeto NumberFormatter e, em seguida:

  • define o formato de número negativo para utilizar parênteses (como em aplicativos financeiros);

  • define o número de dígitos depois do separador decimal para 5;

  • especifica que os zeros à direita devem ser utilizados para garantir cinco casas decimais,

  • define o separador decimal como vírgula;

  • informa ao formatador para não utilizar qualquer separador de agrupamento.

Nota: Caso alguma alteração seja feita nessas propriedades, o formato de número resultante não corresponderá ao formato de preferência para a localidade especificada. Utilize algumas dessas propriedades somente quando a detecção de localidade não for importante, quando é preciso obter um controle detalhado sobre um único aspecto do formato como, por exemplo, o número de zeros à direita ou quando o usuário solicitar a alteração diretamente, pelo Painel de Controle do Windows.

Analisando strings que contém valores numéricos

A classe NumberFormatter pode também extrair valores numéricos de strings que se ajustem às necessidades de formatação especificas de localidade. O método NumberFormatter.parseNumber() extrai um valor numérico único de uma string. Por exemplo: 

var nf:NumberFormatter = new NumberFormatter( "en-US" ); 
var inputNumberString:String =  "-1,234,567.890" 
var parsedNumber:Number = nf.parseNumber(inputNumberString); 
trace("Value:" + parsedNumber); // -1234567.89 
trace("Status:" + nf.lastOperationStatus); // noError

O método parseNumber() manipula strings que contém caracteres de formatação de dígitos e números como sinais negativos e separadores. Se a cadeira de caracteres contiver outros caracteres, um código de erro é definido: 

var nf:NumberFormatter = new NumberFormatter( "en-US" ); 
var inputNumberString:String =  "The value is 1,234,567.890" 
var parsedNumber:Number = nf.parseNumber(inputNumberString); 
trace("Value:" + parsedNumber); // NaN 
trace("Status:" + nf.lastOperationStatus); // parseError

Para extrair números de strings que contém caracteres de alfabeto adicionais, utilize o método NumberFormatter.parse: 

var nf:NumberFormatter = new NumberFormatter( "en-US" ); 
var inputNumberString:String = "The value is 123,456,7.890"; 
var parseResult:NumberParseResult = nf.parse(inputNumberString); 
trace("Value:" + parseResult.value); // 1234567.89 
trace("startIndex: " + parseResult.startIndex); // 14 
trace("Status:" + nf.lastOperationStatus); // noError

O método parse() retorna um objeto NumberParseResult que contém o valor numérico analisado em sua propriedade de valor. A propriedade startIndex indica o índice do primeiro caractere numérico encontrado. Você pode utilizar também as propriedades startIndex e endIndex para extrair as porções da string que venham antes e depois dos dígitos.