Add integer powers operation

doc/modules/ROOT/pages/api_reference.adoc

@@ -174,6 +174,9 @@ https://www.boost.org/LICENSE_1_0.txt
 
 | xref:integer_utilities.adoc[`is_power_2`]
 | Tests whether a safe unsigned integer is an exact power of 2
+
+| xref:integer_utilities.adoc[`ipow`]
+| Integer exponentiation by squaring
 |===
 
 === Arithmetic
@@ -225,7 +228,7 @@ This header is not included in the convenience header since it requires external
 | Contains specializations of `<format>` for library types
 
 | `<boost/safe_numbers/integer_utilities.hpp>`
-| Integer utility functions (`isqrt`, `remove_trailing_zeros`)
+| Integer utility functions (`isqrt`, `remove_trailing_zeros`, `is_power_10`, `is_power_2`, `ipow`)
 
 | `<boost/safe_numbers/iostream.hpp>`
 | Stream I/O operators (`operator<<`, `operator>>`) for library types

doc/modules/ROOT/pages/integer_utilities.adoc

@@ -244,6 +244,77 @@ static_assert(is_power_10(verified_u32{u32{100}}));
 static_assert(!is_power_10(verified_u32{u32{200}}));
 ----
 
+== ipow
+
+Integer exponentiation using the exponentiation-by-squaring algorithm.
+
+=== Runtime Overload
+
+[source,c++]
+----
+template <non_bounded_unsigned_library_type T>
+    requires (!is_verified_type_v<T>)
+constexpr auto ipow(const T a, const T b) noexcept -> T;
+----
+
+Computes `a` raised to the power `b` using exponentiation by squaring.
+
+The algorithm runs in O(log(b)) multiplications:
+
+* If `b == 0`, returns `T{1}`.
+* If `b` is odd, returns `a * ipow(a, b - 1)`.
+* If `b` is even, returns `ipow(a, b / 2)^2`.
+
+If the result overflows the type, the behavior follows the overflow policy of the safe integer type (by default, throwing `std::overflow_error`).
+
+==== Parameters
+
+* `a` -- The base value.
+* `b` -- The exponent value.
+
+==== Return Value
+
+`a` raised to the power `b`, as the same safe integer type `T`.
+
+==== Complexity
+
+O(log(b)) multiplications.
+
+==== Example
+
+[source,c++]
+----
+using namespace boost::safe_numbers;
+
+auto r1 = ipow(u32{2}, u32{10});     // r1 == u32{1024}
+auto r2 = ipow(u32{10}, u32{9});     // r2 == u32{1000000000}
+auto r3 = ipow(u64{3}, u64{30});     // r3 == u64{205891132094649}
+auto r4 = ipow(u32{5}, u32{0});      // r4 == u32{1}
+----
+
+=== Verified Overload
+
+[source,c++]
+----
+template <non_bounded_unsigned_library_type T>
+consteval auto ipow(const verified_type_basis<T> a, const verified_type_basis<T> b) -> verified_type_basis<T>;
+----
+
+Compile-time only overload for verified types.
+Returns a verified type, preserving the compile-time guarantee.
+
+Since `ipow` is `consteval` for verified types, the computation is guaranteed to occur at compile time. Overflow produces a compile error.
+
+==== Example
+
+[source,c++]
+----
+using namespace boost::safe_numbers;
+
+constexpr auto r = ipow(verified_u32{u32{2}}, verified_u32{u32{20}});  // r == verified_u32{u32{1048576}}
+constexpr auto s = ipow(verified_u64{u64{10}}, verified_u64{u64{18}}); // s == verified_u64{u64{1000000000000000000}}
+----
+
 == is_power_2
 
 Tests whether an unsigned integer value is an exact power of 2 (i.e., has exactly one bit set).

doc/modules/ROOT/pages/verified_integers.adoc

@@ -49,6 +49,7 @@ public:
     using underlying_type = underlying_type_t<BasisType>;
 
     // Construction (consteval -- compile-time only)
+    consteval verified_type_basis() = default;  // zero-initializes
     explicit consteval verified_type_basis(const BasisType basis);
     explicit consteval verified_type_basis(const underlying_type val);
 
@@ -105,12 +106,14 @@ consteval auto operator%(const verified_type_basis<BasisType> lhs,
 
 [source,c++]
 ----
+consteval verified_type_basis() = default;
 explicit consteval verified_type_basis(const BasisType basis);
 explicit consteval verified_type_basis(const underlying_type val);
 ----
 
 Construction is `consteval` -- it can only occur at compile time.
-The first overload accepts the safe integer basis type directly; the second accepts the underlying fundamental type and constructs the basis type internally.
+The default constructor zero-initializes the value, consistent with the behavior of the basis types.
+The second overload accepts the safe integer basis type directly; the third accepts the underlying fundamental type and constructs the basis type internally.
 If the value is out of range (e.g., for a bounded type), the compilation fails.
 
 === Conversion
@@ -197,7 +200,8 @@ consteval auto operator--(int) -> verified_type_basis;
 |===
 | Operation | Qualifier | Compile-Time | Runtime
 
-| Construction | `consteval` | Yes | No
+| Default construction | `consteval` | Yes | No
+| Explicit construction | `consteval` | Yes | No
 | Arithmetic (`+`, `-`, `*`, `/`, `%`) | `consteval` | Yes | No
 | Compound assignment (`+=`, `-=`, etc.) | `consteval` | Yes | No
 | Increment/decrement (`++`, `--`) | `consteval` | Yes | No

include/boost/safe_numbers/detail/verified_type_basis.hpp

@@ -37,6 +37,8 @@ class verified_type_basis
 
 public:
 
+    consteval verified_type_basis() = default;
+
     explicit consteval verified_type_basis(const BasisType basis) : basis_{basis} {}
 
     explicit consteval verified_type_basis(const underlying_type val) : verified_type_basis{BasisType{val}} {}

include/boost/safe_numbers/integer_utilities.hpp

@@ -106,6 +106,50 @@ consteval auto is_power_2(const detail::verified_type_basis<T> n) noexcept -> bo
     return has_single_bit(n);
 }
 
+namespace detail {
+
+// Iterative exponentiation by squaring: O(log b) multiplications
+template <non_bounded_unsigned_library_type T>
+constexpr auto ipow_impl(T base, T exp) -> T
+{
+    using underlying = underlying_type_t<T>;
+
+    auto result = T{static_cast<underlying>(1)};
+
+    while (exp != T{static_cast<underlying>(0)})
+    {
+        if (static_cast<underlying>(exp) & underlying{1})
+        {
+            result = result * base;
+        }
+        exp = exp / T{static_cast<underlying>(2)};
+        if (exp != T{static_cast<underlying>(0)})
+        {
+            base = base * base;
+        }
+    }
+
+    return result;
+}
+
+} // namespace detail
+
+template <detail::non_bounded_unsigned_library_type T>
+    requires (!detail::is_verified_type_v<T>)
+constexpr auto ipow(const T a, const T b) -> T
+{
+    return detail::ipow_impl(a, b);
+}
+
+template <detail::non_bounded_unsigned_library_type T>
+consteval auto ipow(const detail::verified_type_basis<T> a,
+                    const detail::verified_type_basis<T> b) -> detail::verified_type_basis<T>
+{
+    // This is a workaround for P2564R3 "Consteval should propagate up"
+    // Operate on the underlying type rather than on the verfied type directly
+    return detail::verified_type_basis<T>{detail::ipow_impl(static_cast<T>(a), static_cast<T>(b))};
+}
+
 } // namespace boost::safe_numbers
 
 #endif // BOOST_SAFE_NUMBERS_INTEGER_UTILITIES_HPP

test/Jamfile

@@ -134,6 +134,7 @@ run test_isqrt.cpp ;
 run test_remove_trailing_zeros.cpp ;
 run test_is_power_10.cpp ;
 run test_is_power_2.cpp ;
+run test_ipow.cpp ;
 
 # Compile Tests
 compile compile_tests/compile_test_unsigned_integers.cpp ;