## SymRound(theNumber[, numDigits])

##### Last updated October 4, 2002

**Version:** 1 |
**Requires:** CF5 |
**Library:** MathLib

**Description:**

Despite what is conventionally taught, a "5" after the digit to be rounded should not always be rounded up. Five is the exact middle of the digits that are rounded (the digit "0" is not rounded, but just truncated), and thus should only be rounded up half of the time. Non-zero digits after the five mean that it is no longer in the exact middle, so most fives do correctly round up. However, a five which is at the end of the number or which is followed by only zeros should round to the closest *even* number (and thus rounded down half of the time).

**Return Values:**

Returns a numeric value.

**Example:**

```
<cfoutput>
<pre>
<b>x</b> <b>SymRound(x)</b>
(to the nearest tenth ... or 1 decimal place):
1.14 #SymRound(1.14, 1)#
1.15 #SymRound(1.15, 1)#
1.24 #SymRound(1.24, 1)#
1.25 #SymRound(1.25, 1)# *surprised?*
1.25000000000 #SymRound(1.25000000000, 1)# *surprised?*
1.25000000001 #SymRound(1.25000000001, 1)#
1.26 #SymRound(1.26, 1)#
-1.25 #SymRound(-1.25, 1)# *surprised?*
-1.251 #SymRound(-1.251, 1)#
(to the nearest hundred ... or -2 decimal places):
149 #SymRound(149, -2)#
150 #SymRound(150, -2)#
151 #SymRound(151, -2)#
249 #SymRound(249, -2)#
250 #SymRound(250, -2)# *surprised?*
251 #SymRound(251, -2)#
(to the nearest whole number):
2.5 #SymRound(2.5)# *surprised?*
</pre>
</cfoutput>
```

**Parameters:**

Name | Description | Required |
---|---|---|

theNumber | Number you want to round. | Yes |

numDigits | Number of decimal places to round to. | No |

**Full UDF Source: **

```
/**
* Symmetrically rounds any number to a specific decimal point, preventing a common "rounding bias" from skewing results.
* Ver 1.1: Made numDigits an optional parameter instead of required.
*
* @param theNumber Number you want to round. (Required)
* @param numDigits Number of decimal places to round to. (Optional)
* @return Returns a numeric value.
* @author Shawn Seley (shawnse@aol.com)
* @version 1.1, October 4, 2002
*/
function SymRound(theNumber) {
// The decimal-place-rounding foundation of this code was based on Sierra Bufe's (sierra@brighterfusion.com) RoundIt().
var x = 0;
var rounded_down = 0;
var numDigits = 0; // rounds to the nearest whole integer unless a decimal place is specified
if(ArrayLen(Arguments) GTE 2) numDigits = Arguments[2];
// multiply by 10 to the power of the number of digits to be preserved, and remove its sign
x = Abs(theNumber * (10 ^ numDigits));
rounded_down = Int(x);
// round off to an integer, checking for the exception first
if((x -rounded_down EQ 0.5) and (not rounded_down mod 2)) {
// number is an exact-middle "5" AND rounding down is the closest *even* result
x = rounded_down;
} else x = Round(Val(x)); // otherwise round normally
// divide by 10 to the power of the number of digits to be preserved, and restore the number's sign
return x / (10 ^ numDigits) * Sgn(theNumber);
}
```

blog comments powered by Disqus
### Search CFLib.org

### Latest Additions

Kevin Cotton added

date2ExcelDate

May 5, 2016

Raymond Camden added

CapFirst

April 25, 2016

Chris Wigginton added

loremIpsum

January 18, 2016

Gary Stanton added

calculateArrival...

November 19, 2015

Sebastiaan Naafs - van Dijk added

getDaysInQuarter

November 13, 2015