Recipe 5.3 Rounding Numbers

5.3.1 Problem

You want to round a number to the nearest integer, decimal place, or interval (such as to the nearest multiple of 5).

5.3.2 Solution

Use Math.round( ) to round a number to the nearest integer. Use Math.floor( ) and Math.ceil( ) to round a number down or up, respectively. Create a custom roundTo( ) method to round a number to a specified number of decimal places or to a specified multiple.

5.3.3 Discussion

There are numerous reasons to round numbers. For example, when displaying the results of a calculation, you might display only the intended precision. Because all arithmetic in ActionScript is performed with floating-point numbers, some calculations result in unexpected floating-point numbers that must be rounded. For example, the result of a calculation may be 3.9999999 in practice even though it should be 4.0 in theory.

The Math.round( ) method returns the nearest integer value of any parameter passed to it:

trace(Math.round(204.499));  // Displays: 204
trace(Math.round(401.5));    // Displays: 402

The Math.floor( ) method rounds down, and the Math.ceil( ) method rounds up:

trace(Math.floor(204.99));   // Displays: 204
trace(Math.ceil(401.01));    // Displays: 402

To round a number to the nearest decimal place:

For example, to round 90.337 to two decimal places, you could use:

trace (Math.round(90.337 / .01) * .01);   // Displays: 90.34

You can use the identical math to round a number to the nearest multiple of an integer. For example, this rounds 92.5 to the nearest multiple of 5:

trace (Math.round(92.5 / 5)  *  5);   // Displays: 95

As another example, this rounds 92.5 to the nearest multiple of 10:

trace (Math.round(92.5 / 10) * 10);   // Displays: 90

You can create a custom Math.roundTo( ) method that encapsulates this functionality. The custom method takes two parameters:

num

The number to round.

roundToInterval

The interval to which to round num. For example, if you want to round to the nearest tenth, use 0.1 as the interval. Or, to round to the nearest multiple of six, use 6.

Here is our custom roundTo( ) method, which is attached directly to the Math object, so it is available throughout the entire movie. You can add this custom method to a Math.as file for easy inclusion in other projects.

Math.roundTo = function (num, roundToInterval) {
  // roundToInterval defaults to 1 (round to the nearest integer).
  if (roundToInterval == undefined) {
    roundToInterval = 1;
  }
  // Return the result.
  return Math.round(num / roundToInterval) * roundToInterval;
};

Here is an example of how to use the Math.roundTo( ) method, assuming it is stored in an external file named Math.as:

#include "Math.as"
trace(Math.roundTo(Math.PI));          // Displays: 3
trace(Math.roundTo(Math.PI, .01));     // Displays: 3.14
trace(Math.roundTo(Math.PI, .0001));   // Displays: 3.1416
trace(Math.roundTo(123.456, 1));       // Displays: 123
trace(Math.roundTo(123.456, 6));       // Displays: 126
trace(Math.roundTo(123.456, .01));     // Displays: 123.46

You might prefer a custom Math.roundDecPl( ) method that rounds a number to a specified number of decimal places. Our custom method takes two parameters:

num

The number to round

decPl

The number of decimal places to which to round num

Here is our custom roundDecPl( ) method, which is attached directly to the Math object, so it is available throughout the entire movie:

Math.roundDecPl = function (num, decPl) {

  // decPl defaults to 0 (round to the nearest integer).
  if (decPl == undefined) {
    decPl = 0;
  }
  // Calculate the value used to multiply the original number, 
  // which is 10 raised to the power of decPl.
  var multiplier = Math.pow(10, decPl);
  // Return the result.
  return Math.round(num * multiplier ) / multiplier;
};

Here is an example of how to use Math.roundDecPl( ), assuming it is stored in an external file named Math.as:

#include "Math.as"
trace(Math.roundDecPl(Math.PI));     // Displays: 3
trace(Math.roundDecPl(Math.PI, 2));  // Displays: 3.14
trace(Math.roundDecPl(Math.PI, 4));  // Displays: 3.1416