Formatando valores de moeda

A classe CurrencyFormatter formata valores numéricos em strings que contém strings de moeda e números formatados, de acordo com as convenções de uma localidade especifica.

Quando você instancia um novo objeto CurrencyFormatter, ele define a moeda para o padrão para a localidade fornecida.

O exemplo a seguir mostra que um objeto CurrencyFormatter criado com o uso da localidade alemã assume que as quantidades de moeda estão em Euros:

var cf:CurrencyFormatter = new CurrencyFormatter( "de-DE" ); 
trace(cf.format(1234567.89)); // 1.234.567,89 EUR

Na maioria dos casos você não deve contar com o padrão de moeda para uma localidade. Caso não existe suporte para a localidade padrão do usuário, a classe CurrencyFormatter define uma localidade fallback. A localidade fallback pode ter uma moeda padrão diferente. Além disso, você desejará que os formatos de moeda pareçam corretas para seu usuário, mesmo se as quantidades não estejam na moeda local do usuário. Por exemplo, um usuário canadense pode querer ver os preços de uma empresa alemã em euros, mas formatados no estilo canadense.

O método CurrencyFormatter.setCurrency() especifica a cadeia de caracteres de moeda exata e o símbolo da moeda a ser utilizado.

O exemplo a seguir mostra quantidades de moeda em Euros para usuários na parte francesa do Canadá:

var cf:CurrencyFormatter = new CurrencyFormatter( "fr-CA" ); 
cf.setCurrency("EUR", "€"); 
trace(cf.format(1234567.89)); // 1.234.567,89 EUR

O método setCurrency() pode também ser utilizada para reduzir a confusão ao definir símbolos de moeda sem ambiguidade. Por exemplo:

cf.setCurrency("USD","US$");

O método format() exibe um código de moeda IDO 4217 de três caracteres ao invés do símbolo de moeda. Os códigos ISO 4217 não possuem ambiguidade e não requerem localização. No entanto muitos usuários preferem ver símbolos de moeda ao invés de códigos ISO.

A classe CurremcyFormatter pode ajudá-lo a decidir se uma string de moeda formatada deve utilizar um símbolo de moeda, como um símbolo de dólar ou de euro, ou uma string de moeda ISO de três caracteres, como USD ou EUR. Por exemplo, um valor em dólares Canadenses pode ser exibido como $200 para um usuário no Canadá. No entanto, para um usuário nos EUA, ele pode ser exibido como CAD 200. Utilize o método formattingWithCurrencySymbolIsSafe() para determinar se o símbolo de moeda de quantidade seria ambíguo ou incorreto para em relação às configurações de localidade do usuário.

O exemplo a seguir formata um valor em euros em um formato par a localidade en-US. Dependendo da localidade do usuário, a string de saída usará o código de moeda ISO ou o símbolo de moeda.

var cf:CurrencyFormatter = new CurrencyFormatter( "en-CA"); 
 
if (cf.formattingWithCurrencySymbolIsSafe("USD")) 
{ 
    trace(cf.format(1234567.89, true)); // $1,234,567.89 
} 
else 
{ 
    cf.setCurrency("USD", "$"); 
    trace(cf.format(1234567.89)); // USD1,234,567.89 
}

A classe CurrencyFormatter pode também extrair uma string de quantidade de moeda de uma string de entrada que corresponda às necessidades de formatação especificas de localidade. O método CurrencyFormatter.parse() armazena a quantidade analisada e a string de moeda em um objeto CurrencyParseResult, como mostrado em:

var cf:CurrencyFormatter = new CurrencyFormatter( "en-US" ); 
var inputCurrencyString:String = "(GBP 123,56,7.890)"; 
var parseResult:CurrencyParseResult = cf.parse(inputCurrencyString); 
trace("parsed amount: " + parseResult.value); // -1234567.89 
trace("currencyString: " + parseResult.currencyString ); // GBP

A porção de string de moeda da string de entrada pode conter um símbolo de moeda, um código ISO de moeda, e caracteres adicionais de texto. As posições da cadeia de caracteres de moeda, o indicador de número negativo e o valor numérico, devem corresponder aos formatos especificados pelas propriedades negativeCurrencyFormat e positiveCurrencyFormat. Por exemplo:

var cf:CurrencyFormatter = new CurrencyFormatter( "en-US" ); 
var inputCurrencyString:String = "Total $-123,56,7.890"; 
var parseResult:CurrencyParseResult = cf.parse(inputCurrencyString); 
trace("status: " + cf.lastOperationStatus ); // parseError 
trace("parsed amount: " + parseResult.value); // NaN 
trace("currencyString: " + parseResult.currencyString ); // 
cf.negativeCurrencyFormat = 2; 
parseResult = cf.parse(inputCurrencyString); 
trace("status: " + cf.lastOperationStatus ); // noError 
trace("parsed amount: " + parseResult.value); // -123567.89 
trace("currencyString: " + parseResult.currencyString ); // Total $                

Neste exemplo, a string de entrada tem uma string de moeda seguida por um sinal de menos e um número. No entanto o valor padrão de negativeCurrencyFormat para a localidade en-US especifica que o indicador negativo deve vir primeiro. Como resultado, o método parse() gera um erro e o valor analisado é NaN.

Em seguida ele define o negativeCurrencyFormat para 2, o qual especifica que a string de moeda vem primeiro, o método parse() terá êxito.