Decimal::Round Method (Decimal, Int32, MidpointRounding)
Rounds a decimal value to a specified precision. A parameter specifies how to round the value if it is midway between two other numbers.
Assembly: mscorlib (in mscorlib.dll)
Parameters
- d
-
Type:
System::Decimal
A decimal number to round.
- decimals
-
Type:
System::Int32
The number of significant decimal places (precision) in the return value.
- mode
-
Type:
System::MidpointRounding
A value that specifies how to round d if it is midway between two other numbers.
Return Value
Type: System::DecimalThe number that is nearest to the d parameter with a precision equal to the decimals parameter. If d is halfway between two numbers, one of which is even and the other odd, the mode parameter determines which of the two numbers is returned. If the precision of d is less than decimals, d is returned unchanged.
| Exception | Condition |
|---|---|
| ArgumentOutOfRangeException | decimals is less than 0 or greater than 28. |
| ArgumentException | mode is not a System::MidpointRounding value. |
| OverflowException | The result is outside the range of a Decimal object. |
The decimals parameter specifies the number of significant decimal places in the return value and ranges from 0 to 28. If decimals is zero, an integer is returned.
In a midpoint value, the value after the least significant digit in the result is precisely half way between two numbers. For example, 3.47500 is a midpoint value if it is to be rounded two decimal places, and 7.500 is a midpoint value if it is to be rounded to an integer. In these cases, the nearest value can't be easily identified without a rounding convention, which is specified by the mode argument. The Round(Decimal, Int32, MidpointRounding) method supports two rounding conventions for handling midpoint values.
- Rounding away from zero.
Midpoint values are rounded to the next number away from zero. For example, 3.75 rounds to 3.8, 3.85 rounds to 3.9, -3.75 rounds to -3.8, and -3.85 rounds to -3.9. This form of rounding is represented by the MidpointRounding::AwayFromZero enumeration member.
Rounding away from zero is the most widely known form of rounding.
- Rounding to even, or banker's rounding
Midpoint values are rounded to the nearest even number. For example, both 3.75 and 3.85 round to 3.8, and both -3.75 and -3.85 round to -3.8. This form of rounding is represented by the MidpointRounding::ToEven enumeration member.
Rounding to nearest is the standard form of rounding used in financial and statistical operations. It conforms to IEEE Standard 754, section 4. When used in multiple rounding operations, it reduces the rounding error that is caused by consistently rounding midpoint values in a single direction. In some cases, this rounding error can be significant.
The following example demonstrates how to use the Round(Decimal, Int32, MidpointRounding) method with the MidpointRounding enumeration.
// This example demonstrates the Math.Round() method in conjunction // with the MidpointRounding enumeration. using namespace System; void main() { Decimal result = (Decimal) 0.0; Decimal posValue = (Decimal) 3.45; Decimal negValue = (Decimal) -3.45; // By default, round a positive and a negative value to the nearest // even number. The precision of the result is 1 decimal place. result = Math::Round(posValue, 1); Console::WriteLine("{0,4} = Math.Round({1,5}, 1)", result, posValue); result = Math::Round(negValue, 1); Console::WriteLine("{0,4} = Math.Round({1,5}, 1)", result, negValue); Console::WriteLine(); // Round a positive value to the nearest even number, then to the // nearest number away from zero. The precision of the result is 1 // decimal place. result = Math::Round(posValue, 1, MidpointRounding::ToEven); Console::WriteLine( "{0,4} = Math.Round({1,5}, 1, MidpointRounding.ToEven)", result, posValue); result = Math::Round(posValue, 1, MidpointRounding::AwayFromZero); Console::WriteLine( "{0,4} = Math.Round({1,5}, 1, MidpointRounding.AwayFromZero)", result, posValue); Console::WriteLine(); // Round a negative value to the nearest even number, then to the // nearest number away from zero. The precision of the result is 1 // decimal place. result = Math::Round(negValue, 1, MidpointRounding::ToEven); Console::WriteLine( "{0,4} = Math.Round({1,5}, 1, MidpointRounding.ToEven)", result, negValue); result = Math::Round(negValue, 1, MidpointRounding::AwayFromZero); Console::WriteLine( "{0,4} = Math.Round({1,5}, 1, MidpointRounding.AwayFromZero)", result, negValue); Console::WriteLine(); } /* This code example produces the following results: 3.4 = Math.Round( 3.45, 1) -3.4 = Math.Round(-3.45, 1) 3.4 = Math.Round( 3.45, 1, MidpointRounding.ToEven) 3.5 = Math.Round( 3.45, 1, MidpointRounding.AwayFromZero) -3.4 = Math.Round(-3.45, 1, MidpointRounding.ToEven) -3.5 = Math.Round(-3.45, 1, MidpointRounding.AwayFromZero) */
Available since 2.0