MidpointRounding Enum

Definition

Namespace:

System

Assembly:

System.Runtime.dll

Specifies the strategy that mathematical rounding methods should use to round a number.

public enum class MidpointRounding

public enum MidpointRounding

type MidpointRounding = 

Public Enum MidpointRounding

Inheritance

Object

ValueType

Enum

MidpointRounding

Fields

AwayFromZero	1	The strategy of rounding to the nearest number, and when a number is halfway between two others, it's rounded toward the nearest number that's away from zero.
ToEven	0	The strategy of rounding to the nearest number, and when a number is halfway between two others, it's rounded toward the nearest even number.
ToNegativeInfinity	3	The strategy of downwards-directed rounding, with the result closest to and no greater than the infinitely precise result.
ToPositiveInfinity	4	The strategy of upwards-directed rounding, with the result closest to and no less than the infinitely precise result.
ToZero	2	The strategy of directed rounding toward zero, with the result closest to and no greater in magnitude than the infinitely precise result.

Examples

The following example demonstrates the Math.Round method in conjunction with the MidpointRounding enumeration:

decimal result;

// Round a positive value using different strategies.
// The precision of the result is 1 decimal place.

result = Math.Round(3.45m, 1, MidpointRounding.ToEven);
Console.WriteLine($"{result} = Math.Round({3.45m}, 1, MidpointRounding.ToEven)");
result = Math.Round(3.45m, 1, MidpointRounding.AwayFromZero);
Console.WriteLine($"{result} = Math.Round({3.45m}, 1, MidpointRounding.AwayFromZero)");
result = Math.Round(3.47m, 1, MidpointRounding.ToZero);
Console.WriteLine($"{result} = Math.Round({3.47m}, 1, MidpointRounding.ToZero)\n");

// Round a negative value using different strategies.
// The precision of the result is 1 decimal place.

result = Math.Round(-3.45m, 1, MidpointRounding.ToEven);
Console.WriteLine($"{result} = Math.Round({-3.45m}, 1, MidpointRounding.ToEven)");
result = Math.Round(-3.45m, 1, MidpointRounding.AwayFromZero);
Console.WriteLine($"{result} = Math.Round({-3.45m}, 1, MidpointRounding.AwayFromZero)");
result = Math.Round(-3.47m, 1, MidpointRounding.ToZero);
Console.WriteLine($"{result} = Math.Round({-3.47m}, 1, MidpointRounding.ToZero)\n");

/*
This code example produces the following results:

3.4 = Math.Round(3.45, 1, MidpointRounding.ToEven)
3.5 = Math.Round(3.45, 1, MidpointRounding.AwayFromZero)
3.4 = Math.Round(3.47, 1, MidpointRounding.ToZero)

-3.4 = Math.Round(-3.45, 1, MidpointRounding.ToEven)
-3.5 = Math.Round(-3.45, 1, MidpointRounding.AwayFromZero)
-3.4 = Math.Round(-3.47, 1, MidpointRounding.ToZero)
*/

Dim result As Decimal = 0D
Dim posValue As Decimal = 3.45D
Dim negValue As Decimal = -3.45D

' Round a positive value using different strategies.
' 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)
result = Math.Round(posValue, 1, MidpointRounding.ToZero)
Console.WriteLine("{0,4} = Math.Round({1,5}, 1, MidpointRounding.ToZero)",
                   result, posValue)
Console.WriteLine()

' Round a negative value using different strategies.
' 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)
result = Math.Round(negValue, 1, MidpointRounding.ToZero)
Console.WriteLine("{0,4} = Math.Round({1,5}, 1, MidpointRounding.ToZero)",
                   result, negValue)
Console.WriteLine()

'This code example produces the following results:
'
'        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.ToZero)
'
'        -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.ToZero)
'

Remarks

Use MidpointRounding with appropriate overloads of Math.Round, MathF.Round, and Decimal.Round to provide more control of the rounding process.

There are two overall rounding strategies, round to nearest and directing rounding, and each enumeration field participates in exactly one of these strategies.

Round to nearest

Fields:

• AwayFromZero
• ToEven

A round-to-nearest operation takes an original number with an implicit or specified precision; examines the next digit, which is at that precision plus one; and returns the nearest number with the same precision as the original number. For positive numbers, if the next digit is from 0 through 4, the nearest number is toward negative infinity. If the next digit is from 6 through 9, the nearest number is toward positive infinity. For negative numbers, if the next digit is from 0 through 4, the nearest number is toward positive infinity. If the next digit is from 6 through 9, the nearest number is toward negative infinity.

If the next digit is from 0 through 4 or 6 through 9, the MidpointRounding.AwayFromZero and MidpointRounding.ToEven do not affect the result of the rounding operation. However, if the next digit is 5, which is the midpoint between two possible results, and all remaining digits are zero or there are no remaining digits, the nearest number is ambiguous. In this case, the round-to-nearest modes in MidpointRounding enable you to specify whether the rounding operation returns the nearest number away from zero or the nearest even number.

The following table demonstrates the results of rounding some negative and positive numbers in conjunction with round-to-nearest modes. The precision used to round the numbers is zero, which means the number after the decimal point affects the rounding operation. For example, for the number -2.5, the digit after the decimal point is 5. Because that digit is the midpoint, you can use a MidpointRounding value to determine the result of rounding. If AwayFromZero is specified, -3 is returned because it is the nearest number away from zero with a precision of zero. If ToEven is specified, -2 is returned because it is the nearest even number with a precision of zero.

Original number	AwayFromZero	ToEven
3.5	4	4
2.8	3	3
2.5	3	2
2.1	2	2
-2.1	-2	-2
-2.5	-3	-2
-2.8	-3	-3
-3.5	-4	-4

Directed rounding

Fields:

• ToNegativeInfinity
• ToPositiveInfinity
• ToZero

A directed-rounding operation takes an original number with an implicit or specified precision and returns the next closest number in a specific direction with the same precision as the original number. Directed modes on MidpointRounding control toward which predefined number the rounding is performed.

The following table demonstrates the results of rounding some negative and positive numbers in conjunction with directed-rounding modes. The precision used to round the numbers is zero, which means the number before the decimal point is affected by the rounding operation.

Original number	ToNegativeInfinity	ToPositiveInfinity	ToZero
3.5	3	4	3
2.8	2	3	2
2.5	2	3	2
2.1	2	3	2
-2.1	-3	-2	-2
-2.5	-3	-2	-2
-2.8	-3	-2	-2
-3.5	-4	-3	-3