encapsulate programming by contract within this library, so that is not affected by and can not affect any outside code

Author: hurchalla

README.md

@@ -2,7 +2,7 @@
 
 ![Alt text](images/clockxtrasmall_border2.jpg?raw=true "Clock Gears, photo by Krzysztof Golik, licensed CC BY-SA 4.0")
 
-Clockwork is a high performance, easy to use Modular Arithmetic library for C++ provided as a "header-only" library, supporting up to 128 bit integer types, and providing extensive support for Montgomery arithmetic.  If you want or need Montgomery arithmetic in this range, or general modular arithmetic functions, Clockwork is almost certainly the fastest and easiest library you could use.  For best performance make sure you define the standard C++ macro NDEBUG.  
+Clockwork is a high performance, easy to use Modular Arithmetic library for C++ provided as a "header-only" library, supporting up to 128 bit integer types, and providing extensive support for Montgomery arithmetic.  If you want or need Montgomery arithmetic in this range, or general modular arithmetic functions, Clockwork is almost certainly the fastest and easiest library you could use.  
 
 The library requires only C++11, and works with all higher versions of the C++ standard.
 
@@ -12,9 +12,7 @@ Clockwork is designed to be a flexible and bulletproof library with the best per
 
 ## Requirements
 
-The Clockwork library requires only compiler support for C++11, which is essentially supported universally at this point.
-
-For good performance you *must* ensure that the standard macro NDEBUG (see <cassert>) is defined when compiling.  
+The Clockwork library requires only compiler support for C++11, which is essentially supported universally at this point.  
 
 Compilers that are confirmed to build this library without warnings or errors on Ubuntu linux (x64) include clang6, clang10, clang18, gcc7, gcc10, gcc13, and intel compiler 19.  On Windows, Microsoft Visual C++ 2017, 2019, 2022 are all confirmed to build the library without warnings or errors.  On MacOS, clang16 and gcc14 are confirmed to build without warnings or errors.  The library is intended for use on all architectures (e.g. x86/64, ARM, RISC-V), but has so far been tested only with x86, x64 (Windows and Ubuntu), and ARM64 (MacOS).
 
@@ -40,8 +38,6 @@ If you're using CMake for your project and you wish to add the Clockwork modular
 add_subdirectory(*path_of_the_cloned_modular_arithmetic_repository*   *your_binary_dir*/modular_arithmetic)  
 target_link_libraries(*your_project_target_name*   hurchalla_modular_arithmetic)  
 
-For best performance you *must* ensure that the standard macro NDEBUG (see <cassert>) is defined when compiling.  You can do this by calling CMake with -DCMAKE_BUILD_TYPE=Release.  
-
 It may help to see a simple [example project with CMake](examples/example_with_cmake).
 
 ### Without CMake
@@ -58,8 +54,6 @@ If you prefer, for the last command you could instead use CMake's default instal
 This will copy all the files needed for this modular arithmetic library to an "include" subfolder in the installation folder of your choosing.
 When compiling your project, you'll of course need to ensure that you have that include subfolder as part of your include path.  
 
-For best performance you *must* ensure that the standard macro NDEBUG (see <cassert>) is defined when compiling.  You can generally do this by adding the option flag -DNDEBUG to your compile command.  
-
 It may help to see a simple [example](examples/example_without_cmake).
 
 ## The API

build_tests.sh

@@ -567,7 +567,8 @@ elif [ "${mode,,}" = "debug" ]; then
             -DFORCE_TEST_HURCHALLA_CPP11_STANDARD=$force_cpp11_testing \
             -DCMAKE_BUILD_TYPE=Debug \
             -DCMAKE_EXE_LINKER_FLAGS="$clang_ubsan_link_flags" \
-            -DCMAKE_CXX_FLAGS="$cpp_standard  $cpp_stdlib \
+            -DCMAKE_CXX_FLAGS="-DHURCHALLA_CLOCKWORK_ENABLE_ASSERTS=1 \
+            $cpp_standard  $cpp_stdlib \
             $clang_ubsan  $gcc_ubsan  \
             $test_avoid_cselect  $test_heavyweight \
             $use_inline_asm  $use_all_inline_asm \

examples/example_with_cmake/example.cpp

@@ -1,4 +1,4 @@
-// Copyright (c) 2020-2022 Jeffrey Hurchalla.
+// Copyright (c) 2020-2025 Jeffrey Hurchalla.
 /*
  * This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -15,40 +15,37 @@
 #include <cassert>
 #include <cstdint>
 
-#ifndef NDEBUG
-// remove this if you want to allow asserts
-// (they're very good for testing and debugging but may drastically slow down
-// the library).
-#error "Performance warning: asserts are enabled and will slow performance"
-#endif
 
 int main()
 {
    namespace hc = ::hurchalla;
-   int64_t modulus = 333333333;
-   int64_t base = 42;
-   int64_t exponent = 123456789;
+
+   // you could use any integer type that the compiler supports
+   // (including __uint128_t)
+   using T = uint64_t;
+
+   T modulus = 333333333;
+   T base = 42;
+   T exponent = 123456789;
 
    // ---- Demonstration of modular exponentiation ----
 
    // Montgomery arithmetic version:
    assert(modulus % 2 == 1);  // montgomery arithmetic always needs odd modulus.
-      // first construct a MontgomeryForm object to do Montgomery arithmetic
-      // with a particular modulus.
-   hc::MontgomeryForm<int64_t> mf(modulus);
-      // convert base to its Montgomery representation.
-   auto base_montval = mf.convertIn(base);
-      // get the pow result in Montgomery representation.
-   auto result_montval = mf.pow(base_montval, exponent);
-      // convert the Montgomery representation result to normal integer domain.
-   int64_t result1 = mf.convertOut(result_montval);
+      // First construct a MontgomeryForm object to do Montgomery arithmetic
+      // with the modulus we chose.
+   hc::MontgomeryForm<T> mf(modulus);
+      // Convert base to its Montgomery representation.
+   auto mont_base = mf.convertIn(base);
+      // Get the pow result in Montgomery representation.
+   auto mont_result = mf.pow(mont_base, exponent);
+      // Convert the Montgomery representation result to normal integer domain.
+   T result1 = mf.convertOut(mont_result);
 
 
    // Standard arithmetic version:  (note that Montgomery arithmetic is
-   // typically faster, and that modular_pow() requires an unsigned type)
-   uint64_t result2 = hc::modular_pow(static_cast<uint64_t>(base),
-                                      static_cast<uint64_t>(exponent),
-                                      static_cast<uint64_t>(modulus));
+   // usually much faster)
+   T result2 = hc::modular_pow(base, exponent, modulus);
 
 
    std::cout << "Example results for " << base << "^" << exponent

examples/example_with_cmake/example.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-# Copyright (c) 2020-2022 Jeffrey Hurchalla.
+# Copyright (c) 2020-2025 Jeffrey Hurchalla.
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at https://mozilla.org/MPL/2.0/.
@@ -10,10 +10,6 @@
 # a CMake project.  If you haven't already done so, you should follow the steps
 # in the README.md for "How to use the library" | "With CMake"
 
-# Note that using CMake with -DCMAKE_BUILD_TYPE=Release will ensure that the
-# standard macro NDEBUG (see <cassert>) is defined, which is essential for best
-# performance.
-
 mkdir -p tmp
 cmake -S. -B./tmp -DCMAKE_BUILD_TYPE=Release
 cmake --build ./tmp --config Release

examples/example_without_cmake/example.cpp

@@ -1,4 +1,4 @@
-// Copyright (c) 2020-2022 Jeffrey Hurchalla.
+// Copyright (c) 2020-2025 Jeffrey Hurchalla.
 /*
  * This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -15,40 +15,37 @@
 #include <cassert>
 #include <cstdint>
 
-#ifndef NDEBUG
-// remove this if you want to allow asserts
-// (they're very good for testing and debugging but may drastically slow down
-// the library).
-#error "Performance warning: asserts are enabled and will slow performance"
-#endif
 
 int main()
 {
    namespace hc = ::hurchalla;
-   int64_t modulus = 333333333;
-   int64_t base = 42;
-   int64_t exponent = 123456789;
+
+   // you could use any integer type that the compiler supports
+   // (including __uint128_t)
+   using T = uint64_t;
+
+   T modulus = 333333333;
+   T base = 42;
+   T exponent = 123456789;
 
    // ---- Demonstration of modular exponentiation ----
 
    // Montgomery arithmetic version:
    assert(modulus % 2 == 1);  // montgomery arithmetic always needs odd modulus.
-      // first construct a MontgomeryForm object to do Montgomery arithmetic
-      // with a particular modulus.
-   hc::MontgomeryForm<int64_t> mf(modulus);
-      // convert base to its Montgomery representation.
-   auto base_montval = mf.convertIn(base);
-      // get the pow result in Montgomery representation.
-   auto result_montval = mf.pow(base_montval, exponent);
-      // convert the Montgomery representation result to normal integer domain.
-   int64_t result1 = mf.convertOut(result_montval);
+      // First construct a MontgomeryForm object to do Montgomery arithmetic
+      // with the modulus we chose.
+   hc::MontgomeryForm<T> mf(modulus);
+      // Convert base to its Montgomery representation.
+   auto mont_base = mf.convertIn(base);
+      // Get the pow result in Montgomery representation.
+   auto mont_result = mf.pow(mont_base, exponent);
+      // Convert the Montgomery representation result to normal integer domain.
+   T result1 = mf.convertOut(mont_result);
 
 
    // Standard arithmetic version:  (note that Montgomery arithmetic is
-   // typically faster, and that modular_pow() requires an unsigned type)
-   uint64_t result2 = hc::modular_pow(static_cast<uint64_t>(base),
-                                      static_cast<uint64_t>(exponent),
-                                      static_cast<uint64_t>(modulus));
+   // usually much faster)
+   T result2 = hc::modular_pow(base, exponent, modulus);
 
 
    std::cout << "Example results for " << base << "^" << exponent

examples/example_without_cmake/example.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-# Copyright (c) 2020-2022 Jeffrey Hurchalla.
+# Copyright (c) 2020-2025 Jeffrey Hurchalla.
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at https://mozilla.org/MPL/2.0/.
@@ -27,8 +27,7 @@ cpp_compiler=g++
 
 
 $cpp_compiler -std="c++17" \
-        -Wall -Wextra  \
-        -O2  -DNDEBUG  \
+        -Wall -Wextra  -O2  \
         -I$include_path \
         -o example  example.cpp
 

modular_arithmetic/CMakeLists.txt

@@ -46,6 +46,7 @@ target_sources(hurchalla_basic_modular_arithmetic INTERFACE
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/hurchalla/modular_arithmetic/modular_multiplicative_inverse.h>
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/hurchalla/modular_arithmetic/modular_pow.h>
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/hurchalla/modular_arithmetic/modular_subtraction.h>
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/hurchalla/modular_arithmetic/detail/clockwork_programming_by_contract.h>
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/hurchalla/modular_arithmetic/detail/impl_modular_multiplicative_inverse.h>
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/hurchalla/modular_arithmetic/detail/impl_modular_pow.h>
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/hurchalla/modular_arithmetic/detail/optimization_tag_structs.h>

modular_arithmetic/include/hurchalla/modular_arithmetic/absolute_value_difference.h

@@ -12,7 +12,7 @@
 #include "hurchalla/modular_arithmetic/detail/platform_specific/impl_absolute_value_difference.h"
 #include "hurchalla/util/traits/ut_numeric_limits.h"
 #include "hurchalla/util/compiler_macros.h"
-#include "hurchalla/util/programming_by_contract.h"
+#include "hurchalla/modular_arithmetic/detail/clockwork_programming_by_contract.h"
 
 namespace hurchalla {
 
@@ -24,13 +24,13 @@ template <typename T>  HURCHALLA_FORCE_INLINE
 T absolute_value_difference(T a, T b)
 {
     static_assert(ut_numeric_limits<T>::is_integer, "");
-    HPBC_PRECONDITION(a >= 0);
-    HPBC_PRECONDITION(b >= 0);
+    HPBC_CLOCKWORK_PRECONDITION(a >= 0);
+    HPBC_CLOCKWORK_PRECONDITION(b >= 0);
 
     T result = detail::impl_absolute_value_difference<T>::call(a, b);
 
-    HPBC_POSTCONDITION(result >= 0);
-    HPBC_POSTCONDITION(result == ((a>b) ? a-b : b-a));
+    HPBC_CLOCKWORK_POSTCONDITION(result >= 0);
+    HPBC_CLOCKWORK_POSTCONDITION(result == ((a>b) ? a-b : b-a));
     return result;
 }