Recipe 4.4. Inserting Leading or Trailing Zeros or Spaces

Problem

You want to add leading or trailing zeros or spaces to a number to display it as a string.

Solution

Use the custom NumberFormat class, apply a mask, and then call the format( ) method.

Discussion

You might need to format numbers with leading or trailing zeros or spaces for display purposes, such as when displaying times or dates. For example, you would want to format 6 hours and 3 minutes as 6:03 or 06:03, not 6:3. Additionally, sometimes you'll want to apply leading and/or trailing spaces to align the columns of several numbers; for example:

123456789
  1234567
    12345

Although you can certainly work out the algorithms on your own to add leading or trailing characters, you'll likely find working with a NumberFormat object much faster, simpler, and more flexible. The NumberFormat class is a custom class included with the downloads for this book at http://www.rightactionscript.com/ascb. That class is part of the ascb.util package, so the first thing you'll want to do is make sure you have an import statement:

import ascb.util.NumberFormat;

Next you need to determine the mask that you'll use to format the number. The mask can consist of zeros (0), pound signs (#), dots (.), and commas (,); any other characters are disregarded.

Zeros (0): Placeholders that are either filled with the corresponding digit or a zero.
Pound signs (#): Placeholders that are either filled with the corresponding digit or a space.
Dots (.): Decimal point placeholders; they can be replaced by the localized decimal point symbol.
Commas (,): Placeholders for grouping symbols; they are replaced by the localized grouping symbol.

To better understand this, it can be helpful to take a look at some examples; consider the following mask:

##,###.0000

When the preceding mask is used with the numbers 1.2345, 12.345, 123.45, 1234.5, and 12345, the results are as follows (assuming that the localized settings apply commas as grouping symbols and dots as decimal points):

     1.2345
    12.3450
   123.4500
 1,234.5000
12,345.0000

You can set the mask for a NumberFormat object in several ways. You can specify the mask as a parameter when you construct the object, as follows:

var styler:NumberFormat = new NumberFormat("##,###.0000");

Additionally, you can use the mask property of the object to change the mask at any point:

styler.mask = "##.00";

The mask property is a read-write property, so you can also retrieve the current mask string by reading the value from the property.

Once a mask has been applied to a NumberFormat object, you can format any number value by calling the format( ) method and passing the number as a parameter:

trace(styler.format(12345);

The following code is a complete, working example that illustrates the features of the NumberFormat class that have been discussed so far:

var styler:NumberFormat = new NumberFormat("#,###,###,###");

trace(styler.format(1));
trace(styler.format(12));
trace(styler.format(123));
trace(styler.format(1234));

styler.mask = "#,###,###,###.0000";

trace(styler.format(12345));
trace(styler.format(123456));
trace(styler.format(1234567));
trace(styler.format(12345678));
trace(styler.format(123456789));

The output from the preceding example is as follows (assuming U.S.-style localization settings):

            1
           12
          123
        1,234
       12,345.0000
      123,456.0000
    1,234,567.0000
   12,345,678.0000
  123,456,789.0000

By default, NumberFormat objects attempt to automatically localize the return values. If the Flash Player is running on a U.S. English operating system, the NumberFormat class uses commas as grouping symbols and dots as decimal points. On the other hand, if the computer is running a French operating system, the symbols are reversed; dots for grouping symbols and commas for decimal points. There are several reasons why you may opt to override the automatic localization, including:

You want the numbers to be formatted in a standard way regardless of the operating system on which the Flash application is run.
Automatic localization doesn't work properly. This may occur in some situations for at least two reasons:
- The Locale class (the class used by NumberFormat to determine the correct localization settings) may not include some languages/countries.
- The Flash Player does not report very specific settings. It only reports the language code. Because of that, it may be difficultto nearly impossibleto correctly calculate the locale to use.

There are a variety of ways you can override the automatic localization settings:

Pass a Locale object to the format( ) method as a second parameter. The format( ) method then uses the settings from that Locale object instead of the automatic settings. This option works well when you want to apply different custom localization settings each time you call the format( ) method. You can create a Locale object by using the constructor. With no parameters, the Locale object uses automatic localization detection, so you'll want to pass it one or two parameters. The first parameter is the language code (e.g., en). The second parameter is the country code (e.g., US), also called the variant. You should only specify the variant if there are different regions that use the same language, but use different formatting. For example, the language code es (Spanish) could potentially apply to many countries, including Mexico (MX) and Spain (ES)both of which use different symbols to format numbers.
Set the Locale.slanguage and/or Locale.svariant properties to set the localization properties globally. You don't need to specify any additional parameters when calling format( ) with this option. Simply assign values to the static properties, Locale.slanguage and/or Locale.svariant; those settings affect any subsequent calls to format( ).
Use a symbols object as the second parameter when calling format( ). The symbols object should have two properties: group and decimal. The values for those properties allow you to define the symbols to use when formatting the number. This option is best when the Locale object does not have settings for the locale that you want and/or when you want to use custom formatting symbols.

The Locale class is in the ascb.util package, so be sure to import that class if you want to use it.

The following example illustrates some of the ways you can override the automatic localization settings:

var styler:NumberFormat = new NumberFormat("#,###,###,###.00");

Locale.slanguage = "fr";
trace(styler.format(1234));
trace(styler.format(12345, {group: ",", decimal: "."}));
trace(styler.format(123456));
Locale.slanguage = "en";
trace(styler.format(1234567));
trace(styler.format(12345678, new Locale("es", "ES")));
trace(styler.format(123456789, {group: "|", decimal: ","}));

The preceding code displays the following:

        1.234,00
       12,345.00
      123.456,00
    1,234,567.00
   12.345.678,00
  123|456|789,00