Recipe 5.5 Formatting Numbers for Display

5.5.1 Problem

You want to format a number with a custom decimal delimiter, thousands delimiters, and/or leading spaces.

5.5.2 Solution

Create a custom Math.formatNumber( ) method.

5.5.3 Discussion

ActionScript does not include a built-in way to format numbers as strings, so you need to create a custom method to handle this for you. Furthermore, the delimiter used to indicate decimals and thousands varies by country. For example, the number represented as 1,234.56 in the United States is written as 1.234,56 in many countries. Using some basic string, array, and mathematical methods, we can create a custom method to format numbers with a configurable decimal delimiter (i.e., 123.4 or 123,4), configurable thousands delimiters (i.e., 1,234 or 1.234), and optional leading spaces (to align values when using a monospace font).

Our custom Math.formatNumber( ) method accepts four parameters:

num

The number you want to format

thousandsDelim

The value to use for delimiting the thousands, millions, billions, etc. places

decimalDelim

The value to use for delimiting the decimal places

spaceFill

Specifies the number of total spaces the formatted string should occupy (optional)

Here is our method definition, which can be added to Math.as for easy inclusion in your projects:

Math.numberFormat = function (num, thousandsDelim, decimalDelim, spaceFill) {
  // Default to a comma for thousands and a period for decimals.
  if (thousandsDelim == undefined) {thousandsDelim = ",";}
  if (decimalDelim   == undefined) {decimalDelim= ".";}

  // Convert the number to a string and split it at the decimal point.
  parts = String(num).split(".");

  // Take the whole number portion and store it as an array of single characters. 
  // This makes it easier to insert the thousands delimiters, as needed.
  partOneAr = parts[0].split("");

  // Reverse the array so we can process the characters right to left.
  partOneAr.reverse(  );

  // Insert the thousands delimiter after every third character.
  for (var i = 0, counter = 0; i < partOneAr.length; i++) {
    counter++;
    if (counter > 3) {
      counter = 0;
      partOneAr.splice(i, 0, thousandsDelim);
    }
  }

  // Reverse the array again so that it is back in the original order.
  partOneAr.reverse(  );

  // Create the formatted string using decimalDelim, if necessary.
  var val = partOneAr.join("");
  if (parts[1] != undefined) {
    val += decimalDelim + parts[1];
  }

  // If spaceFill is defined, add the necessary number of leading spaces.
  if (spaceFill != undefined) {
    // Store the original length before adding spaces.
    var origLength = val.length;
    for (var i = 0; i < spaceFill - origLength; i++) {
      val = " " + val;
    }
  }

  // Return the value.
  return val;
};

Note that in the preceding example, we store the length of the string prior to prepending it with spaces. If we checked the length within the loop, as follows, the length itself would change for each iteration (because it would count the spaces already added):

// This leads to the wrong result!
for (var i = 0; i < spaceFill - val.length; i++) {
  val = " " + val;
}

Here is another way the loop could be implemented. This time, we intentionally re-test the length of the string with each loop iteration. Note that the loop's initialization and update expressions are empty; only the loop's conditional test is used.

for (; val.length < spaceFill; ) {
  val = " " + val;
}

Here are a few examples of how to use numberFormat( ):

trace(Math.numberFormat(1234.2));               // Displays: "1,234.2"
trace(Math.numberFormat(1234.2, ".", ","));     // Displays: "1.234,2"
// Note the extra leading spaces in the result of the following example.
trace(Math.numberFormat(1234.2, ",", ".", 10)); // Displays: "   1,234.2"

5.5.4 See Also

Recipe 5.3 and Recipe 5.4 can be used to ensure that a certain number of digits are displayed past the decimal point. Then, if you are using a monospaced font, aligning numbers is simply a matter of setting the text field's format to right justification using the TextFormat.align property. Also refer to Recipe 5.6.