# CFLib.org – Common Function Library Project

## SymRound(theNumber[, numDigits])

##### Last updated October 04, 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 &quot;rounding bias&quot; from skewing results.
*
* @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;

// 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);

}
``````

### Search CFLib.org Raymond Camden added
QueryDeleteRows
November 04, 2017 Leigh added
May 11, 2016 Raymond Camden added
stripHTML
May 10, 2016 Kevin Cotton added
date2ExcelDate
May 05, 2016 Raymond Camden added
CapFirst
April 25, 2016

Created by Raymond Camden / Design by Justin Johnson