CurrencyFormatter  - AS3

The name of the actual locale ID used by this CurrencyFormatter object.

There are three possibilities for the value of the name, depending on operating system and the value of the requestedLocaleIDName parameter passed to the CurrencyFormatter() constructor.

1. If the requested locale was not LocaleID.DEFAULT and the operating system provides support for the requested locale, then the name returned is the same as the requestedLocaleIDName property.
2. If LocaleID.DEFAULT was used as the value for the requestedLocaleIDName parameter to the constructor, then the name of the current locale specified by the user's operating system is used. The LocaleID.DEFAULT value preserves user's customized setting in the OS. Passing an explicit value as the requestedLocaleIDName parameter does not necessarily give the same result as using the LocaleID.DEFAULT even if the two locale ID names are the same. The user might have customized the locale settings on their machine, and by requesting an explicit locale ID name rather than using LocaleID.DEFAULT your application would not retrieve those customized settings.
3. If the system does not support the requestedLocaleIDName specified in the constructor then a fallback locale ID name is provided.

Related API Elements

The three letter ISO 4217 currency code for the actual locale being used.

This code is used to determine the currency symbol or string when formatting currency amounts using the format() method with the withCurrencySymbol parameter set to false.

This property is initialized by the constructor based on the actual locale that is used. When a fallback locale is used this property reflects the preferred, default currency code for the fallback locale.

The default value is dependent on the actual locale and operating system.

Related API Elements

The currency symbol or string for the actual locale being used.

This property is used as the currency symbol when formatting currency amounts using the format() method with the withCurrencySymbol parameter set to true.

This property is initialized by the constructor based on the actual locale that is used. When a fallback locale is used this property reflects the preferred, default currency symbol for the fallback locale.

The default value is dependent on the actual locale and operating system.

Related API Elements

The decimal separator character used for formatting or parsing currency amounts that have a decimal part.

This property is initially set based on the locale that is selected when the formatter object is constructed.

When this property is assigned a value and there are no errors or warnings, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

The default value is dependent on the actual locale and operating system.

Related API Elements

Defines the set of digit characters used when formatting currency amounts.

Different languages and regions use different sets of characters to represent the digits 0 through 9. This property defines the set of digits to be used.

The value of this property represents the Unicode value for the zero digit of a decimal digit set. The valid values for this property are defined in the NationalDigitsType class.

When this property is assigned a value and there are no errors or warnings, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

The default value is dependent on the actual locale and operating system.

Related API Elements

The maximum number of digits that can appear after the decimal separator.

Numbers are rounded to the number of digits specified by this property. The rounding scheme varies depending on the user's operating system.

When the trailingZeros property is set to true, the fractional portion of the number (after the decimal point) is padded with trailing zeros until its length matches the value of this fractionalDigits property.

When this property is assigned a value and there are no errors or warnings, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

The default value is 0.

Related API Elements

Describes the placement of grouping separators within the formatted currency amount string.

When the useGrouping property is set to true, the groupingPattern property is used to define the placement and pattern used for the grouping separator.

The grouping pattern is defined as a string containing numbers separated by semicolons and optionally may end with an asterisk. For example: "3;2;*". Each number in the string represents the number of digits in a group. The grouping separator is placed before each group of digits. An asterisk at the end of the string indicates that groups with that number of digits should be repeated for the rest of the formatted string. If there is no asterisk then there are no additional groups or separators for the rest of the formatted string.

The first number in the string corresponds to the first group of digits to the left of the decimal separator. Subsequent numbers define the number of digits in subsequent groups to the left. Thus the string "3;2;*" indicates that a grouping separator is placed after the first group of 3 digits, followed by groups of 2 digits. For example: 98,76,54,321

The following table shows examples of formatting the currency amount 123456789.12 with various grouping patterns. The grouping separator is a comma, the decimal separator is a period, and a dollar sign ($) is the currency symbol.

Only a limited number of grouping sizes can be defined. On some operating systems, grouping patterns can only contain two numbers plus an asterisk. Other operating systems can support up to four numbers and an asterisk. For patterns without an asterisk, some operating systems only support one number while others support up to three numbers. If the maximum number of grouping pattern elements is exceeded, then additional elements are ignored, and the lastOperationStatus property is set as described below.

When this property is assigned a value and there are no errors or warnings, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

Related API Elements

The character or string used for the grouping separator.

The value of this property is used as the grouping separator when formatting currency amounts when the useGrouping property is set to true. This property is initially set based on the locale that is selected when the formatter object is constructed.

When this property is assigned a value and there are no errors or warnings, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

The default value is dependent on the actual locale and operating system.

Related API Elements

The status of the most recent operation that this CurrencyFormatter object performed. The lastOperationStatus property is set whenever the constructor or a method of this class is called or another property is set. For the possible values see the description for each method.

Related API Elements

Specifies whether a leading zero is included in a formatted currency amount when there are no integer digits to the left of the decimal separator.

When this property is set to true a leading zero is included to the left of the decimal separator when formatting numeric values between -1.0 and 1.0. When this property is set to false a leading zero is not included.

For example if the currency amount is 0.321 and this property is set true, then the leading zero is included in the formatted string. If the property is set to false, the leading zero is not included. In that case the string would just include the decimal separator followed by the decimal digits, like $.321.

The following table shows examples of how currency amounts are formatted based on the values of this property and the related fractionalDigits and trailingZeros properties.

When this property is assigned a value and there are no errors or warnings, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

The default value is dependent on the actual locale and operating system.

Related API Elements

A numeric value that indicates a formatting pattern for negative currency amounts. This pattern defines the location of the currency symbol and the negative symbol or parentheses in relation to the numeric portion of the currency amount.

The value of this property must be one of the constants defined in the table below.

The table below summarizes the possible formatting patterns for negative currency amounts. When a currency amount is formatted with the format() method:

• The '¤' symbol is replaced with the value of the currencyISOCode or the currencySymbol property, depending on the value of the withCurrencySymbol parameter passed to the format() method;
• The '-' character is replaced with the value of the negativeNumberSymbol property;
• The 'n' character is replaced with the currency amount value that is passed to the format() method.

When this property is assigned a value and there are no errors or warnings, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

The default value is dependent on the actual locale and operating system.

Related API Elements

The negative symbol used when formatting negative currency amounts.

This symbol is used with the negative currency format when formatting a currency amount that is less than zero. It is not used in negative currency formats that do not include a negative sign (for example, when negative currency amounts are enclosed in parentheses).

When this property is assigned a value and there are no errors or warnings, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

The default value is dependent on the actual locale and operating system.

Related API Elements

A numeric value that indicates a formatting pattern for positive currency amounts. This format defines the location of currency symbol relative to the numeric portion of the currency amount.

The value of this property must be one of the constants defined in the table below.

The table below summarizes the possible formatting patterns for positive currency amounts. When a currency amount is formatted with the format() method:

• The '¤' symbol is replaced with the value of the currencyISOCode or the currencySymbol property, depending on the value of the withCurrencySymbol parameter passed to the format() method;
• The 'n' character is replaced with the currency amount value that is passed to the format() method.

When this property is assigned a value and there are no errors or warnings, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

The default value is dependent on the actual locale and operating system.

Related API Elements

The name of the requested locale ID that was passed to the constructor of this CurrencyFormatter object.

If the LocaleID.DEFAULT value was used then the name returned is "i-default". The actual locale used can differ from the requested locale when a fallback locale is applied. The name of the actual locale can be retrieved using the actualLocaleIDName property.

Related API Elements

Specifies whether trailing zeros are included in the formatted currency amount.

When this property is set to true, trailing zeros are included in the fractional part of the formatted number up the limit specified by the fractionalDigits property. When this property is set to false then no trailing zeros are shown.

For example if the currency amount is 123.4, and this property is set true, and the fractionalDigits property is set to 3, the formatted string would show trailing zeros, like $123.400 . If this property is false, trailing zeros are not included, and the string shows just the decimal separator followed by the non-zero decimal digits, like $123.4 .

The following table shows examples of how currency amounts are formatted based on the values of this property and the related fractionalDigits and leadingZero properties.

When this property is assigned a value and there are no errors or warnings, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

The default value is dependent on the actual locale and operating system.

Related API Elements

Enables the use of the grouping separator when formatting currency amounts.

When the useGrouping property is set to true, digits are grouped and delimited by the grouping separator character. For example: $123,456,789

When the useGrouping property is set to false, digits are not grouped or separated. For example: $123456789

The groupingSeparator property defines the symbol to be used as a grouping separator. The groupingPattern property defines the number of digits between grouping separators.

When this property is assigned a value and there are no errors or warnings, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

Related API Elements

Constructs a new CurrencyFormatter object to format numbers representing currency amounts according to the conventions of a given locale.

This constructor determines if the current operating system supports the requested locale ID name. If it is not supported then a fallback locale is used instead. If a fallback locale is used then the lastOperationStatus property indicates the type of fallback, and the actualLocaleIDName property contains the name of the fallback locale ID.

Certain properties such as the currencySymbol and currencyISOCode properties are set automatically based on the locale.

NOTE: When a fallback locale is used the currency properties are set to default values, and therefore the currencySymbol or currencyISOCode properties might be given unexpected values. It is a good idea to examine the currencySymbol and currencyISOCode property values before formatting a currency amount.

To format based on the user's current operating system preferences, pass the value LocaleID.DEFAULT in the requestedLocaleIDName parameter to the constructor.

When the constructor is called and it completes successfully, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

When the requested locale ID name is not available then the lastOperationStatus is set to one of the following:

• LastOperationStatus.USING_FALLBACK_WARNING
• LastOperationStatus.USING_DEFAULT_WARNING

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

For details on the warnings listed above and other possible values of the lastOperationStatus property, see the descriptions in the LastOperationStatus class.

Related API Elements

Creates a string representing a currency amount formatted according to the current properties of this CurrencyFormatter object, including the locale, currency symbol, and currency ISO code.

By default this method uses the currencyISOCode property to determine the currency symbol and other settings used when formatting.

Many countries and regions use the same currency symbols for different currencies. For example the United States, Australia, New Zealand, Canada, and Mexico all use the same dollar sign symbol ($) for local currency values. When the formatting currency differs from the user's local currency it is best to use the ISO code as the currency string. You can use the formattingWithCurrencySymbolIsSafe() method to test whether the ISO code of the currency to be formatted matches the currencyISOCode property of the formatter.

This method can format numbers of very large and very small magnitudes. However the number of significant digits is limited to the precision provided by the Number data type.

Parameters

Related API Elements

 
         var cf:CurrencyFormatter = new CurrencyFormatter("fr-CA");  
         
         trace(cf.actualLocaleIDName);               // "fr-CA"  
         trace(cf.currencyISOCode);                // "CAD"
         trace(cf.currencySymbol);                // "$"
         
         trace(cf.format(1254.56));                // "1 254,56 CAD"
         trace(cf.format(1254.56, true));            // "1 254,56 $"
         

 
         var cf:CurrencyFormatter = new CurrencyFormatter(LocaleID.DEFAULT);  
         
         if (cf.formattingWithCurrencySymbolIsSafe("CAD")) {
           trace(cf.actualLocaleIDName);     // "fr-CA French (Canada)"
           trace(cf.format(1254.56, false)); // "1 254,56 $"
         }
         else {
           trace(cf.actualLocaleIDName);     // "en-US English (USA)"
           cf.setCurrency("CAD", "C$")
           trace(cf.format(1254.56, true));  // "C$ 1,254.56"
         }
         

Determines whether the currently specified currency symbol can be used when formatting currency amounts.

Many regions and countries use the same currency symbols. This method can be used to safeguard against the use of an ambiguous currency symbol, or a currency symbol or ISO code that is different than expected due to the use of a fallback locale.

A common use case for this method is to determine whether to show a local currency symbol (if the amount is formatted in the user's default currency), or a more specific ISO code string (if the amount is formatted in a currency different from the user's default).

This method compares the requestedISOCode parameter against the current currencyISOCode property, returning true if the strings are equal and false if they are not. When the strings are equal, using the format() method with the withCurrencySymbol parameter set to true results in a formatted currency value string with a unique currency symbol for the locale. If this method returns false, then using the format() method with the withCurrencySymbol parameter set to true could result in the use of an ambiguous or incorrect currency symbol.

When this method is called and it completes successfully, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

Parameters

Related API Elements

Lists all of the locale ID names supported by this class.

If this class is not supported on the current operating system, this method returns a null value.

When this method is called and it completes successfully, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

Parses a string into a currency amount and a currency symbol.

The parsing algorithm uses the value of the decimalSeparator property to determine the integral and fractional portion of the number. It uses the values of the negativeCurrencyFormat and positiveCurrencyFormat properties to determine the location of the currency symbol or string relative to the currency amount. For negative amounts the value of the negativeCurrencyFormat property determines the location of the negative symbol and whether parentheses are used.

If the order of the currency symbol, minus sign, and number in the input string does not match the pattern identified by the negativeCurrencyFormat and positiveCurrencyFormat properties, then:

1. The value property of the returned CurrencyParseResult object is set to NaN.
2. The currencyString property of the returned CurrencyParseResult object is set to null.
3. The lastOperationStatus property is set to indicate that parsing failed.

The input string may include space characters, which are ignored during the parsing.

Parsing can succeed even if there is no currency symbol. No validation is done of the portion of the string corresponding to the currency symbol. If there is no currency symbol or string, the currencyString property in the returned CurrencyParseResult object is set to an empty string.

When this method is called and it completes successfully, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

Parameters

Related API Elements

Sets the currencyISOCode and currencySymbol properties of the CurrencyFormatter object.

When this method is called and it completes successfully, the lastOperationStatus property is set to:

• LastOperationStatus.NO_ERROR

Otherwise the the currencyISOCode and the currencySymbol properties are not modified and the lastOperationStatus property is set to one of the constants defined in the LastOperationStatus class.

Parameters

Related API Elements

This example uses the following locales:

• The default operating system locale for currency formatting (LocaleID.DEFAULT)
• Japanese (Japan)
• English (US)
• French (France)

The example does the following for each locale in the list:

1. Creates a CurrencyFormatter object
2. Uses the formattingWithCurrencySymbolIsSafe() method to check whether the default currency for the locale is Euros ("EUR") and if so it formats the string using the currency symbol. Otherwise it formats the string using the ISO code.

  
package {
    import flash.display.Sprite;
    import flash.globalization.CurrencyFormatter;
    import flash.globalization.LocaleID;
    
    public class CurrencyFormatterExample1 extends Sprite
    {
        public function CurrencyFormatterExample1():void
        {
            var cf:CurrencyFormatter;
            var amountWithSymbol:String;
            var amountWithISOCode:String
            
            var localeNames:Array = [LocaleID.DEFAULT, "ja-JP", "en-US", "fr-FR"];
            
            for each (var localeName:String in localeNames) 
            {
                cf = new CurrencyFormatter(localeName);
                
                trace('\n' + "LocaleID requested=" + cf.requestedLocaleIDName 
                    + "; actual=" + cf.actualLocaleIDName);
                
                trace("Last Operation Status: " + cf.lastOperationStatus );
                
                trace("Currency ISO Code: " + cf.currencyISOCode);
                
                if (cf.formattingWithCurrencySymbolIsSafe("EUR")) 
                {
                    amountWithSymbol = cf.format(123456789.19, true);
                    trace("Format using Symbol: "+ amountWithSymbol);
                }
                else 
                {
                    amountWithISOCode = cf.format(123456789.19); 
                    trace("Format using ISO Code: " + amountWithISOCode);
                }
            }
        }
    }
}

This example takes the following steps:

1. Creates a CurrencyFormatter object for the English (US) locale.
2. Uses the parse() method to parse the input string.
3. Displays the amount and currency string values from the resulting CurrencyParseResult object.

 
package {
      import flash.display.Sprite;
      import flash.globalization.CurrencyFormatter;
      import flash.globalization.CurrencyParseResult;
      import flash.globalization.LastOperationStatus;
      import flash.globalization.LocaleID;

      public class CurrencyFormatterParseExample extends Sprite
      {
            public function CurrencyFormatterParseExample()
            {
                var cf:CurrencyFormatter = new CurrencyFormatter( "en_US" );
                
                trace("LocaleID requested=" + cf.requestedLocaleIDName 
                    + "; actual=" + cf.actualLocaleIDName);
                trace("Last Operation Status: " + cf.lastOperationStatus );

                var inputString:String = "Dollar 123,567,89,0.254";
                
                var result:CurrencyParseResult = cf.parse(inputString);
                
                if (cf.lastOperationStatus == LastOperationStatus.NO_ERROR ) {
                    trace("Amount value: " + result.value); 
                    trace("Currency string: " + result.currencyString); 
                }
            }
      }
}