Merge pull request #101 from saxbophone/josh/docs-update-v0.4

Docs update v0.4 + efficiency increases

Author: saxbophone

CMakeLists.txt

@@ -111,6 +111,8 @@ else() # GCC/Clang warning option
     enable_cxx_compiler_flag_if_supported("-Wextra")
     # enable sign conversion warnings
     enable_cxx_compiler_flag_if_supported("-Wsign-conversion")
+    # disable unknown-pragma warnings --we have pragmas for some compilers that aren't known by others
+    enable_cxx_compiler_flag_if_supported("-Wno-unknown-pragmas")
     # if tests are enabled, enable converting all warnings to errors too
     if (ENABLE_TESTS)
         enable_cxx_compiler_flag_if_supported("-Werror")

Doxyfile

@@ -1494,7 +1494,7 @@ MATHJAX_FORMAT         = HTML-CSS
 # The default value is: http://cdn.mathjax.org/mathjax/latest.
 # This tag requires that the tag USE_MATHJAX is set to YES.
 
-MATHJAX_RELPATH        = https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.1/es5/startup.js
+MATHJAX_RELPATH        = https://cdn.mathjax.org/mathjax/latest
 
 # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax
 # extension names that should be enabled during MathJax rendering. For example

README.md

@@ -94,9 +94,9 @@ using namespace com::saxbophone;
 int main() {
     // powers of 11
     for (unsigned int power = 0; power < 20; power++) {
-        std::cout << arby::Nat::pow(11, power) << std::endl;
+        std::cout << arby::pow(11, power) << std::endl;
     }
-    std::cout << arby::Nat::pow(2, 64) << std::endl;
+    std::cout << arby::pow(2, 64) << std::endl;
     // demo of custom literals
     using namespace com::saxbophone::arby::literals;
     arby::Nat foo = 1234567891011121314151617181920_nat * 77378921_nat;

arby/include/arby/Nat.hpp

@@ -156,12 +156,14 @@ namespace com::saxbophone::arby {
          * @brief Defaulted equality operator for Nat objects
          * @param rhs other Nat object to compare against
          * @returns `true` if objects are equal, otherwise `false`
+         * @note Worst-case complexity: @f$ \mathcal{O(n)} @f$
          */
         constexpr bool operator==(const Nat& rhs) const = default;
         /**
          * @brief three-way-comparison operator defines all relational operators
          * @param rhs other Nat object to compare against
          * @returns std::strong_ordering object for comparison
+         * @note Complexity: @f$ \mathcal{O(n)} @f$
          */
         constexpr auto operator<=>(const Nat& rhs) const {
             // use size to indicate ordering if they differ
@@ -297,6 +299,7 @@ namespace com::saxbophone::arby {
         /**
          * @brief custom ostream operator that allows class Nat to be printed
          * with std::cout and friends
+         * @note Complexity is @f$ \mathcal{O(terrible)} @f$
          */
         friend std::ostream& operator<<(std::ostream& os, const Nat& object);
         /**
@@ -306,6 +309,8 @@ namespace com::saxbophone::arby {
         /**
          * @brief prefix increment
          * @returns new value of Nat object after incrementing
+         * @note Best-case complexity: @f$ \mathcal{O(1)} @f$
+         * @note Worst-case complexity: @f$ \mathcal{O(n)} @f$
          */
         constexpr Nat& operator++() {
             // increment least significant digit then rollover remaining digits as needed
@@ -325,6 +330,8 @@ namespace com::saxbophone::arby {
         /**
          * @brief postfix increment
          * @returns old value of Nat object before incrementing
+         * @note Best-case complexity: @f$ \mathcal{O(1)} @f$
+         * @note Worst-case complexity: @f$ \mathcal{O(n)} @f$
          */
         constexpr Nat operator++(int) {
             Nat old = *this; // copy old value
@@ -335,10 +342,12 @@ namespace com::saxbophone::arby {
          * @brief prefix decrement
          * @returns new value of Nat object after decrementing
          * @throws std::underflow_error when value of Nat is `0`
+         * @note Best-case complexity: @f$ \mathcal{O(1)} @f$
+         * @note Worst-case complexity: @f$ \mathcal{O(n)} @f$
          */
         constexpr Nat& operator--() {
             // empty digits vector (means value is zero) is a special case
-            if (_digits.size() == 0) {
+            if (_digits.empty()) {
                 throw std::underflow_error("arithmetic underflow: can't decrement unsigned zero");
             } else {
                 // decrement least significant digit then borrow from remaining digits as needed
@@ -360,6 +369,8 @@ namespace com::saxbophone::arby {
          * @brief postfix decrement
          * @returns old value of Nat object before decrementing
          * @throws std::underflow_error when value of Nat is `0`
+         * @note Best-case complexity: @f$ \mathcal{O(1)} @f$
+         * @note Worst-case complexity: @f$ \mathcal{O(n)} @f$
          */
         constexpr Nat operator--(int) {
             Nat old = *this; // copy old value
@@ -371,10 +382,11 @@ namespace com::saxbophone::arby {
          * @details Adds other value to this Nat and assigns the result to self
          * @param rhs value to add to this Nat
          * @returns resulting object after addition-assignment
+         * @note Complexity: @f$ \mathcal{O(n)} @f$
          */
         constexpr Nat& operator+=(Nat rhs) {
-            // either arg being a zero is a no-op, guard against this
-            if (_digits.size() != 0 or rhs._digits.size() != 0) {
+            // both args being zero is a no-op, guard against this
+            if (not (_digits.empty() and rhs._digits.empty())) {
                 // make sure this and rhs are the same size, fill with leading zeroes if needed
                 if (rhs._digits.size() > _digits.size()) {
                     _digits.push_front(rhs._digits.size() - _digits.size(), 0);
@@ -404,6 +416,7 @@ namespace com::saxbophone::arby {
          * @brief Addition operator for Nat
          * @param lhs,rhs operands for the addition
          * @returns sum of lhs + rhs
+         * @note Complexity: @f$ \mathcal{O(n)} @f$
          */
         friend constexpr Nat operator+(Nat lhs, const Nat& rhs) {
             lhs += rhs; // reuse compound assignment
@@ -415,11 +428,12 @@ namespace com::saxbophone::arby {
          * @param rhs value to subtract from this Nat
          * @returns resulting object after subtraction-assignment
          * @throws std::underflow_error when rhs is bigger than this
+         * @note Complexity: @f$ \mathcal{O(n)} @f$
          */
         constexpr Nat& operator-=(Nat rhs) {
             // TODO: detect underflow early?
             // rhs being a zero is a no-op, guard against this
-            if (rhs._digits.size() != 0) {
+            if (not rhs._digits.empty()) {
                 // make sure this and rhs are the same size, fill with leading zeroes if needed
                 if (rhs._digits.size() > _digits.size()) {
                     _digits.push_front(rhs._digits.size() - _digits.size(), 0);
@@ -444,7 +458,7 @@ namespace com::saxbophone::arby {
                 }
             }
             // remove any leading zeroes
-            while (_digits.size() > 0 and _digits.front() == 0) {
+            while (not _digits.empty() and _digits.front() == 0) {
                 _digits.pop_front();
             }
             return *this; // return the result by reference
@@ -454,6 +468,7 @@ namespace com::saxbophone::arby {
          * @param lhs,rhs operands for the subtraction
          * @returns result of lhs - rhs
          * @throws std::underflow_error when rhs is bigger than lhs
+         * @note Complexity: @f$ \mathcal{O(n)} @f$
          */
         friend constexpr Nat operator-(Nat lhs, const Nat& rhs) {
             lhs -= rhs; // reuse compound assignment
@@ -464,6 +479,7 @@ namespace com::saxbophone::arby {
          * @details Multiplies this Nat by other value and assigns the result to self
          * @param rhs value to multiply this Nat by
          * @returns resulting object after multiplication-assignment
+         * @note Complexity: @f$ \mathcal{O(n^2)} @f$
          */
         constexpr Nat& operator*=(const Nat& rhs) {
             Nat product = *this * rhs; // uses friend *operator
@@ -475,12 +491,13 @@ namespace com::saxbophone::arby {
          * @brief Multiplication operator for Nat
          * @param lhs,rhs operands for the multiplication
          * @returns product of lhs * rhs
+         * @note Complexity: @f$ \mathcal{O(n^2)} @f$
          */
         friend constexpr Nat operator*(const Nat& lhs, const Nat& rhs) {
             // init product to zero
             Nat product;
             // either operand being zero always results in zero, so only run the algorithm if they're both non-zero
-            if (lhs._digits.size() != 0 and rhs._digits.size() != 0) {
+            if (not (lhs._digits.empty() or rhs._digits.empty())) {
                 // multiply each digit from lhs with each digit from rhs
                 std::size_t l = 0; // manual indices to track which digit we are on,
                 std::size_t r = 0; // as codlili's iterators are not random-access
@@ -547,10 +564,11 @@ namespace com::saxbophone::arby {
          * @param lhs,rhs operands for the division/modulo operation
          * @returns pair of {quotient, remainder}
          * @throws std::domain_error when rhs is zero
+         * @todo Work out time-complexity
          */
         static constexpr std::pair<Nat, Nat> divmod(const Nat& lhs, const Nat& rhs) {
             // division by zero is undefined
-            if (rhs._digits.size() == 0) {
+            if (rhs._digits.empty()) {
                 throw std::domain_error("division by zero");
             }
             // this will gradually accumulate the calculated quotient
@@ -588,6 +606,7 @@ namespace com::saxbophone::arby {
          * @param rhs value to divide this Nat by
          * @returns resulting object after division-assignment
          * @throws std::domain_error when rhs is zero
+         * @todo Work out time-complexity
          */
         constexpr Nat& operator/=(const Nat& rhs) {
             Nat quotient = *this / rhs; // uses friend /operator
@@ -600,6 +619,7 @@ namespace com::saxbophone::arby {
          * @note This implements floor-division, returning the quotient only
          * @param lhs,rhs operands for the division
          * @returns quotient of lhs / rhs
+         * @todo Work out time-complexity
          */
         friend constexpr Nat operator/(Nat lhs, const Nat& rhs) {
             Nat quotient;
@@ -613,6 +633,7 @@ namespace com::saxbophone::arby {
          * @param rhs value to modulo-divide this Nat by
          * @returns resulting object after modulo-assignment
          * @throws std::domain_error when rhs is zero
+         * @todo Work out time-complexity
          */
         constexpr Nat& operator%=(const Nat& rhs) {
             Nat remainder = *this % rhs; // uses friend %operator
@@ -626,6 +647,7 @@ namespace com::saxbophone::arby {
          * @param lhs,rhs operands for the division
          * @returns remainder of lhs / rhs
          * @throws std::domain_error when rhs is zero
+         * @todo Work out time-complexity
          */
         friend constexpr Nat operator%(Nat lhs, const Nat& rhs) {
             Nat remainder;
@@ -634,6 +656,7 @@ namespace com::saxbophone::arby {
         }
         /**
          * @brief bitwise OR-assignment
+         * @note Complexity: @f$ \mathcal{O(n)} @f$
          */
         constexpr Nat& operator|=(const Nat& rhs) {
             // add additional digits to this if fewer than rhs
@@ -655,22 +678,26 @@ namespace com::saxbophone::arby {
         }
         /**
          * @brief bitwise OR operator for Nat
+         * @note Complexity: @f$ \mathcal{O(n)} @f$
          */
         friend constexpr Nat operator|(Nat lhs, const Nat& rhs) {
             lhs |= rhs; // reuse member operator
             return lhs;
         }
         /**
          * @brief bitwise AND-assignment
+         * @note Complexity: @f$ \mathcal{O(n)} @f$
          */
         constexpr Nat& operator&=(const Nat& rhs) {
             /*
              * if rhs has fewer digits than this, we can remove this' leading
              * digits because they would be AND'ed with implicit zero which is
              * always zero
              */
-            if (rhs._digits.size() < _digits.size()) {
-                while (_digits.size() > rhs._digits.size()) {
+            std::size_t lhs_size = _digits.size();
+            std::size_t rhs_size = rhs._digits.size();
+            if (lhs_size > rhs_size) {
+                for (std::size_t i = 0; i < lhs_size - rhs_size; i++) {
                     _digits.pop_front();
                 }
             }
@@ -686,20 +713,22 @@ namespace com::saxbophone::arby {
                 *it &= *rhs_it;
             }
             // remove any leading zeroes
-            while (_digits.size() > 0 and _digits.front() == 0) {
+            while (not _digits.empty() and _digits.front() == 0) {
                 _digits.pop_front();
             }
             return *this;
         }
         /**
          * @brief bitwise AND operator for Nat
+         * @note Complexity: @f$ \mathcal{O(n)} @f$
          */
         friend constexpr Nat operator&(Nat lhs, const Nat& rhs) {
             lhs &= rhs; // reuse member operator
             return lhs;
         }
         /**
          * @brief bitwise XOR-assignment
+         * @note Complexity: @f$ \mathcal{O(n)} @f$
          */
         constexpr Nat& operator^=(const Nat& rhs) {
             Nat result = *this ^ rhs; // reuse friend function
@@ -709,6 +738,7 @@ namespace com::saxbophone::arby {
         }
         /**
          * @brief bitwise XOR operator for Nat
+         * @note Complexity: @f$ \mathcal{O(n)} @f$
          */
         friend constexpr Nat operator^(Nat lhs, const Nat& rhs) {
             Nat result;
@@ -764,6 +794,7 @@ namespace com::saxbophone::arby {
         /**
          * @brief contextual conversion to bool (behaves same way as int)
          * @returns `false` when value is `0`, otherwise `true`
+         * @note Complexity is @f$ \mathcal{O(n)} @f$ but should be @f$ \mathcal{O(1)} @f$
          */
         explicit constexpr operator bool() const {
             // zero is false --all other values are true

arby/include/arby/math.hpp

@@ -29,12 +29,7 @@ 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.
+     * @todo Work out time-complexity
      * @relatedalso Nat
      */
     constexpr Nat pow(const Nat& base, const Nat& exponent) {
@@ -67,6 +62,8 @@ namespace com::saxbophone::arby {
      * @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$
+     * @todo Work out time-complexity
+     * @relatedalso Nat
      */
     constexpr std::pair<Nat, Nat> ilog(const Nat& base, const Nat& x) {
         if (base < 2) {

tests/Nat/basic_arithmetic.cpp

@@ -287,6 +287,21 @@ TEST_CASE("Addition of arby::Nat and much smaller arby::Nat", "[basic-arithmetic
     CHECK((uintmax_t)result == addition);
 }
 
+TEST_CASE("arby::Nat + 0") {
+    arby::Nat value = GENERATE((uintmax_t)0, std::numeric_limits<uintmax_t>::max());
+
+    CHECK((value + 0) == value);
+}
+
+TEST_CASE("arby::Nat += 0") {
+    uintmax_t value = GENERATE((uintmax_t)0, std::numeric_limits<uintmax_t>::max());
+    arby::Nat object = value;
+
+    object += 0;
+
+    CHECK((uintmax_t)object == value);
+}
+
 TEST_CASE("Assignment-subtraction of arby::Nat from arby::Nat", "[basic-arithmetic]") {
     auto minuend = GENERATE(take(100, random((uintmax_t)1, std::numeric_limits<uintmax_t>::max())));
     // ensure subtrahend is never bigger than minuend so we don't underflow
@@ -384,3 +399,18 @@ TEST_CASE("Subtraction of arby::Nat(0) from arby::Nat(0)", "[basic-arithmetic]")
 
     CHECK((uintmax_t)(lhs - rhs) == 0);
 }
+
+TEST_CASE("arby::Nat - 0") {
+    arby::Nat value = GENERATE((uintmax_t)0, std::numeric_limits<uintmax_t>::max());
+
+    CHECK((value - 0) == value);
+}
+
+TEST_CASE("arby::Nat -= 0") {
+    uintmax_t value = GENERATE((uintmax_t)0, std::numeric_limits<uintmax_t>::max());
+    arby::Nat object = value;
+
+    object -= 0;
+
+    CHECK((uintmax_t)object == value);
+}