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..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,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**. 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 + +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 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 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. + +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:** 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 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.