Round Method (Decimal, Int32, MidpointRounding)
Collapse the table of content
Expand the table of content

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.

Namespace:   System
Assembly:  mscorlib (in mscorlib.dll)

public static decimal Round(
	decimal d,
	int decimals,
	MidpointRounding mode
)

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.Decimal

The 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 System;

class Sample 
{
    public static void Main() 
    {
    decimal result = 0.0m;
    decimal posValue =  3.45m;
    decimal negValue = -3.45m;

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

*/

.NET Framework
Available since 2.0
Return to top
Show:
© 2016 Microsoft