Add generic driver function

doc/modules/ROOT/nav.adoc

@@ -6,13 +6,16 @@
 ** xref:examples.adoc#examples_overflowing[Overflowing Arithmetic]
 ** xref:examples.adoc#examples_checked[Checked Arithmetic]
 ** xref:examples.adoc#examples_wrapping[Wrapping Arithmetic]
+** xref:examples.adoc#examples_strict[Strict Arithmetic]
+** xref:examples.adoc#examples_generic[Generic Policy-Parameterized Arithmetic]
 ** xref:examples.adoc#examples_charconv[Character Conversion]
 ** xref:examples.adoc#examples_fmt_format[Formatting]
 * xref:api_reference.adoc[]
 ** xref:api_reference.adoc#api_types[Types]
 ** xref:api_reference.adoc#api_functions[Functions]
 ** xref:api_reference.adoc#api_headers[Headers]
 * xref:unsigned_integers.adoc[]
+* xref:policies.adoc[]
 * xref:limits.adoc[]
 * xref:format.adoc[]
 * xref:charconv.adoc[]

doc/modules/ROOT/pages/api_reference.adoc

@@ -33,6 +33,16 @@ https://www.boost.org/LICENSE_1_0.txt
 | Safe unsigned 128-bit integer
 |===
 
+=== Enumerations
+
+[cols="1,2", options="header"]
+|===
+| Type | Description
+
+| xref:policies.adoc[`overflow_policy`]
+| Enum class specifying the overflow handling policy for arithmetic operations
+|===
+
 [#api_functions]
 == Functions
 
@@ -42,13 +52,38 @@ https://www.boost.org/LICENSE_1_0.txt
 |===
 | Function | Description
 
-| xref:charconv.adoc#to_chars[`to_chars`]
+| xref:charconv.adoc[`to_chars`]
 | Converts a safe integer to a character string
 
-| xref:charconv.adoc#from_chars[`from_chars`]
+| xref:charconv.adoc[`from_chars`]
 | Parses a character string into a safe integer
 |===
 
+=== Arithmetic
+
+[cols="1,2", options="header"]
+|===
+| Function | Description
+
+| xref:policies.adoc[`saturating_add`, `saturating_sub`, `saturating_mul`, `saturating_div`, `saturating_mod`]
+| Saturating arithmetic (clamp to min/max on overflow)
+
+| xref:policies.adoc[`overflowing_add`, `overflowing_sub`, `overflowing_mul`, `overflowing_div`, `overflowing_mod`]
+| Overflowing arithmetic (wrap and return overflow flag)
+
+| xref:policies.adoc[`checked_add`, `checked_sub`, `checked_mul`, `checked_div`, `checked_mod`]
+| Checked arithmetic (return `std::nullopt` on overflow)
+
+| xref:policies.adoc[`wrapping_add`, `wrapping_sub`, `wrapping_mul`, `wrapping_div`, `wrapping_mod`]
+| Wrapping arithmetic (wrap silently)
+
+| xref:policies.adoc[`strict_add`, `strict_sub`, `strict_mul`, `strict_div`, `strict_mod`]
+| Strict arithmetic (call `std::exit(EXIT_FAILURE)` on error)
+
+| xref:policies.adoc[`add`, `sub`, `mul`, `div`, `mod`]
+| Generic policy-parameterized arithmetic (takes `overflow_policy` as template parameter)
+|===
+
 [#api_headers]
 == Headers
 
@@ -59,6 +94,9 @@ https://www.boost.org/LICENSE_1_0.txt
 | `<boost/safe_numbers/unsigned_integers.hpp>`
 | All unsigned safe integer types (`u8`, `u16`, `u32`, `u64`, `u128`)
 
+| `<boost/safe_numbers/overflow_policy.hpp>`
+| The `overflow_policy` enum class
+
 | `<boost/safe_numbers/charconv.hpp>`
 | Character conversion functions (`to_chars`, `from_chars`)
 

doc/modules/ROOT/pages/examples.adoc

@@ -150,6 +150,59 @@ Counter sequence: 254 255 0 1 2
 ----
 ====
 
+[#examples_strict]
+== Strict Arithmetic
+
+Strict arithmetic calls `std::exit(EXIT_FAILURE)` on overflow, underflow, or division by zero.
+This provides a hard termination policy for safety-critical applications where exceptions cannot be used but silent wrapping is unacceptable.
+All strict functions are `noexcept`.
+
+.This https://github.com/boostorg/safe_numbers/blob/develop/examples/strict_arithmetic.cpp[example] demonstrates strict arithmetic operations.
+====
+[source, c++]
+----
+include::example$strict_arithmetic.cpp[]
+----
+
+Output:
+----
+strict_add(100, 50) = 150
+strict_sub(100, 50) = 50
+strict_mul(100, 50) = 5000
+strict_div(100, 50) = 2
+strict_mod(100, 50) = 0
+strict_div(1000000, 3) = 333333
+strict_mod(1000000, 3) = 1
+----
+====
+
+[#examples_generic]
+== Generic Policy-Parameterized Arithmetic
+
+The generic `add`, `sub`, `mul`, `div`, and `mod` functions accept an `overflow_policy` as a template parameter, allowing you to write code that is generic over the overflow handling strategy.
+The return type varies by policy.
+
+.This https://github.com/boostorg/safe_numbers/blob/develop/examples/generic_arithmetic.cpp[example] demonstrates the generic policy-parameterized interface.
+====
+[source, c++]
+----
+include::example$generic_arithmetic.cpp[]
+----
+
+Output:
+----
+add<throw_exception>(100, 50) = 150
+add<saturate>(100, 50)        = 150
+add<wrapping>(100, 50)        = 150
+add<strict>(100, 50)          = 150
+add<overflow_tuple>(100, 50)   = 150 (overflowed: false)
+add<checked>(100, 50)          = 150
+add<checked>(max, 1)           = nullopt (overflow)
+add<saturate>(max, 1)          = 4294967295
+add<wrapping>(max, 1)          = 0
+----
+====
+
 [#examples_charconv]
 == Character Conversion
 
@@ -252,4 +305,14 @@ The following table summarizes the behavior of each arithmetic policy:
 |Wraps around (modulo 2^N)
 |`T`
 |Counters, checksums, hashing
+
+|Strict
+|Calls `std::exit(EXIT_FAILURE)`
+|`T`
+|Safety-critical, no-exceptions environments
+
+|Generic (`add<Policy>`)
+|Depends on policy
+|Depends on policy
+|Policy-generic algorithms
 |===