Merge pull request #60 from cppalliance/54

Add is power of 10 helper function

Author: mborland

doc/modules/ROOT/pages/api_reference.adoc

@@ -168,6 +168,9 @@ https://www.boost.org/LICENSE_1_0.txt
 
 | xref:integer_utilities.adoc[`remove_trailing_zeros`]
 | Branchlessly removes trailing decimal zeros from a safe unsigned integer
+
+| xref:integer_utilities.adoc[`is_power_10`]
+| Tests whether a safe unsigned integer is an exact power of 10
 |===
 
 === Arithmetic

doc/modules/ROOT/pages/design.adoc

@@ -26,7 +26,7 @@ Bugs like these are subtle, difficult to catch in code review, and can have seve
 
 Existing tools help but leave gaps.
 Compiler flags like `-Wsign-conversion` and `-Wconversion` catch many issues at compile time, and UBSan catches undefined behavior at runtime.
-But UBSan explicitly allows unsigned integer rollover because the standard defines it as well-defined behavior -- even though silent rollover is the source of countless bugs.
+But UBSan explicitly allows unsigned integer rollover because the standard defines it as well-defined behavior, even though silent rollover is the source of countless bugs.
 Boost.SafeNumbers aims to go further: by default, unsigned rollover is an error.
 
 == Core Design Principles
@@ -42,15 +42,15 @@ The cost is slightly more verbose code at type boundaries; the benefit is that e
 
 === Fail Early, Fail Loudly
 
-When an operation would produce an incorrect result -- overflow, underflow, division by zero -- the library makes this visible rather than silently continuing with a wrong value.
+When an operation produces an incorrect result, (e.g., overflow, underflow, division by zero) the library makes this visible rather than silently continuing with a wrong value.
 
 At compile time, errors become compiler errors.
 At runtime, errors throw exceptions by default.
 There is no mode where an error is silently ignored unless the programmer explicitly opts into wrapping behavior.
 
 === Type Safety as a First-Class Concern
 
-The safe types (`u8`, `u16`, `u32`, `u64`, `u128`) are concrete, named types -- not template wrappers around a policy.
+The safe types (`u8`, `u16`, `u32`, `u64`, `u128`) are concrete, named types, not template wrappers around a policy.
 This makes them easy to read, easy to teach, and easy to use as drop-in replacements for builtin types.
 
 Overflow policies are expressed through named free functions (`saturating_add`, `wrapping_add`, etc.) rather than through type-level policy parameters.
@@ -101,7 +101,7 @@ Different domains require different responses to overflow:
 - General application code benefits from *exceptions*: the error is reported and can be handled.
 - Some code needs to *detect and branch*: check whether overflow occurred without changing control flow.
 
-The library's default -- `throw_exception` -- is the safest general-purpose choice because it makes errors impossible to ignore.
+The library's default, `throw_exception`, is the safest general-purpose choice because it makes errors impossible to ignore.
 For other needs, named free functions make the policy explicit at each call site:
 
 [source,c++]
@@ -135,24 +135,24 @@ See xref:policies.adoc[] for the full API reference.
 
 The library intentionally prohibits several operations that are legal in pass:[C++] but are common sources of bugs:
 
-**Construction from `bool`** -- Prevents conflation of boolean logic and integer arithmetic.
+**Construction from `bool`**: Prevents conflation of boolean logic and integer arithmetic.
 In pass:[C++], `true + true == 2`, which is rarely the intended behavior.
 Constructing a safe integer from `bool` is a compile-time error.
 
-**Mixed-width arithmetic** -- Adding a `u8` to a `u32` is a compile-time error.
+**Mixed-width arithmetic**: Adding a `u8` to a `u32` is a compile-time error.
 In pass:[C++], the narrower operand would be implicitly promoted, which hides the fact that two different-sized values are being combined.
 The library requires an explicit conversion so the programmer acknowledges the width difference.
 
-**Unary minus on unsigned types** -- In pass:[C++], `-x` on an unsigned value performs modular negation, producing a large positive number.
+**Unary minus on unsigned types**: In pass:[C++], `-x` on an unsigned value performs modular negation, producing a large positive number.
 This is almost never intentional.
-The library does not define unary minus for unsigned types, so attempting it is a compile-time error.
+The library will provide a `static_assert` message should this operation be attempted.
 
-**Implicit conversions to and from builtin types** -- All conversions between safe types and builtin types require an explicit cast.
+**Implicit conversions to and from builtin types**: All conversions between safe types and builtin types require an explicit cast.
 This prevents accidental loss of safety guarantees when passing values across API boundaries.
 
 == Performance Considerations
 
-The library uses compiler intrinsics for overflow detection: `__builtin_add_overflow`, `__builtin_sub_overflow`, and `__builtin_mul_overflow` on GCC and Clang, and platform-specific intrinsics (`_addcarry_u64`, `_subborrow_u64`, `_umul128`) on MSVC.
+The library uses compiler intrinsics for overflow detection: `pass:[__builtin_add_overflow]`, `pass:[__builtin_sub_overflow]`, and `pass:[__builtin_mul_overflow]` on GCC and Clang, and platform-specific intrinsics (`_addcarry_u64`, `_subborrow_u64`, `_umul128`) on MSVC.
 These compile to efficient hardware instructions (typically a single arithmetic instruction followed by a conditional branch on the carry or overflow flag).
 
 The target is a runtime penalty of less than 2x compared to builtin types.

doc/modules/ROOT/pages/integer_utilities.adoc

@@ -188,3 +188,60 @@ using namespace boost::safe_numbers;
 constexpr auto r = remove_trailing_zeros(verified_u32{u32{5000}});
 // r.trimmed_number == 5, r.number_of_removed_zeros == 3
 ----
+
+== is_power_10
+
+Tests whether an unsigned integer value is an exact power of 10 (i.e., one of 1, 10, 100, 1000, ...).
+
+Implemented using `remove_trailing_zeros` and checking that the trimmed result equals 1.
+
+=== Runtime Overload
+
+[source,c++]
+----
+template <non_bounded_unsigned_library_type T>
+    requires (!is_verified_type_v<T>)
+constexpr auto is_power_10(const T n) -> bool;
+----
+
+==== Parameters
+
+* `n` -- The value to test. Must be non-zero.
+
+==== Return Value
+
+`true` if `n` is a power of 10, `false` otherwise.
+
+==== Example
+
+[source,c++]
+----
+using namespace boost::safe_numbers;
+
+is_power_10(u32{1000});      // true
+is_power_10(u32{1});         // true
+is_power_10(u32{1234});      // false
+is_power_10(u64{10000000000000000000ULL});  // true
+----
+
+=== Verified Overload
+
+[source,c++]
+----
+template <non_bounded_unsigned_library_type T>
+consteval auto is_power_10(const verified_type_basis<T> n) -> bool;
+----
+
+Compile-time only overload for verified types.
+
+Since `is_power_10` is `consteval` for verified types, the result is guaranteed to be a compile-time constant and can be used directly in `static_assert`.
+
+==== Example
+
+[source,c++]
+----
+using namespace boost::safe_numbers;
+
+static_assert(is_power_10(verified_u32{u32{100}}));
+static_assert(!is_power_10(verified_u32{u32{200}}));
+----

include/boost/safe_numbers/detail/int128/detail/int128_imp.hpp

@@ -25,10 +25,8 @@ namespace boost {
 namespace int128 {
 
 struct
-    #if defined(BOOST_SAFE_NUMBERS_DETAIL_INT128_HAS_INT128) || defined(BOOST_SAFE_NUMBERS_DETAIL_INT128_HAS_MSVC_INT128)
+    #if (defined(BOOST_SAFE_NUMBERS_DETAIL_INT128_HAS_INT128) || defined(BOOST_SAFE_NUMBERS_DETAIL_INT128_HAS_MSVC_INT128)) && !defined(_M_IX86)
     alignas(alignof(detail::builtin_i128))
-    #else
-    alignas(16)
     #endif
 int128_t
 {

include/boost/safe_numbers/detail/int128/detail/uint128_imp.hpp

@@ -26,10 +26,8 @@ namespace boost {
 namespace int128 {
 
 struct
-    #if defined(BOOST_SAFE_NUMBERS_DETAIL_INT128_HAS_INT128) || defined(BOOST_SAFE_NUMBERS_DETAIL_INT128_HAS_MSVC_INT128)
+    #if (defined(BOOST_SAFE_NUMBERS_DETAIL_INT128_HAS_INT128) || defined(BOOST_SAFE_NUMBERS_DETAIL_INT128_HAS_MSVC_INT128)) && !defined(_M_IX86)
     alignas(alignof(detail::builtin_u128))
-    #else
-    alignas(16)
     #endif
 uint128_t
 {

include/boost/safe_numbers/integer_utilities.hpp

@@ -61,6 +61,25 @@ consteval auto remove_trailing_zeros(const detail::verified_type_basis<T> val)
     return detail::remove_trailing_zeros(static_cast<underlying>(val));
 }
 
+template <detail::non_bounded_unsigned_library_type T>
+    requires (!detail::is_verified_type_v<T>)
+constexpr auto is_power_10(const T n) -> bool
+{
+    using underlying = typename detail::underlying_type_t<T>;
+
+    const auto [trimmed_number, _] = detail::remove_trailing_zeros(static_cast<underlying>(n));
+    return trimmed_number == static_cast<underlying>(1);
+}
+
+template <detail::non_bounded_unsigned_library_type T>
+consteval auto is_power_10(const detail::verified_type_basis<T> n) -> bool
+{
+    using underlying = typename detail::underlying_type_t<T>;
+
+    const auto [trimmed_number, _] = detail::remove_trailing_zeros(static_cast<underlying>(n));
+    return trimmed_number == static_cast<underlying>(1);
+}
+
 } // namespace boost::safe_numbers
 
 #endif // BOOST_SAFE_NUMBERS_INTEGER_UTILITIES_HPP

test/Jamfile

@@ -132,6 +132,7 @@ run test_verified_limits.cpp ;
 # Utility function tests
 run test_isqrt.cpp ;
 run test_remove_trailing_zeros.cpp ;
+run test_is_power_10.cpp ;
 
 # Compile Tests
 compile compile_tests/compile_test_unsigned_integers.cpp ;