[fix/docs]: fit check_amicable_pair.cpp to guidelines (#2465)

* Quality of life

FIX:  initlized sum to 1 instead of adding it before return
CHORE: cleaned documentation aswell as adding new documentation, namespace math added

* Update math/check_amicable_pair.cpp

Co-authored-by: realstealthninja <[email protected]>

* Update math/check_amicable_pair.cpp

Co-authored-by: David Leal <[email protected]>

* Update math/check_amicable_pair.cpp

Co-authored-by: David Leal <[email protected]>

* Update math/check_amicable_pair.cpp

Co-authored-by: David Leal <[email protected]>

* clang-format and clang-tidy fixes for bc87fea

* clang-format and clang-tidy fixes for 0a19d1a

---------

Co-authored-by: realstealthninja <[email protected]>
Co-authored-by: David Leal <[email protected]>
Co-authored-by: github-actions[bot] <[email protected]>

Author: 4 people

bit_manipulation/next_higher_number_with_same_number_of_set_bits.cpp

@@ -5,9 +5,10 @@
  * implementation
  *
  * @details
- * Given a number x, find next number with same number of 1 bits in it’s binary representation.
- * For example, consider x = 12, whose binary representation is 1100 (excluding leading zeros on 32 bit machine).
- * It contains two logic 1 bits. The next higher number with two logic 1 bits is 17 (100012).
+ * Given a number x, find next number with same number of 1 bits in it’s binary
+ * representation. For example, consider x = 12, whose binary representation is
+ * 1100 (excluding leading zeros on 32 bit machine). It contains two logic 1
+ * bits. The next higher number with two logic 1 bits is 17 (100012).
  *
  * A binary number consists of two digits. They are 0 & 1. Digit 1 is known as
  * set bit in computer terms.
@@ -28,43 +29,39 @@ namespace bit_manipulation {
  * @param x the number that will be calculated
  * @returns a number
  */
-uint64_t next_higher_number(uint64_t x)
-{
- 
-  uint64_t rightOne;
-  uint64_t nextHigherOneBit;
-  uint64_t rightOnesPattern;
- 
-  uint64_t next = 0;
- 
-  if(x)
-  {
- 
-    // right most set bit
-    rightOne = x & -(signed)x;
- 
-    // reset the pattern and set next higher bit
-    // left part of x will be here
-    nextHigherOneBit = x + rightOne;
- 
-    // nextHigherOneBit is now part [D] of the above explanation.
- 
-    // isolate the pattern
-    rightOnesPattern = x ^ nextHigherOneBit;
- 
-    // right adjust pattern
-    rightOnesPattern = (rightOnesPattern)/rightOne;
- 
-    // correction factor
-    rightOnesPattern >>= 2;
- 
-    // rightOnesPattern is now part [A] of the above explanation.
- 
-    // integrate new pattern (Add [D] and [A])
-    next = nextHigherOneBit | rightOnesPattern;
-  }
- 
-  return next;
+uint64_t next_higher_number(uint64_t x) {
+    uint64_t rightOne = 0;
+    uint64_t nextHigherOneBit = 0;
+    uint64_t rightOnesPattern = 0;
+
+    uint64_t next = 0;
+
+    if (x) {
+        // right most set bit
+        rightOne = x & -static_cast<signed>(x);
+
+        // reset the pattern and set next higher bit
+        // left part of x will be here
+        nextHigherOneBit = x + rightOne;
+
+        // nextHigherOneBit is now part [D] of the above explanation.
+
+        // isolate the pattern
+        rightOnesPattern = x ^ nextHigherOneBit;
+
+        // right adjust pattern
+        rightOnesPattern = (rightOnesPattern) / rightOne;
+
+        // correction factor
+        rightOnesPattern >>= 2;
+
+        // rightOnesPattern is now part [A] of the above explanation.
+
+        // integrate new pattern (Add [D] and [A])
+        next = nextHigherOneBit | rightOnesPattern;
+    }
+
+    return next;
 }
 
 }  // namespace bit_manipulation

math/armstrong_number.cpp

@@ -1,24 +1,24 @@
 /**
-* @file
-* @brief Program to check if a number is an [Armstrong/Narcissistic
-* number](https://en.wikipedia.org/wiki/Narcissistic_number) in decimal system.
-*
-* @details
-* Armstrong number or [Narcissistic
-* number](https://en.wikipedia.org/wiki/Narcissistic_number) is a number that
-* is the sum of its own digits raised to the power of the number of digits.
-*
-* let n be the narcissistic number,
-* \f[F_b(n) = \sum_{i=0}^{k-1}d_{i}^{k}\f] for
-* \f$ b > 1 F_b : \N \to \N \f$ where
-* \f$ k = \lfloor log_b n\rfloor is the number of digits in the number in base \f$b\f$, and
-* \f$ d_i = \frac{n mod b^{i+1} - n mod b^{i}}{b^{i}} \f$
-*
-* @author [Neeraj Cherkara](https://github.com/iamnambiar)
-*/
-#include <cassert> /// for assert
-#include <cmath> /// for std::pow
-#include <iostream> /// for IO operations
+ * @file
+ * @brief Program to check if a number is an [Armstrong/Narcissistic
+ * number](https://en.wikipedia.org/wiki/Narcissistic_number) in decimal system.
+ *
+ * @details
+ * Armstrong number or [Narcissistic
+ * number](https://en.wikipedia.org/wiki/Narcissistic_number) is a number that
+ * is the sum of its own digits raised to the power of the number of digits.
+ *
+ * let n be the narcissistic number,
+ * \f[F_b(n) = \sum_{i=0}^{k-1}d_{i}^{k}\f] for
+ * \f$ b > 1 F_b : \N \to \N \f$ where
+ * \f$ k = \lfloor log_b n\rfloor is the number of digits in the number in base
+ * \f$b\f$, and \f$ d_i = \frac{n mod b^{i+1} - n mod b^{i}}{b^{i}} \f$
+ *
+ * @author [Neeraj Cherkara](https://github.com/iamnambiar)
+ */
+#include <cassert>   /// for assert
+#include <cmath>     /// for std::pow
+#include <iostream>  /// for IO operations
 
 /**
  * @brief Function to calculate the total number of digits in the number.
@@ -61,9 +61,9 @@ bool is_armstrong(int number) {
 }
 
 /**
-* @brief Self-test implementations
-* @returns void
-*/
+ * @brief Self-test implementations
+ * @returns void
+ */
 static void test() {
     // is_armstrong(370) returns true.
     assert(is_armstrong(370) == true);
@@ -82,10 +82,10 @@ static void test() {
 }
 
 /**
-* @brief Main Function
-* @returns 0 on exit
-*/
+ * @brief Main Function
+ * @returns 0 on exit
+ */
 int main() {
-    test(); // run self-test implementations
+    test();  // run self-test implementations
     return 0;
 }

math/check_amicable_pair.cpp

@@ -1,26 +1,36 @@
 /**
- *
  * @file
- * \brief A C++ Program to check whether a pair of number is [amicable
+ * @brief A C++ Program to check whether a pair of numbers is an [amicable
  * pair](https://en.wikipedia.org/wiki/Amicable_numbers) or not.
  *
- * \details
- * Amicable Pair are two positive integers such that sum of the proper divisor
- * of each number is equal to the other number.
- * @author iamnambiar
+ * @details
+ * An Amicable Pair is two positive integers such that the sum of the proper
+ * divisor for each number is equal to the other number.
+ *
+ * @note Remember that a proper divisor is any positive whole number that
+ * divides into a selected number, apart from the selected number itself, and
+ * returns a positive integer. for example 1, 2 and  5 are all proper divisors
+ * of 10.
+ *
+ * @author [iamnambiar](https://github.com/iamnambiar)
  */
-#include <cassert>
-#include <iostream>
+#include <cassert>   /// for assert
+#include <iostream>  /// for IO operations
 
 /**
- * Function to calculate the sum of all the proper divisor
+ * @brief Mathematical algorithms
+ * @namespace
+ */
+namespace math {
+/**
+ * @brief Function to calculate the sum of all the proper divisor
  * of an integer.
- * @param num First number.
+ * @param num selected number.
  * @return Sum of the proper divisor of the number.
  */
 int sum_of_divisor(int num) {
     // Variable to store the sum of all proper divisors.
-    int sum = 0;
+    int sum = 1;
     // Below loop condition helps to reduce Time complexity by a factor of
     // square root of the number.
     for (int div = 2; div * div <= num; ++div) {
@@ -35,11 +45,11 @@ int sum_of_divisor(int num) {
             }
         }
     }
-    return sum + 1;
+    return sum;
 }
 
 /**
- * Function to check whether the pair is amicable or not.
+ * @brief Function to check whether the pair is amicable or not.
  * @param x First number.
  * @param y Second number.
  * @return `true` if the pair is amicable
@@ -48,25 +58,27 @@ int sum_of_divisor(int num) {
 bool are_amicable(int x, int y) {
     return (sum_of_divisor(x) == y) && (sum_of_divisor(y) == x);
 }
+}  // namespace math
 
 /**
- * Function for testing the is_amicable() with
- * all the test cases.
+ * @brief Self-test implementations
+ * @returns void
  */
-void test() {
-    // are_amicable(220, 284) returns true.
-    assert(are_amicable(220, 284) == true);
-    // are_amicable(6232, 6368) returns true.
-    assert(are_amicable(6368, 6232) == true);
-    // are_amicable(458, 232) returns false.
-    assert(are_amicable(458, 232) == false);
+static void tests() {
+    assert(math::are_amicable(220, 284) == true);
+    assert(math::are_amicable(6368, 6232) == true);
+    assert(math::are_amicable(458, 232) == false);
+    assert(math::are_amicable(17296, 18416) == true);
+    assert(math::are_amicable(18416, 17296) == true);
+
+    std::cout << "All tests have successfully passed!" << std::endl;
 }
 
 /**
- * Main Function
+ * @brief Main function
+ * @returns 0 on exit
  */
 int main() {
-    test();
-    std::cout << "Assertion Success." << std::endl;
+    tests();  // perform self-tests implementations
     return 0;
 }