Apache Flex 4.16.0 API Reference | All Packages | All Classes | Index | Frames No Frames |
NumberFormatter

Package | spark.formatters
Class | public class NumberFormatter
Inheritance | NumberFormatter NumberFormatterBase GlobalizationBase AdvancedStyleClient flash.events.EventDispatcher
Implements | IFormatter

Language Version : | ActionScript 3.0

Product Version : | Flex 4.5

Runtime Versions : | Flash Player 10.1, AIR 2.5

The NumberFormatter class provides locale-sensitive formatting and parsing of numeric values. It can format `int`, `uint`, and `Number` objects.

This class is a wrapper class around the flash.globalization.NumberFormatter class. Therefore, the locale-specific formatting is provided by the flash.globalization.NumberFormatter. However, this NumberFormatter class can be used in MXML declarations, uses the locale style for the requested Locale ID name, and has methods and properties that are bindable.

The flash.globalization.NumberFormatter class use the underlying operating system for the formatting functionality and to supply the locale-specific data. On some operating systems, the flash.globalization classes are unsupported, on these systems this wrapper class provides fallback functionality.

MXML Syntax Show MXML Syntax
Hide MXML Syntax

The `<s:NumberFormatter>` tag inherits all of the tag attributes of its superclass and adds the following tag attributes:

      <s:NumberFormatter
        Properties
        negativeNumberFormat="locale and OS dependent"
      />

View the examples

See also

flash.globalization.NumberFormatter

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | actualLocaleIDName : String [override] [read-only] The name of the actual locale ID used by this class object. | NumberFormatter
|  | className : String [read-only] The name of the component class. | AdvancedStyleClient
|  | decimalSeparator : String The decimal separator character used for formatting or parsing numbers that have a decimal part. | NumberFormatterBase
|  | digitsType : uint Defines the set of digit characters to be used when formatting numbers. | NumberFormatterBase
|  | errorText : String Replacement string returned by the format() method when an error occurs. | NumberFormatterBase
|  | fractionalDigits : int The maximum number of digits that can appear after the decimal separator. | NumberFormatterBase
|  | groupingPattern : String Describes the placement of grouping separators within the formatted number string. | NumberFormatterBase
|  | groupingSeparator : String The character or string used for the grouping separator. | NumberFormatterBase
|  | id : String The identity of the component. | AdvancedStyleClient
|  | inheritingStyles : Object An object containing the inheritable styles for this non-visual style client instance. | AdvancedStyleClient
|  | lastOperationStatus : String [override] [read-only] The status of the most recent operation that this class object performed. | NumberFormatterBase
|  | leadingZero : Boolean Specifies whether a leading zero is included in a formatted number when there are no integer digits to the left of the decimal separator. | NumberFormatterBase
|  | moduleFactory : IFlexModuleFactory A module factory is used as context for finding the style manager that controls the styles for this non-visual style client instance. | AdvancedStyleClient
|  | negativeNumberFormat : uint A numeric value that indicates a formatting pattern for negative numbers. | NumberFormatter
|  | negativeSymbol : String The negative symbol to be used when formatting negative values. | NumberFormatterBase
|  | nonInheritingStyles : Object The beginning of this component's chain of non-inheriting styles. | AdvancedStyleClient
|  | styleDeclaration : CSSStyleDeclaration The style declaration that holds the inline styles declared by this object. | AdvancedStyleClient
|  | styleManager : IStyleManager2 [read-only] Returns the StyleManager instance used by this component. | AdvancedStyleClient
|  | styleName : Object The source of this object's style values. | AdvancedStyleClient
|  | styleParent : IAdvancedStyleClient A component's parent is used to evaluate descendant selectors. | AdvancedStyleClient
|  | trailingZeros : Boolean Specifies whether trailing zeros are included in a formatted number. | NumberFormatterBase
|  | useGrouping : Boolean Enables the use of the grouping separator when formatting numbers. | NumberFormatterBase

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | NumberFormatter() Constructs a new NumberFormatter object to format numbers according to the conventions of a given locale. | NumberFormatter
|  | clearStyle(styleProp:String):void Deletes a style property from this component instance. | AdvancedStyleClient
|  | format(value:Object):String Formats a number. | NumberFormatter
|  | getAvailableLocaleIDNames():Vector.<String> [static] Lists all of the locale ID names supported by this class. | NumberFormatter
|  | getClassStyleDeclarations():Array Returns an Array of CSSStyleDeclaration objects for the type selector that applies to this component, or null if none exist. | AdvancedStyleClient
|  | getStyle(styleProp:String):* [override] Gets a style property that has been set anywhere in this component's style lookup chain. | GlobalizationBase
|  | hasCSSState():Boolean Returns true if currentCSSState is not null. | AdvancedStyleClient
|  | initialized(document:Object, id:String):void The initialized method is called when this class or a class that extends this class is used in an MXML declaration. | AdvancedStyleClient
|  | matchesCSSState(cssState:String):Boolean Returns true if cssState matches currentCSSState. | AdvancedStyleClient
|  | matchesCSSType(cssType:String):Boolean Determines whether this instance is the same as, or is a subclass of, the given type. | AdvancedStyleClient
|  | notifyStyleChangeInChildren(styleProp:String, recursive:Boolean):void Propagates style changes to the children of this style client instance. | AdvancedStyleClient
|  | parse(inputString:String):NumberParseResult Parses a string and returns a NumberParseResult object containing the parsed elements. | NumberFormatter
|  | parseNumber(parseString:String):Number Parses a string that contains only digits and optional whitespace characters and returns a Number. | NumberFormatter
|  | regenerateStyleCache(recursive:Boolean):void Sets up the internal style cache values so that the getStyle() method functions. | AdvancedStyleClient
|  | registerEffects(effects:Array):void Registers the EffectManager as one of the event listeners for each effect event. | AdvancedStyleClient
|  | setStyle(styleProp:String, newValue:*):void Sets a style property on this component instance. | AdvancedStyleClient
|  | styleChanged(styleProp:String):void Detects changes to style properties. | AdvancedStyleClient
|  | stylesInitialized():void Flex calls the stylesInitialized() method when the styles for a component are first initialized. | AdvancedStyleClient

Protected Methods
Show Inherited Protected Methods
Show Inherited Protected Methods

| Method | Defined By
--- | --- | ---
|  | setDeferredStyles():void | AdvancedStyleClient

Events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | change | The change event is generated whenever the locale style is changed or another property is set that would cause the format of a number to change or cause updates to the other values available through this class. | GlobalizationBase

Styles
Hide Inherited Styles
Show Inherited Styles

| Style | Description | Defined By
--- | --- | --- | ---
|  | locale | Type: String CSS Inheritance: yes The locale identifier that specifies the language, region, script and optionally other related tags and keys. See also http://www.unicode.org/reports/tr35/ | GlobalizationBase

Property Detail

actualLocaleIDName | property

`actualLocaleIDName:String` [read-only] [override]

Language Version : | ActionScript 3.0

Product Version : | Flex 4.5

Runtime Versions : | Flash Player 10.1, AIR 2.5

The name of the actual locale ID used by this class object. This is the locale that is used to access the formatting data and functionality from the operating system.

If the locale that was set by the `locale` style is not available, then the value of the `actualLocaleIDName` is different from the value of the `locale` style. It indicates the fallback locale that is being used. If the locale style was set to `LocaleID.DEFAULT` the name of the locale specified by the user's operating system is used.

This property can be used as the source for data binding.

Implementation
`public function get actualLocaleIDName():String`

See also

flash.globalization.NumberFormatter.actualLocaleIDName
NumberFormatter()

negativeNumberFormat | property |

`negativeNumberFormat:uint`

Language Version : | ActionScript 3.0

Product Version : | Flex 4.5

Runtime Versions : | Flash Player 10.1, AIR 2.5

A numeric value that indicates a formatting pattern for negative numbers. This pattern defines the location of the negative symbol or parentheses in relation to the numeric portion of the formatted number.

The following table summarizes the possible formats for negative numbers. When a negative number is formatted, the minus sign in the format is replaced with the value of the `negativeSymbol` property and the 'n' character is replaced with the formatted numeric value.

Negative number format type | Format
0 | (n)
1 | -n
2 | - n
3 | n-
4 | n -

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

This property can be used as the source for data binding.

Implementation
`public function get negativeNumberFormat():uint`
`public function set negativeNumberFormat(value:uint):void`
Throws

| `ArgumentError` — if the assigned value is not a number between 0 and 4.

See also

negativeSymbol
format()
Constructor Detail

NumberFormatter | () | Constructor

`public function NumberFormatter()`

Language Version : | ActionScript 3.0

Product Version : | Flex 4.5

Runtime Versions : | Flash Player 10.1, AIR 2.5

Constructs a new NumberFormatter object to format numbers according to the conventions of a given locale.

The locale for this class is supplied by the locale style. The locale style can be set in several ways:

- By using the class in an MXML declaration and inheriting the locale from the document that contains the declaration. Example:

            <fx:Declarations>
                   <s:NumberFormatter id="nf" />
            </fx:Declarations>

- By using an MXML declaration and specifying the locale value in the list of assignments. Example:

            <fx:Declarations>
                <s:NumberFormatter id="nf_French_France" locale="fr_FR" />
            </fx:Declarations>

- Calling the setStyle method. For example:

            nf.setStyle("locale", "fr-FR")

- Inheriting the style from a `UIComponent` by calling the UIComponent's `addStyleClient()` method.

If the `locale` style is not set by one of the above techniques, the instance of this class will be added as a `StyleClient` to the `topLevelApplication` and will therefore inherit the `locale` style from the `topLevelApplication` object when the `locale` dependent property getter or `locale` dependent method is called.

Most of the properties of this class are automatically set based on the locale style. If the locale style is changed, any properties that have not been explicitly set will also be updated based on the new locale. Note that the actual locale that is used is specified by the actualLocaleIDName property.

See also

actualLocaleIDName
lastOperationsStatus
Method Detail

format | () | method

`public function format(value:Object):String`

Language Version : | ActionScript 3.0

Product Version : | Flex 4.5

Runtime Versions : | Flash Player 10.1, AIR 2.5

Formats a number.

This function formats the number based on the property values of the formatter. If the properties are not modified after the `locale` style is set, the numbers are formatted according to the locale-specific conventions provided by the operating system for the locale identified by the `actualLocaleIDName` property. To customize the format, the properties can be altered to control specific aspects of formatting a number.

Very large numbers and very small magnitude numbers can be formatted with this function. However, the number of significant digits is limited to the precision provided by the `Number` object. Scientific notation is not supported.

If there is an error when formatting, due to an illegal input value or other error, by default the `format()` method returns `null`. However if the `errorText` property is non-null, then the value of the `errorText` property is returned. The `lastOperationStatus` property will be set to indicate the error that occurred.

Parameters

| `value:Object` — An object containing a number value to format. If the object is not a `Number` then it is converted to a number using the `Number()` conversion function.

Returns

| `String` — A formatted number string.

See also

NumberFormatter
spark.formatters.supportClasses.NumberFormatterBase.errorText
lastOperationStatus

getAvailableLocaleIDNames | () | method |

`public static function getAvailableLocaleIDNames():Vector.<String>`

Language Version : | ActionScript 3.0

Product Version : | Flex 4.5

Runtime Versions : | Flash Player 10.1, AIR 2.5

Lists all of the locale ID names supported by this class. This is a list of locales supported by the operating system, not a list of locales that the ResourceManager has resources for.

Returns

| `Vector.<String>` — A vector of strings containing all of the locale ID names supported by this class and operating system.

parse | () | method |

`public function parse(inputString:String):NumberParseResult`

Language Version : | ActionScript 3.0

Product Version : | Flex 4.5

Runtime Versions : | Flash Player 10.1, AIR 2.5

Parses a string and returns a `NumberParseResult` object containing the parsed elements.

The `NumberParseResult` object contains the value of the first number found in the input string, the starting index for the number within the string, and the index of the first character after the number in the string.

If the string does not contain a number, the value property of the NumberParseResult is set to `NaN` and the `startIndex` and `endIndex` properties are set to the hexadecimal value `0x7fffffff`.

This function uses the value of the `decimalSeparator` property to determine the portion of the number that contains fractional digits, and the `groupingSeparator` property to determine which characters are allowed within the digits of a number, and the `negativeNumberFormat` property to control how negative values are represented.

The following table identifies the result of strings parsed for the various `NegativeNumberFormat` values:

NegativeNumberFormat | Input String | Result
(n) | "(123)" or "( 123 )" | "-123"
-n | "-123" or "- 123" | "-123"
- n | "-123" or "- 123" | "-123"
n- | "123-" or "123 -" | "-123"
n - | "123-" or "123 -" | "-123"

A single white space is allowed between the number and the minus sign or parenthesis. A white space character is a character that has a Space Separator (Zs) property in the Unicode Character Database. For more information, see http://www.unicode.org/ucd/).

Other properties are ignored when determining a valid number. Specifically the value of the `digitsType` property is ignored and the digits can be from any of the digit sets that are enumerated in the `NationalDigitsType` class. The values of the `groupingPattern` and `useGrouping` properties do not influence the parsing of the number.

If numbers are preceded or followed in the string by a plus sign '+', the plus sign is treated as a character that is not part of the number.

This function does not parse strings containing numbers in scientific notation (e.g. 1.23e40).

Parameters

| `inputString:String` — The input string to parse.

Returns

| `NumberParseResult` — A `NumberParseResult` object containing the numeric value and the indices for the start and end of the portion of the string that contains the number.

Throws

| `TypeError` — if the `inputString` parameter is null.

See also

flash.globalization.NumberParseResult
parseNumber()
flash.globalization.NationalDigitsType
Example
The following code parses a number from a string and retrieves the prefix and suffix:

          var nf:NumberFormatter = new NumberFormatter();
          nf.setStyle("locale","fr-FR");
          var str:String = "1,56 mètre"
          var result:NumberParseResult = nf.parse(str);
          trace(result.value) // 1.56
          trace(str.substr(0,result.startIndex));                // ""
          trace(str.substr(result.startIndex, result.endIndex)); // "1,56"
          trace(str.substr(result.endIndex));                 // " mètre"

parseNumber | () | method |

`public function parseNumber(parseString:String):Number`

Language Version : | ActionScript 3.0

Product Version : | Flex 4.5

Runtime Versions : | Flash Player 10.1, AIR 2.5

Parses a string that contains only digits and optional whitespace characters and returns a Number. If the string does not begin with a number or contains characters other than whitespace that are not part of the number, then this method returns `NaN`. White space before or after the numeric digits is ignored.

If the numeric digit is preceded or followed by a plus sign '+' it is treated as a non-whitespace character. The return value is `NaN`.

See the description of the parse function for more information about number parsing and what constitutes a valid number.

Parameters

| `parseString:String` — The input string to parse.

Returns

| `Number` — A `Number` object containing the numeric value.

Throws

| `TypeError` — if the `parseString` is `null`

See also

parse()
flash.globalization.NationalDigitsType
Examples
NumberFormatterExample1.mxml

    <?xml version="1.0" encoding="utf-8"?>
    <!--

      Licensed to the Apache Software Foundation (ASF) under one or more
      contributor license agreements.  See the NOTICE file distributed with
      this work for additional information regarding copyright ownership.
      The ASF licenses this file to You under the Apache License, Version 2.0
      (the "License"); you may not use this file except in compliance with
      the License.  You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

    -->
    <!-- Sample program for spark.formatters.NumberFormatter -->
    <s:Application
        xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/mx">

        <fx:Declarations>
            <s:NumberFormatter id="numberFormatter"/>
        </fx:Declarations>

        <fx:Script>
            <![CDATA[
                [Bindable]
                private var number:Number = 123456789.123456789;
            ]]>
        </fx:Script>

        <s:Form>
            <s:FormItem label="Input Locale ID Name">
                <s:HGroup>
                    <s:TextInput id="inputLocaleIDName"/>
                    <!-- Upon button click, sets the locale style on the document
                    UI component. The formatter will inherit this style. -->
                    <s:Button click="setStyle('locale', inputLocaleIDName.text);"
                              label="Apply"/>
                </s:HGroup>
                <s:Label text="Example: 'en-US', 'fr-FR', 'ja-JP', 'ar-SA'"/>
            </s:FormItem>
            <s:FormItem label="Use Grouping">
                <s:CheckBox id="useGrouping"
                             change="numberFormatter.useGrouping = useGrouping.selected"/>
            </s:FormItem>
            <s:FormItem label="Fractional Digits">
                <s:TextInput id="fractionalDigits"
                              change="numberFormatter.fractionalDigits = Number(fractionalDigits.text)"/>
            </s:FormItem>
            <s:FormItem label="Actual Locale ID Name">
                <s:Label text="{numberFormatter.actualLocaleIDName}"/>
            </s:FormItem>
            <s:FormItem label="Formatted Result">
                <s:Label text="{numberFormatter.format(number)}"/>
            </s:FormItem>
        </s:Form>
    </s:Application>

NumberFormatterExample2.mxml

    <?xml version="1.0" encoding="utf-8"?>
    <!--

      Licensed to the Apache Software Foundation (ASF) under one or more
      contributor license agreements.  See the NOTICE file distributed with
      this work for additional information regarding copyright ownership.
      The ASF licenses this file to You under the Apache License, Version 2.0
      (the "License"); you may not use this file except in compliance with
      the License.  You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

    -->
    <!-- Sample program for spark.formatters.NumberFormatter -->
    <s:Application
        xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/mx">

        <fx:Declarations>
            <s:NumberFormatter id="numberFormatter"/>
        </fx:Declarations>

        <s:Form>
            <s:FormItem label="Input Locale ID Name">
                <s:HGroup>
                    <s:TextInput id="inputLocaleIDName"/>
                    <!-- Upon button click, sets the locale style on the document
                    UI component. The formatter will inherit this style. -->
                    <s:Button click="setStyle('locale', inputLocaleIDName.text);"
                              label="Apply"/>
                </s:HGroup>
                <s:Label text="Example: 'en-US', 'fr-FR', 'ja-JP', 'ar-SA'"/>
            </s:FormItem>
            <s:FormItem label="Input Number">
                <s:TextInput id="inputNumber"/>
                <s:Label text="Example: {numberFormatter.format(123456789.123)}"/>
            </s:FormItem>
            <s:FormItem label="Actual Locale ID Name">
                <s:Label text="{numberFormatter.actualLocaleIDName}"/>
            </s:FormItem>
            <s:FormItem label="Parsed Result">
                <s:Label
                    text="{numberFormatter.parseNumber(inputNumber.text).toString()}"/>
            </s:FormItem>
        </s:Form>
    </s:Application>

Sun Mar 5 2017, 03:42 PM +11:00