Skip to content

Commit ab53c14

Browse files
committed
clarify non-integral behavior
Fixes #42428 Clarify that `checked` and `unchecked` behavior changes for floating point types (`float`, `double`, and `half`), and has minimal impact for `decimal`.
1 parent 7a3b35e commit ab53c14

File tree

1 file changed

+13
-3
lines changed

1 file changed

+13
-3
lines changed

docs/csharp/language-reference/statements/checked-and-unchecked.md

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "checked and unchecked statements - control the overflow-checking context"
3-
description: "The `checked` and `unchecked` statements control the overflow-checking context. In a checked context, overflow causes an exception to be thrown. In an unchecked context, the result is truncated."
4-
ms.date: 11/22/2022
2+
title: "checked, unchecked statements - overflow-checking context"
3+
description: "Control the overflow-checking context. In a checked context, overflow causes an exception to be thrown. In an unchecked context, the result is truncated."
4+
ms.date: 10/29/2022
55
f1_keywords:
66
- "checked_CSharpKeyword"
77
- "unchecked_CSharpKeyword"
@@ -32,6 +32,16 @@ The `checked` and `unchecked` statements and operators only affect the overflow-
3232

3333
At the preceding example, the first invocation of the `Multiply` local function shows that the `checked` statement doesn't affect the overflow-checking context within the `Multiply` function as no exception is thrown. At the second invocation of the `Multiply` function, the expression that calculates the second argument of the function is evaluated in a checked context and results in an exception as it's textually inside the block of the `checked` statement.
3434

35+
The behavior of `checked` and `unchecked` depends on the type and the operation. Even for integers, things like `unchecked(x / 0)` will always throw because there is no sensible behavior. Developers need to check the behavior for the type being used and the operation being done to understand how the `checked` and `unchecked` keywords will impact their code.
36+
37+
## Numeric types and overflow-checking context
38+
39+
The `checked` and `unchecked` primarily apply to integral types where there is a sensible overflow behavior. The wraparound behavior where `T.MaxValue + 1` becomes `T.MinValue` is sensible in a two's complement value. The represented value is not *correct* since it cannot fit in the storage for the type. Therefore, the bits are representative of the lower n-bits of the full result.
40+
41+
For types like `decimal`, `float`, `double` or `Half` where you have a more complex value being represented or a one's complement representation, wraparound no longer becomes sensible. It can't be used to compute larger or more accurate results, so `unchecked` isn't beneficial.
42+
43+
For `float`, `double`, and `Half` you do have sensible saturating values for `PositiveInfinity` and `NegativeInfinity` so you can detect overflow in an `unchecked` context. For `decimal`, no such limits exist and saturating at `MaxValue` can lead to errors or confusion, so operations using those types throw in both a `checked` and `unchecked` context.
44+
3545
## Operations affected by the overflow-checking context
3646

3747
The overflow-checking context affects the following operations:

0 commit comments

Comments
 (0)