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:

1. Decide the number of decimal places to which you want to round. For example, if you want to round 90.337 to 90.34, then you will round to two decimal places, which means that you will round to the nearest .01.

2. Divide the input value by the number chosen in Step 1 (in this case, .01).

3. Use Math.round( ) to round the calculated value from Step 2 to the nearest integer.

4. Multiply the result of Step 3 by the same value that you used to divide in Step 2.

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```

 Preface
 Part II: Remote Recipes
 Part III: Applications
 Appendix A. Unicode Escape Sequences for Latin 1 Characters
 Colophon