Add documentation for checked arithmetic operators with examples in F# (#43789)

* Fixed bug 41859.

* Comments fix.

---------

Co-authored-by: Adit Sheth <[email protected]>

Author: shethaadit

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.<br /><br />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 <xref:System.OverflowException> 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 <xref:System.OverflowException> 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 <xref:System.OverflowException> 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.

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.