Formatowanie wartości wyrażonych w walutach

Klasa CurrencyFormatter służy do formatowania wartości liczbowych na ciągi zawierające ciągi waluty i sformatowane liczby zgodnie z konwencją obowiązującą w określonym państwie.

Po utworzeniu instancji nowego obiektu CurrencyFormatter ustawia on swoją walutę na domyślną walutę dla danego państwa.

Poniżej przedstawiono przykład, jak obiekt CurrencyFormatter utworzony za pomocą ustawień narodowych Niemiec przyjmuje euro do wyrażenia kwot waluty.

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

W większości przypadków nie powinno się opierać na domyślnej walucie dla danego państwa. Jeżeli domyślne ustawienia narodowe użytkownika nie są obsługiwane, wówczas klasa CurrencyFormatter przypisuje alternatywne ustawienia narodowe. Alternatywne ustawienia narodowe mogą mieć inną walutę domyślną. Ponadto zazwyczaj pożądane jest, aby formaty waluty wyglądały prawidłowo dla użytkownika, nawet jeżeli kwoty nie są wyrażone w lokalnej walucie użytkownika. Na przykład, użytkownik z Kanady może chcieć, aby ceny niemieckiej firmy były wyrażone w euro, ale sformatowane w stylu kanadyjskim.

Metoda CurrencyFormatter.setCurrency() dokładnie określa ciąg znaków i symbol waluty, jakie mają być używane.

W poniższym przykładzie kwoty waluty wyrażone w euro są przedstawiane w formie odpowiedniej dla francuskojęzycznych użytkowników w Kanadzie.

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

Metodę setCurrency() można również zastosować, aby uniknąć nieporozumień poprzez ustawienie jednoznacznych symboli waluty. Na przykład:

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

Domyślnie metoda format() służy do wyświetlania trzyznakowego kodu waluty ISO 4217 zamiast symbolu waluty. Kody ISO 4217 są jednoznaczne i nie wymagają lokalizacji. Jednakże wielu użytkowników preferuje symbole waluty zamiast kodów ISO.

Klasa CurrencyFormatter ułatwia podjęcie decyzji, czy w sformatowanym ciągu waluty należy zastosować symbol waluty, np. znak dolara lub euro, czy trzyznakowy ciąg waluty ISO, np. USD lub EUR. Na przykład kwota w dolarach kanadyjskich może być dla użytkowników w Kanadzie wyświetlana w postaci $200. Jednak dla użytkowników w Stanach Zjednoczonych odpowiednia byłaby postać CAD 200. Metoda formattingWithCurrencySymbolIsSafe() służy do określania, czy symbol waluty dla kwoty mógłby być niejednoznaczny lub nieprawidłowy względem ustawień narodowych danego użytkownika.

Na poniższym przykładzie przedstawiono formatowanie wartości w euro na format dla ustawień narodowych en-US. W zależności od ustawień narodowych użytkownika, w ciągu wyjściowym zostanie zastosowany kod waluty ISO lub symbol waluty.

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 
}

Za pomocą klasy CurrencyFormatter można również wyodrębniać kwotę wyrażoną w walucie oraz ciąg waluty z ciągu wejściowego, który jest zgodny z wymaganiami formatowania właściwymi dla danego regionu. Metoda CurrencyFormatter.parse() zapisuje przeanalizowaną kwotę oraz ciąg waluty w obiekcie CurrencyParseResult w sposób przedstawiony poniżej:

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

Część ciągu waluty z ciągu wejściowego może zawierać symbol waluty, kod ISO waluty i dodatkowe znaki tekstowe. Pozycje ciągu waluty, wskaźnik liczby ujemnej oraz wartość liczbowa są zgodne z formatami określonymi przez właściwości negativeCurrencyFormat i positiveCurrencyFormat. Na przykład:

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 $                

W tym przykładzie ciąg wejściowy zawiera ciąg waluty, następnie znak minus i liczbę. Jednakże domyślna wartość negativeCurrencyFormat dla ustawień narodowych en-US określa, że wskaźnik wartości ujemnych jest pierwszym znakiem w ciągu. Dlatego też w wyniku działania metody parse() wywoływany jest błąd, a przeanalizowana wartość to NaN.

Operacja metody parse() kończy się powodzeniem, gdy właściwość negativeCurrencyFormat zostaje przez nią ustawiona na 2, co określa, że ciąg waluty występuje na początku.