Merge to Master for v3.0.0

.drone.jsonnet

@@ -1,8 +1,9 @@
 # Copyright 2022, 2023 Peter Dimov
+# Copyright 2025 - 2026 Matt Borland
 # Distributed under the Boost Software License, Version 1.0.
 # https://www.boost.org/LICENSE_1_0.txt
 
-local library = "decimal";
+local library = "int128";
 
 local triggers =
 {
@@ -23,9 +24,8 @@ local linux_pipeline(name, image, environment, packages = "", sources = [], arch
         os: "linux",
         arch: arch
     },
-    clone:
-    {
-        retries: 5,
+    "clone": {
+       "retries": 5
     },
     steps:
     [
@@ -37,7 +37,9 @@ local linux_pipeline(name, image, environment, packages = "", sources = [], arch
             commands:
             [
                 'set -e',
-                'wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add -',
+                'echo $DRONE_STAGE_MACHINE',
+                'uname -a',
+                'curl -sSL --retry 5 https://apt.llvm.org/llvm-snapshot.gpg.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/llvm-snapshot.gpg',
             ] +
             (if sources != [] then [ ('apt-add-repository "' + source + '"') for source in sources ] else []) +
             (if packages != "" then [ 'apt-get update', 'apt-get -y install ' + packages ] else []) +
@@ -267,6 +269,34 @@ local windows_pipeline(name, image, environment, arch = "amd64") =
         "g++-14-multilib",
     ),
 
+    linux_pipeline(
+        "Linux 26.04 GCC 15 32",
+        "cppalliance/droneubuntu2604:1",
+        { TOOLSET: 'gcc', COMPILER: 'g++-15', CXXSTD: '03,11,14,17,20,23', ADDRMD: '32', CXXFLAGS: "-fexcess-precision=fast" },
+        "g++-15-multilib",
+    ),
+
+    linux_pipeline(
+        "Linux 26.04 GCC 15 64",
+        "cppalliance/droneubuntu2604:1",
+        { TOOLSET: 'gcc', COMPILER: 'g++-15', CXXSTD: '03,11,14,17,20,23', ADDRMD: '64', CXXFLAGS: "-fexcess-precision=fast" },
+        "g++-15-multilib",
+    ),
+
+    linux_pipeline(
+        "Linux 26.04 GCC 16 32",
+        "cppalliance/droneubuntu2604:1",
+        { TOOLSET: 'gcc', COMPILER: 'g++-16', CXXSTD: '03,11,14,17,20,23', ADDRMD: '32', CXXFLAGS: "-fexcess-precision=fast" },
+        "g++-16-multilib",
+    ),
+
+    linux_pipeline(
+        "Linux 26.04 GCC 16 64",
+        "cppalliance/droneubuntu2604:1",
+        { TOOLSET: 'gcc', COMPILER: 'g++-16', CXXSTD: '03,11,14,17,20,23', ADDRMD: '64', CXXFLAGS: "-fexcess-precision=fast" },
+        "g++-16-multilib libabsl-dev",
+    ),
+
     linux_pipeline(
         "Linux 18.04 Clang 5.0",
         "cppalliance/droneubuntu1804:1",
@@ -386,17 +416,27 @@ local windows_pipeline(name, image, environment, arch = "amd64") =
     ),
 
     linux_pipeline(
-        "Linux 24.04 Clang 20 ASAN",
+        "Linux 24.04 Clang 21",
         "cppalliance/droneubuntu2404:1",
-        { TOOLSET: 'clang', COMPILER: 'clang++-20', CXXSTD: '03,11,14,17,20,23,2c' } + asan,
-        "clang-20",
-        ["deb http://apt.llvm.org/noble/ llvm-toolchain-noble-20 main"],
+        { TOOLSET: 'clang', COMPILER: 'clang++-21', CXXSTD: '17,20,2b' },
+        "clang-21",
+        ["deb http://apt.llvm.org/noble/ llvm-toolchain-noble-21 main"],
+    ),
+
+    linux_pipeline(
+        "Linux 24.04 Clang 21 UBSAN",
+        "cppalliance/droneubuntu2404:1",
+        { TOOLSET: 'clang', COMPILER: 'clang++-21', CXXSTD: '17,20,2b' } + ubsan,
+        "clang-21",
+        ["deb http://apt.llvm.org/noble/ llvm-toolchain-noble-21 main"],
     ),
 
-    macos_pipeline(
-        "MacOS Xcode 14.3.1",
-        { TOOLSET: 'clang', COMPILER: 'clang++', CXXSTD: '03,11,14,17,20,2b' } + asan,
-        xcode_version = "14.3.1", osx_version = "sonoma", arch = "arm64",
+    linux_pipeline(
+        "Linux 24.04 Clang 21 ASAN",
+        "cppalliance/droneubuntu2404:1",
+        { TOOLSET: 'clang', COMPILER: 'clang++-21', CXXSTD: '17,20,2b' } + asan,
+        "clang-21",
+        ["deb http://apt.llvm.org/noble/ llvm-toolchain-noble-21 main"],
     ),
 
     windows_pipeline(

doc/modules/ROOT/nav.adoc

@@ -7,6 +7,7 @@
 ** xref:examples.adoc#examples_bit[`<bit>` support]
 ** xref:examples.adoc#examples_numeric[`<numeric>` support (Saturating Arithmetic)]
 ** xref:examples.adoc#examples_numeric_algorithms[`<numeric>` support (Numeric Algorithms)]
+** xref:examples.adoc#examples_checked[Checked Arithmetic]
 ** xref:examples.adoc#examples_mixed_sign[Mixed Signedness Arithmetic]
 ** xref:examples.adoc#examples_to_string[String Conversion (to_string)]
 ** xref:examples.adoc#examples_boost_math_random[Boost Math and Random Integration]
@@ -23,10 +24,12 @@
 *** xref:api_reference.adoc#api_cstdlib[`<cstdlib>`]
 *** xref:api_reference.adoc#api_charconv[`<charconv>`]
 *** xref:api_reference.adoc#api_cmath[`<cmath>`]
+*** xref:api_reference.adoc#api_functional[`<functional>`]
 *** xref:api_reference.adoc#api_iostream[`<iostream>`]
 *** xref:api_reference.adoc#api_ios[`<ios>`]
 *** xref:api_reference.adoc#api_numeric[`<numeric>`]
 *** xref:api_reference.adoc#api_string[`<string>`]
+*** xref:api_reference.adoc#api_utilities[Utilities]
 ** xref:api_reference.adoc#api_macros[Macros]
 *** xref:api_reference.adoc#api_macro_literals[Literals]
 *** xref:api_reference.adoc#api_macro_configuration[Configuration]
@@ -53,8 +56,14 @@
 * xref:cstdlib.adoc[]
 * xref:charconv.adoc[]
 * xref:stream.adoc[]
+* xref:hash.adoc[]
 * xref:numeric.adoc[]
 * xref:string.adoc[]
+* xref:utilities.adoc[]
+** xref:utilities.adoc#powm[Modular Exponentiation]
+** xref:utilities.adoc#ipow[Integer Power]
+** xref:utilities.adoc#isqrt[Integer Square Root]
+** xref:utilities.adoc#checked[Checked Arithmetic]
 * Benchmarks
 ** xref:u128_benchmarks.adoc[]
 *** xref:u128_benchmarks.adoc#u128_linux[Linux]
@@ -64,5 +73,6 @@
 *** xref:i128_benchmarks.adoc#i128_linux[Linux]
 *** xref:i128_benchmarks.adoc#i128_windows[Windows]
 *** xref:i128_benchmarks.adoc#i128_mac[macOS]
+* xref:comp_to_multiprecision.adoc[]
 * xref:reference.adoc[]
 * xref:copyright.adoc[]

doc/modules/ROOT/pages/api_reference.adoc

@@ -72,6 +72,12 @@ https://www.boost.org/LICENSE_1_0.txt
 | https://en.cppreference.com/w/cpp/types/numeric_limits[`std::numeric_limits<int128_t>`]
 | Numeric limits specialization for `int128_t`
 
+| xref:hash.adoc[`std::hash<uint128_t>`]
+| Hash specialization for `uint128_t`
+
+| xref:hash.adoc[`std::hash<int128_t>`]
+| Hash specialization for `int128_t`
+
 | xref:cstdlib.adoc#div_structs[`u128div_t`]
 | Result type for `div(uint128_t, uint128_t)`
 
@@ -164,6 +170,20 @@ Listed by analogous STL header.
 | Computes quotient and remainder simultaneously
 |===
 
+[#api_functional]
+=== xref:hash.adoc[`<functional>`]
+
+[cols="1,2", options="header"]
+|===
+| Specialization | Description
+
+| xref:hash.adoc[`std::hash<uint128_t>`]
+| Enables `uint128_t` as a key in unordered associative containers
+
+| xref:hash.adoc[`std::hash<int128_t>`]
+| Enables `int128_t` as a key in unordered associative containers
+|===
+
 [#api_formatting]
 === xref:format.adoc[Formatting]
 
@@ -257,6 +277,32 @@ Listed by analogous STL header.
 | `std::string` conversion of base-10 values
 |===
 
+[#api_utilities]
+=== xref:utilities.adoc[Utilities]
+
+[cols="1,2", options="header"]
+|===
+| Function | Description
+
+| xref:utilities.adoc#powm[`powm`]
+| Modular exponentiation `(base ^ exp) mod m`
+
+| xref:utilities.adoc#ipow[`ipow`]
+| Integer power `base ^ exp` (wraps modulo `2^128`)
+
+| xref:utilities.adoc#isqrt[`isqrt`]
+| Integer square root `floor(sqrt(n))`
+
+| xref:utilities.adoc#checked[`ckd_add`]
+| Checked addition (C23 `<stdckdint.h>` contract)
+
+| xref:utilities.adoc#checked[`ckd_sub`]
+| Checked subtraction (C23 `<stdckdint.h>` contract)
+
+| xref:utilities.adoc#checked[`ckd_mul`]
+| Checked multiplication (C23 `<stdckdint.h>` contract)
+|===
+
 [#api_macros]
 == Macros
 
@@ -302,12 +348,6 @@ Listed by analogous STL header.
 | xref:config.adoc#no_int128[`BOOST_INT128_NO_BUILTIN_INT128`]
 | Disables use of compiler built-in `__int128`
 
-| xref:config.adoc#sign_compare[`BOOST_INT128_ALLOW_SIGN_COMPARE`]
-| Allows comparison between signed and unsigned types
-
-| xref:config.adoc#sign_conversion[`BOOST_INT128_ALLOW_SIGN_CONVERSION`]
-| Allows implicit sign conversion
-
 | xref:config.adoc#disable_exceptions[`BOOST_INT128_DISABLE_EXCEPTIONS`]
 | Disables exception throwing
 
@@ -362,6 +402,9 @@ Listed by analogous STL header.
 | xref:format.adoc#std_format[`<boost/int128/format.hpp>`]
 | Formatting integration for pass:[C++20] `<format>`
 
+| xref:hash.adoc[`<boost/int128/hash.hpp>`]
+| `std::hash` specializations for `int128_t` and `uint128_t`
+
 | `<boost/int128/int128.hpp>`
 | The xref:uint128_t.adoc[`uint128_t`] and xref:int128_t.adoc[`int128_t`] types
 
@@ -383,4 +426,7 @@ Listed by analogous STL header.
 | `<boost/int128/random.hpp>`
 | Required for usage of Boost.Random
 
+| xref:utilities.adoc[`<boost/int128/utilities.hpp>`]
+| Modular exponentiation and other library-specific utilities
+
 |===

doc/modules/ROOT/pages/comp_to_multiprecision.adoc

@@ -0,0 +1,19 @@
+////
+Copyright 2026 Matt Borland
+Distributed under the Boost Software License, Version 1.0.
+https://www.boost.org/LICENSE_1_0.txt
+////
+
+[#mp]
+= Comparison to Boost.Multiprecision
+
+An easy question to ask is why this is a separate library from Boost.Multiprecision.
+There are several reasons why:
+
+- The goal is for this library to be extremely lightweight.
+The module weight of this library will be 5, whereas https://pdimov.github.io/boostdep-report/develop/module-weights.html[Boost.Multiprecision is 25]
+- Fundamentally, the designs of the types are different.
+In Boost.Multiprecision, `int128` and `uint128` are incident to the arbitrary precision integer `cpp_int`, not a specifically designed type.
+In this library both `int128_t` and `uint128_t` are their own classes with individually implemented operators to maximize performance.
+- In Boost.Multiprecision all types are based on a high-level template `number` to allow interoperability with each other.
+Again, both `int128_t` and `uint128_t` are their own classes, and are designed to work with and act like the built-in integer types.

doc/modules/ROOT/pages/config.adoc

@@ -24,16 +24,6 @@ Allowed functions have `BOOST_INT128_HOST_DEVICE` as part of their function sign
 [#no_int128]
 - `BOOST_INT128_NO_BUILTIN_INT128`: The user may define this when they do not want the internal implementations to rely on builtin `pass:[__int128]` or `pass:[unsigned __int128]` types.
 
-[#sign_compare]
-- `BOOST_INT128_ALLOW_SIGN_COMPARE`: Allows comparisons between this library's types and built-in types of opposite signedness. Analogous to disabling GCC's `-Wsign-compare` warning.
-
-IMPORTANT: NOT DEFINED BY DEFAULT FOR CORRECTNESS
-
-[#sign_conversion]
-- `BOOST_INT128_ALLOW_SIGN_CONVERSION`: Allows arithmetic operations between this library's types and built-in types of opposite signedness. Analogous to disabling GCC's `-Wsign-conversion` warning. Implies `BOOST_INT128_ALLOW_SIGN_COMPARE`.
-
-IMPORTANT: NOT DEFINED BY DEFAULT FOR CORRECTNESS
-
 [#disable_exceptions]
 - `BOOST_INT128_DISABLE_EXCEPTIONS`: Allows exceptions to be disabled.
 This macro will automatically be defined in the presence of `-fno-exceptions` or similar MSVC flags.

doc/modules/ROOT/pages/examples.adoc

@@ -28,21 +28,36 @@ From builtin (42U): 42
 From parts (1, 0) = 2^64: 18446744073709551616
 From parts (max, max): 340282366920938463463374607431768211455
   Equals numeric_limits max? true
-From literal "36893488147419103232"_U128: 36893488147419103232
+From literal 12345_U128: 12345
 From BOOST_INT128_UINT128_C(max): 340282366920938463463374607431768211455
 From stringstream: 12345678901234567890123456789
 
 === int128_t Construction ===
 From builtin (-42): -42
 From parts (INT64_MIN, 0): -170141183460469231731687303715884105728
   Equals numeric_limits min? true
-From literal "-99999999999999999999"_i128: -99999999999999999999
-From literal "99999999999999999999"_I128: 99999999999999999999
+From literal -12345_i128: -12345
+From literal 12345_I128: 12345
+From BOOST_INT128_INT128_C(-99999999999999999999): -99999999999999999999
+From string literal: -99999999999999999999
 From BOOST_INT128_INT128_C(min): -170141183460469231731687303715884105728
 
 === Default and Copy Construction ===
 Default constructed: 0
-Copy constructed: 36893488147419103232
+Copy constructed: 340282366920938463463374607431768211455
+
+=== Floating-Point Construction ===
+uint128_t from 12345.9 (truncated): 12345
+int128_t from -12345.9 (truncated toward zero): -12345
+uint128_t from 2^100: 1267650600228229401496703205376
+
+=== Floating-Point Edge Cases ===
+uint128_t from NaN: 0
+int128_t from NaN: 0
+uint128_t from -1.0 (clamped to zero): 0
+uint128_t from +infinity (saturates to UINT128_MAX): 340282366920938463463374607431768211455
+int128_t from 1e40 (saturates to INT128_MAX): 170141183460469231731687303715884105727
+int128_t from -1e40 (saturates to INT128_MIN): -170141183460469231731687303715884105728
 ----
 ====
 
@@ -263,6 +278,38 @@ midpoint(-100, -50) = -75
 ----
 ====
 
+[#examples_checked]
+== Checked Arithmetic
+
+.This https://github.com/cppalliance/int128/blob/develop/examples/checked_arithmetic.cpp[example] demonstrates checked addition, subtraction, and multiplication following the C23 checked-integer contract
+====
+[source, c++]
+----
+include::example$checked_arithmetic.cpp[]
+----
+
+.Expected Output
+[listing]
+----
+=== Results That Fit ===
+ckd_add(20, 22): overflow=false, result=42
+
+=== Addition Overflow ===
+ckd_add(UINT128_MAX, 1): overflow=true, wrapped=0
+
+=== Subtraction Underflow ===
+ckd_sub(0, 1): overflow=true, wrapped=340282366920938463463374607431768211455
+
+=== Multiplication Overflow ===
+ckd_mul(INT128_MAX, 2): overflow=true, wrapped=-2
+ckd_mul(INT128_MIN, -1): overflow=true, wrapped=-170141183460469231731687303715884105728
+
+=== Mixed Types ===
+ckd_add<int64_t>(uint128_t{5}, int128_t{-3}): overflow=false, result=2
+ckd_mul<uint8_t>(20, 20): overflow=true, wrapped=144
+----
+====
+
 [#examples_mixed_sign]
 == Mixed Signedness Arithmetic
 

doc/modules/ROOT/pages/file_structure.adoc

@@ -39,6 +39,9 @@ The entire library can be consumed via `<boost/int128.hpp>`, or by independently
 | xref:format.adoc[`<boost/int128/format.hpp>`]
 | C++20 `std::format` support
 
+| xref:hash.adoc[`<boost/int128/hash.hpp>`]
+| `std::hash` specializations for `int128_t` and `uint128_t`
+
 | `<boost/int128/int128.hpp>`
 | Core type definitions (`uint128_t`, `int128_t`)