Merge pull request #95 from saxbophone/josh/math-support

Move pow to math support library and added ilog

Author: saxbophone

Doxyfile

@@ -1471,7 +1471,7 @@ FORMULA_TRANSPARENT    = YES
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-USE_MATHJAX            = NO
+USE_MATHJAX            = YES
 
 # When MathJax is enabled you can set the default output format to be used for
 # the MathJax output. See the MathJax site (see:

arby/include/arby/Nat.hpp

@@ -1,6 +1,7 @@
 /**
  * @file
- * @brief This file forms part of arby
+ * @brief Nat class supporting arbitrary-size unsigned (Natural) integers
+ * @note This file forms part of arby
  * @details arby is a C++ library providing arbitrary-precision integer types
  * @warning arby is alpha-quality software
  *
@@ -123,7 +124,8 @@ namespace com::saxbophone::arby {
 
     /**
      * @brief Arbitrary-precision unsigned integer type
-     * @details This is named after 𝐍, the set of Natural numbers, which this type models
+     * @details This is named after \f$\mathbb{N}\f$, the set of Natural numbers,
+     * which this type models
      * @note `std::numeric_limits<Nat>` is specialised such that most of the
      * members of that type are implemented to describe the traits of this type.
      * @note Exceptions include any members of std::numeric_limits<> which
@@ -598,38 +600,6 @@ namespace com::saxbophone::arby {
             std::tie(std::ignore, remainder) = Nat::divmod(lhs, rhs);
             return remainder;
         }
-        /**
-         * @returns base raised to the power of exponent
-         * @param base,exponent parameters for the base and exponent
-         * @todo This currently uses a divide-and-conquer approach that divides
-         * exponent by 2 each time, for a binary-recursion on the order of
-         * \f$\mathcal{O}(n\log{}n)\f$. This is fine, but it would be nice to
-         * see if we can make incremental improvements to the optimisation by
-         * using factors, logarithms or something else to divide the exponent
-         * into more than 2 chunks at each level of recursion.
-         */
-        static constexpr Nat pow(const Nat& base, const Nat& exponent) {
-            // use divide-and-conquer recursion to break up huge powers into products of smaller powers
-            // exponent = 0 is our base case to terminate the recursion
-            if (exponent == 0) {
-                return 1;
-            } else if (exponent == 1) {
-                // exponent = 1 is an additional base case mainly to prevent a redundant level of recursion to 0
-                return base;
-            } else if (exponent == 2) {
-                // exponent = 2 is our final base case, as it seems a waste to leave it to the catch-all case below
-                return base * base;
-            }
-            auto [quotient, remainder] = Nat::divmod(exponent, 2);
-            // instead of calculating x^n, do x^(n/2)
-            Nat power = Nat::pow(base, quotient);
-            power *= power;
-            // and multiply by base again if n was odd
-            if (remainder == 1) {
-                power *= base;
-            }
-            return power;
-        }
         // XXX: unimplemented shift operators commented out until implemented
         // // left-shift-assignment
         // constexpr Nat& operator<<=(const Nat& n) {

arby/include/arby/math.hpp

@@ -0,0 +1,90 @@
+/**
+ * @file
+ * @brief cmath-like math support functions
+ * @note This file forms part of arby
+ * @details arby is a C++ library providing arbitrary-precision integer types
+ * @warning arby is alpha-quality software
+ *
+ * @author Joshua Saxby <[email protected]>
+ * @date May 2022
+ *
+ * @copyright Copyright Joshua Saxby <[email protected]> 2022
+ *
+ * @copyright
+ * 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 http://mozilla.org/MPL/2.0/.
+ */
+
+#ifndef COM_SAXBOPHONE_ARBY_MATH_HPP
+#define COM_SAXBOPHONE_ARBY_MATH_HPP
+
+#include <stdexcept>
+#include <utility>
+
+#include <arby/Nat.hpp>
+
+
+namespace com::saxbophone::arby {
+    /**
+     * @returns base raised to the power of exponent
+     * @param base,exponent parameters for the base and exponent
+     * @todo This currently uses a divide-and-conquer approach that divides
+     * exponent by 2 each time, for a binary-recursion on the order of
+     * \f$\mathcal{O}(n\log{}n)\f$. This is fine, but it would be nice to
+     * see if we can make incremental improvements to the optimisation by
+     * using factors, logarithms or something else to divide the exponent
+     * into more than 2 chunks at each level of recursion.
+     * @relatedalso Nat
+     */
+    constexpr Nat pow(const Nat& base, const Nat& exponent) {
+        // use divide-and-conquer recursion to break up huge powers into products of smaller powers
+        // exponent = 0 is our base case to terminate the recursion
+        if (exponent == 0) {
+            return 1;
+        } else if (exponent == 1) {
+            // exponent = 1 is an additional base case mainly to prevent a redundant level of recursion to 0
+            return base;
+        } else if (exponent == 2) {
+            // exponent = 2 is our final base case, as it seems a waste to leave it to the catch-all case below
+            return base * base;
+        }
+        auto [quotient, remainder] = Nat::divmod(exponent, 2);
+        // instead of calculating x^n, do x^(n/2)
+        Nat power = pow(base, quotient);
+        power *= power;
+        // and multiply by base again if n was odd
+        if (remainder == 1) {
+            power *= base;
+        }
+        return power;
+    }
+    /**
+     * @brief Calculates integer log of `x` in `base`
+     * @returns pair of \f$floor(log_b(x)),\ ceil(log_b(x))\f$ for the given
+     * base \f$b\f$ and \f$x\f$
+     * @param base base to use for \f$b\f$
+     * @param x value to use for \f$x\f$
+     * @throws std::domain_error when \f$b<2\f$
+     * @throws std::domain_error when \f$x<1\f$
+     */
+    constexpr std::pair<Nat, Nat> ilog(const Nat& base, const Nat& x) {
+        if (base < 2) {
+            throw std::domain_error("ilog: base cannot be < 2");
+        } else if (x < 1) {
+            throw std::domain_error("ilog: x cannot be < 1");
+        }
+        // find the smallest power of base that is just >= than x
+        Nat power = 1;
+        Nat floor = 0;
+        Nat exponent = 0;
+        while (power < x) {
+            power *= base;
+            floor = exponent++; // increment and store old value in floor
+        }
+        // floor = ceil when power = x
+        return {power == x ? exponent : floor, exponent};
+    }
+}
+
+#endif // include guard

tests/CMakeLists.txt

@@ -5,34 +5,40 @@ CPMFindPackage(
     EXCLUDE_FROM_ALL YES
 )
 
+# common option-propagating target to use for test suite sub-targets
+add_library(tests-config INTERFACE)
+target_link_libraries(
+    tests-config
+    INTERFACE
+        arby-compiler-options  # tests use same compiler options as main project
+        arby
+        Catch2::Catch2  # unit testing framework
+)
+
+# every sub-part of the test suite
+add_subdirectory(math_support)
+add_subdirectory(Nat)
+
+# test executable wraps everything together
 add_executable(tests)
 target_sources(
     tests PRIVATE
         main.cpp
-        basic_arithmetic.cpp
-        casting.cpp
-        divmod.cpp
-        misc.cpp
-        multiplication.cpp
-        namespaces.cpp
-        pow.cpp
-        self_assignment.cpp
-        stringification.cpp
-        user_defined_literals.cpp
+        $<TARGET_OBJECTS:math-support>
+        $<TARGET_OBJECTS:Nat>
 )
 target_link_libraries(
-    tests
-    PRIVATE
+    tests PRIVATE
         arby-compiler-options  # tests use same compiler options as main project
         arby
         Catch2::Catch2  # unit testing framework
 )
-target_precompile_headers(tests PRIVATE <arby/Nat.hpp>)
 
 enable_testing()
 
 # auto-discover and add Catch2 tests from unit tests program
 include(CTest)
 include(Catch)
 
+# TODO: we might consider having one separate test executable per part, but not for now
 catch_discover_tests(tests WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")

tests/Nat/CMakeLists.txt

@@ -0,0 +1,14 @@
+add_library(
+    Nat OBJECT
+        basic_arithmetic.cpp
+        casting.cpp
+        divmod.cpp
+        misc.cpp
+        multiplication.cpp
+        namespaces.cpp
+        self_assignment.cpp
+        stringification.cpp
+        user_defined_literals.cpp
+)
+target_link_libraries(Nat PRIVATE tests-config)
+target_precompile_headers(Nat PRIVATE <arby/Nat.hpp>)