Skip to content

Commit f1fb030

Browse files
SingleAccretionSingleAccretion
authored
Improving midpoint rounding documentation (#4485)
* Change the XML summary for rounding modes * Improve the existing code snippet for round to nearest modes with interpolated strings and more descriptive variable names * Replace 'Remarks' section with 'Rounding to nearest' * Added 'Directed rounding' section
1 parent fc57f7f commit f1fb030

File tree

2 files changed

+42
-29
lines changed

2 files changed

+42
-29
lines changed

‎samples/snippets/csharp/VS_Snippets_CLR/math.midpointrounding/CS/mpr.cs

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -8,43 +8,43 @@ public static void Main()
88
{
99
//<snippet1>
1010
decimal result = 0.0m;
11-
decimal posValue = 3.45m;
12-
decimal negValue = -3.45m;
11+
decimal positiveValue = 3.45m;
12+
decimal negativeValue = -3.45m;
1313

1414
// By default, round a positive and a negative value to the nearest even number.
1515
// The precision of the result is 1 decimal place.
1616

17-
result = Math.Round(posValue, 1);
18-
Console.WriteLine("{0,4} = Math.Round({1,5}, 1)", result, posValue);
19-
result = Math.Round(negValue, 1);
20-
Console.WriteLine("{0,4} = Math.Round({1,5}, 1)", result, negValue);
17+
result = Math.Round(positiveValue, 1);
18+
Console.WriteLine($"{result} = Math.Round({positiveValue}, 1)");
19+
result = Math.Round(negativeValue, 1);
20+
Console.WriteLine($"{result} = Math.Round({negativeValue}, 1)");
2121
Console.WriteLine();
2222

2323
// Round a positive value to the nearest even number, then to the nearest number away from zero.
2424
// The precision of the result is 1 decimal place.
2525

26-
result = Math.Round(posValue, 1, MidpointRounding.ToEven);
27-
Console.WriteLine("{0,4} = Math.Round({1,5}, 1, MidpointRounding.ToEven)", result, posValue);
28-
result = Math.Round(posValue, 1, MidpointRounding.AwayFromZero);
29-
Console.WriteLine("{0,4} = Math.Round({1,5}, 1, MidpointRounding.AwayFromZero)", result, posValue);
26+
result = Math.Round(positiveValue, 1, MidpointRounding.ToEven);
27+
Console.WriteLine($"{result} = Math.Round({positiveValue}, 1, MidpointRounding.ToEven)");
28+
result = Math.Round(positiveValue, 1, MidpointRounding.AwayFromZero);
29+
Console.WriteLine($"{result} = Math.Round({positiveValue}, 1, MidpointRounding.AwayFromZero)");
3030
Console.WriteLine();
3131

3232
// Round a negative value to the nearest even number, then to the nearest number away from zero.
3333
// The precision of the result is 1 decimal place.
3434

35-
result = Math.Round(negValue, 1, MidpointRounding.ToEven);
36-
Console.WriteLine("{0,4} = Math.Round({1,5}, 1, MidpointRounding.ToEven)", result, negValue);
37-
result = Math.Round(negValue, 1, MidpointRounding.AwayFromZero);
38-
Console.WriteLine("{0,4} = Math.Round({1,5}, 1, MidpointRounding.AwayFromZero)", result, negValue);
35+
result = Math.Round(negativeValue, 1, MidpointRounding.ToEven);
36+
Console.WriteLine($"{result} = Math.Round({negativeValue}, 1, MidpointRounding.ToEven)");
37+
result = Math.Round(negativeValue, 1, MidpointRounding.AwayFromZero);
38+
Console.WriteLine($"{result} = Math.Round({negativeValue}, 1, MidpointRounding.AwayFromZero)");
3939
Console.WriteLine();
4040
/*
4141
This code example produces the following results:
4242
43-
3.4 = Math.Round( 3.45, 1)
43+
3.4 = Math.Round(3.45, 1)
4444
-3.4 = Math.Round(-3.45, 1)
4545
46-
3.4 = Math.Round( 3.45, 1, MidpointRounding.ToEven)
47-
3.5 = Math.Round( 3.45, 1, MidpointRounding.AwayFromZero)
46+
3.4 = Math.Round(3.45, 1, MidpointRounding.ToEven)
47+
3.5 = Math.Round(3.45, 1, MidpointRounding.AwayFromZero)
4848
4949
-3.4 = Math.Round(-3.45, 1, MidpointRounding.ToEven)
5050
-3.5 = Math.Round(-3.45, 1, MidpointRounding.AwayFromZero)

‎xml/System/MidpointRounding.xml

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -52,15 +52,15 @@
5252
<summary>Specifies how mathematical rounding methods should process a number that is midway between two numbers.</summary>
5353
<remarks>
5454
<format type="text/markdown"><![CDATA[
55+
## Remarks
56+
Use `MidpointRounding` with appropriate overloads of <xref:System.Math.Round%2A?displayProperty=nameWithType> to provide more control of the rounding process.
57+
58+
### Round to nearest
59+
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.
5560
56-
## Remarks
57-
Use `MidpointRounding` with appropriate overloads of <xref:System.Math.Round%2A?displayProperty=nameWithType> to provide more control of the rounding process.
61+
In the previous cases, 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.
5862
59-
A rounding 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.
60-
61-
In the previous cases, the `MidpointRounding` enumeration does 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 `MidpointRounding` enumeration enables you to specify whether the rounding operation returns the nearest number away from zero or the nearest even number.
62-
63-
The following table demonstrates the results of rounding some negative and positive numbers in conjunction with the values of `MidpointRounding`. 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.
63+
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.
6464
6565
|Original number|AwayFromZero|ToEven|
6666
|---------------------|------------------|------------|
@@ -73,6 +73,19 @@
7373
|-2.8|-3|-3|
7474
|-3.5|-4|-4|
7575
76+
## Directed rounding
77+
A directed rounding operation takes an original number with an implicit or specified precision and returns the next number closest to some predefined one with the same precision as the original number. Directed modes on `MidpointRounding` control toward which predefined number the rounding is performed.
78+
79+
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.
80+
81+
|Original number|ToNegativeInfinity|ToPositiveInfinity|ToZero|
82+
|---------------------|------------------|------------|------|
83+
|2.8|2|3|2|
84+
|2.5|2|3|2|
85+
|2.1|2|3|2|
86+
|-2.1|-3|-2|-2|
87+
|-2.5|-3|-2|-2|
88+
|-2.8|-3|-2|-2|
7689
7790
7891
## Examples
@@ -126,7 +139,7 @@
126139
</ReturnValue>
127140
<MemberValue>1</MemberValue>
128141
<Docs>
129-
<summary>When a number is halfway between two others, it is rounded toward the nearest number that is away from zero.</summary>
142+
<summary>Round to nearest mode: when a number is halfway between two others, it is rounded toward the nearest number that is away from zero.</summary>
130143
</Docs>
131144
</Member>
132145
<Member MemberName="ToEven">
@@ -169,7 +182,7 @@
169182
</ReturnValue>
170183
<MemberValue>0</MemberValue>
171184
<Docs>
172-
<summary>When a number is halfway between two others, it is rounded toward the nearest even number.</summary>
185+
<summary>Round to nearest mode: when a number is halfway between two others, it is rounded toward the nearest even number.</summary>
173186
</Docs>
174187
</Member>
175188
<Member MemberName="ToNegativeInfinity">
@@ -203,7 +216,7 @@
203216
</ReturnValue>
204217
<MemberValue>3</MemberValue>
205218
<Docs>
206-
<summary>When a number is halfway between two others, it is rounded toward the result closest to and no greater than the infinitely precise result.</summary>
219+
<summary>Directed mode: the number is rounded down, with the result closest to and no greater than the infinitely precise result.</summary>
207220
</Docs>
208221
</Member>
209222
<Member MemberName="ToPositiveInfinity">
@@ -237,7 +250,7 @@
237250
</ReturnValue>
238251
<MemberValue>4</MemberValue>
239252
<Docs>
240-
<summary>When a number is halfway between two others, it is rounded toward the result closest to and no less than the infinitely precise result.</summary>
253+
<summary>Directed mode: the number is rounded up, with the result closest to and no less than the infinitely precise result.</summary>
241254
</Docs>
242255
</Member>
243256
<Member MemberName="ToZero">
@@ -271,7 +284,7 @@
271284
</ReturnValue>
272285
<MemberValue>2</MemberValue>
273286
<Docs>
274-
<summary>When a number is halfway between two others, it is rounded toward the result closest to and no greater in magnitude than the infinitely precise result.</summary>
287+
<summary>Directed mode: the number is rounded toward zero, with the result closest to and no greater in magnitude than the infinitely precise result.</summary>
275288
</Docs>
276289
</Member>
277290
</Members>

0 commit comments

Comments
 (0)