From cb46cf1ad054a3b0ca60285921ad490f5d7a98af Mon Sep 17 00:00:00 2001 From: Adit Sheth Date: Wed, 27 Nov 2024 09:47:20 -0800 Subject: [PATCH 1/2] Fixed bug 41859. --- .../arithmetic-operators.md | 30 ++++++++++++++++++- .../snippets/fsharp/lang-ref-1/snippet3502.fs | 14 +++++++++ 2 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 samples/snippets/fsharp/lang-ref-1/snippet3502.fs diff --git a/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md b/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md index d39a87e4c0946..681b7ac1ae240 100644 --- a/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md +++ b/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md @@ -9,7 +9,11 @@ This topic describes arithmetic operators that are available in F#. ## Summary of Binary Arithmetic Operators -The following table summarizes the binary arithmetic operators that are available for unboxed integral and floating-point types. +Arithmetic operations in F# can be performed in two modes: **Unchecked** and **Checked**. Unchecked operators prioritize performance but allow overflow/underflow, while checked operators prioritize safety by throwing exceptions in such cases. + +### Unchecked Arithmetic Operators + +The following table summarizes the binary arithmetic operators that are available for **Unchecked Arithmetic** with unboxed integral and floating-point types. |Binary operator|Notes| |---------------|-----| @@ -20,6 +24,30 @@ The following table summarizes the binary arithmetic operators that are availabl |`%` (remainder, rem)|Returns the remainder of a division operation. The sign of the result is the same as the sign of the first operand.| |`**` (exponentiation, to the power of)|Possible overflow condition when the result exceeds the maximum absolute value for the type.

The exponentiation operator works only with floating-point types.| +The unchecked behavior does not throw exceptions when overflow occurs, making it less safe for arithmetic on large or edge-case values. + +### Checked Arithmetic Operators + +The following table summarizes the binary arithmetic operators that are available for **Checked Arithmetic** with unboxed integral types. Checked operators ensure that calculations are verified for overflow or underflow, providing safer arithmetic for critical applications. + +| Binary Operator | Notes | +|------------------|----------------------------------------------------------------------------------------| +| `+` (addition, plus) | Throws an if the result exceeds the maximum absolute value supported by the type. | +| `-` (subtraction, minus) | Throws an if the result goes below the minimum value supported by the type. | +| `*` (multiplication, times) | Throws an if the product exceeds the maximum absolute value supported by the type. | + +The checked operators are useful for ensuring that arithmetic overflows are caught and handled explicitly. + +Here’s an example: + +[!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-1/snippet3502.fs)] + +### Choosing Between Checked and Unchecked Operators + +**Checked Operators:** Ideal for scenarios where overflow errors must be detected and handled explicitly. + +**Unchecked Operators:** Provide faster arithmetic operations but may silently produce incorrect results when overflow occurs. You can use with caution. + ## Summary of Unary Arithmetic Operators The following table summarizes the unary arithmetic operators that are available for integral and floating-point types. diff --git a/samples/snippets/fsharp/lang-ref-1/snippet3502.fs b/samples/snippets/fsharp/lang-ref-1/snippet3502.fs new file mode 100644 index 0000000000000..fc011d30a8047 --- /dev/null +++ b/samples/snippets/fsharp/lang-ref-1/snippet3502.fs @@ -0,0 +1,14 @@ +open Microsoft.FSharp.Core.Operators.Checked + +let safeAddition () = + try + let result = 2147483647 + 1 // Attempt to add integers at their maximum boundary + printfn "Result: %d" result + with + | :? System.OverflowException as ex -> + printfn "Overflow occurred: %s" ex.Message + +safeAddition() + +// Output: +// Overflow occurred: Arithmetic operation resulted in an overflow. From 43b0c551bb4d42a84a4c372661ff6599d781710b Mon Sep 17 00:00:00 2001 From: Adit Sheth Date: Tue, 3 Dec 2024 22:40:31 -0800 Subject: [PATCH 2/2] Comments fix. --- .../arithmetic-operators.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md b/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md index 681b7ac1ae240..1561f5867cf35 100644 --- a/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md +++ b/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md @@ -9,7 +9,7 @@ This topic describes arithmetic operators that are available in F#. ## Summary of Binary Arithmetic Operators -Arithmetic operations in F# can be performed in two modes: **Unchecked** and **Checked**. Unchecked operators prioritize performance but allow overflow/underflow, while checked operators prioritize safety by throwing exceptions in such cases. +Arithmetic operations in F# can be performed in two modes: **Unchecked** and **Checked**. By default, arithmetic operations use unchecked behavior, which prioritizes performance but allows overflow/underflow. Checked operators prioritize safety by throwing exceptions in such cases. ### Unchecked Arithmetic Operators @@ -24,17 +24,17 @@ The following table summarizes the binary arithmetic operators that are availabl |`%` (remainder, rem)|Returns the remainder of a division operation. The sign of the result is the same as the sign of the first operand.| |`**` (exponentiation, to the power of)|Possible overflow condition when the result exceeds the maximum absolute value for the type.

The exponentiation operator works only with floating-point types.| -The unchecked behavior does not throw exceptions when overflow occurs, making it less safe for arithmetic on large or edge-case values. +The unchecked behavior does not throw exceptions when overflow or underflow occurs, making it less safe for arithmetic on large or edge-case values. ### Checked Arithmetic Operators The following table summarizes the binary arithmetic operators that are available for **Checked Arithmetic** with unboxed integral types. Checked operators ensure that calculations are verified for overflow or underflow, providing safer arithmetic for critical applications. -| Binary Operator | Notes | -|------------------|----------------------------------------------------------------------------------------| -| `+` (addition, plus) | Throws an if the result exceeds the maximum absolute value supported by the type. | -| `-` (subtraction, minus) | Throws an if the result goes below the minimum value supported by the type. | -| `*` (multiplication, times) | Throws an if the product exceeds the maximum absolute value supported by the type. | +| Binary Operator | Notes | +|------------------|----------------------------------------------------------------------------------------| +| `+` (addition, plus) | Throws an if the result exceeds the maximum value or goes below the minimum value supported by the type. Both **Overflow** and **Underflow** are possible. | +| `-` (subtraction, minus) | Throws an if the result exceeds the maximum value or goes below the minimum value supported by the type. Both **Overflow** and **Underflow** are possible. | +| `*` (multiplication, times) | Throws an if the product exceeds the maximum value or goes below the minimum value supported by the type. Both **Overflow** and **Underflow** are possible. | The checked operators are useful for ensuring that arithmetic overflows are caught and handled explicitly. @@ -46,7 +46,7 @@ Here’s an example: **Checked Operators:** Ideal for scenarios where overflow errors must be detected and handled explicitly. -**Unchecked Operators:** Provide faster arithmetic operations but may silently produce incorrect results when overflow occurs. You can use with caution. +**Unchecked Operators:** By default, F# uses unchecked arithmetic for performance reasons. These operations may silently produce incorrect results when overflow or underflow occurs. Use with caution. ## Summary of Unary Arithmetic Operators