Repository: TheAlgorithms/Java
Pull request #5364 (2024-08-22 18:03:30)

refactor: `Pow`
Javadocs improvements.
Readability improvements.
Added tests.

<!--
Thank you for your contribution!
In order to reduce the number of notifications sent to the maintainers, please:
- create your PR as draft, cf. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests,
- make sure that all of the CI checks pass,
- mark your PR as ready for review, cf. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#marking-a-pull-request-as-ready-for-review
-->

<!-- For completed items, change [ ] to [x] -->

- [x] I have read [CONTRIBUTING.md](https://github.com/TheAlgorithms/Java/blob/master/CONTRIBUTING.md).
- [x] This pull request is all my own work -- I have not plagiarized it.
- [x] All filenames are in PascalCase.
- [x] All functions and variable names follow Java naming conventions.
- [x] All new algorithms have a URL in their comments that points to Wikipedia or other similar explanations.
- [x] All new code is formatted with `clang-format -i --style=file path/to/your/file.java`

codecov-commenter: ## [Codecov](https://app.codecov.io/gh/TheAlgorithms/Java/pull/5364?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TheAlgorithms) Report
All modified and coverable lines are covered by tests :white_check_mark:
> Project coverage is 45.94%. Comparing base [(`74b05ef`)](https://app.codecov.io/gh/TheAlgorithms/Java/commit/74b05ef7c2bf34f2d1acda5f75fdbd8653e728c1?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TheAlgorithms) to head [(`532d4b0`)](https://app.codecov.io/gh/TheAlgorithms/Java/commit/532d4b0ce2d0d741ba32492583243b7193e22720?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TheAlgorithms).

<details><summary>Additional details and impacted files</summary>


```diff
@@             Coverage Diff              @@
##             master    #5364      +/-   ##
============================================
+ Coverage     45.88%   45.94%   +0.06%     
- Complexity     2857     2860       +3     
============================================
  Files           525      525              
  Lines         15418    15414       -4     
  Branches       2917     2914       -3     
============================================
+ Hits           7074     7082       +8     
+ Misses         8048     8037      -11     
+ Partials        296      295       -1     
```

</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/TheAlgorithms/Java/pull/5364?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TheAlgorithms).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TheAlgorithms).


Patch:
diff --git a/src/main/java/com/thealgorithms/maths/Pow.java b/src/main/java/com/thealgorithms/maths/Pow.java
index 3f362fe8..377b37ac 100644
--- a/src/main/java/com/thealgorithms/maths/Pow.java
+++ b/src/main/java/com/thealgorithms/maths/Pow.java
@@ -1,26 +1,32 @@
 package com.thealgorithms.maths;
 
-// POWER (exponentials) Examples (a^b)
+/**
+ * A utility class for computing exponentiation (power) of integers.
+ * <p>
+ * This class provides a method to calculate the value of a base raised to a given exponent using a simple iterative approach.
+ * For example, given a base {@code a} and an exponent {@code b}, the class computes {@code a}<sup>{@code b}</sup>.
+ * </p>
+ */
 public final class Pow {
     private Pow() {
     }
 
-    public static void main(String[] args) {
-        assert pow(2, 0) == Math.pow(2, 0); // == 1
-        assert pow(0, 2) == Math.pow(0, 2); // == 0
-        assert pow(2, 10) == Math.pow(2, 10); // == 1024
-        assert pow(10, 2) == Math.pow(10, 2); // == 100
-    }
-
     /**
-     * Returns the value of the first argument raised to the power of the second
-     * argument
+     * Computes the value of the base raised to the power of the exponent.
+     * <p>
+     * The method calculates {@code a}<sup>{@code b}</sup> by iteratively multiplying the base {@code a} with itself {@code b} times.
+     * If the exponent {@code b} is negative, an {@code IllegalArgumentException} is thrown.
+     * </p>
      *
-     * @param a the base.
-     * @param b the exponent.
-     * @return the value {@code a}<sup>{@code b}</sup>.
+     * @param a the base of the exponentiation. Must be a non-negative integer.
+     * @param b the exponent to which the base {@code a} is raised. Must be a non-negative integer.
+     * @return the result of {@code a}<sup>{@code b}</sup> as a {@code long}.
+     * @throws IllegalArgumentException if {@code b} is negative.
      */
     public static long pow(int a, int b) {
+        if (b < 0) {
+            throw new IllegalArgumentException("Exponent must be non-negative.");
+        }
         long result = 1;
         for (int i = 1; i <= b; i++) {
             result *= a;


Test patch:
diff --git a/src/test/java/com/thealgorithms/maths/PowTest.java b/src/test/java/com/thealgorithms/maths/PowTest.java
new file mode 100644
index 00000000..4309b0f1
--- /dev/null
+++ b/src/test/java/com/thealgorithms/maths/PowTest.java
@@ -0,0 +1,36 @@
+package com.thealgorithms.maths;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+public class PowTest {
+    @ParameterizedTest
+    @CsvSource({"2, 0, 1", "0, 2, 0", "2, 10, 1024", "10, 2, 100", "5, 3, 125", "3, 4, 81"})
+    void testPow(int base, int exponent, long expected) {
+        assertEquals(expected, Pow.pow(base, exponent), "Failed for base: " + base + " and exponent: " + exponent);
+    }
+
+    @Test
+    void testPowThrowsExceptionForNegativeExponent() {
+        assertThrows(IllegalArgumentException.class, () -> Pow.pow(2, -1));
+    }
+
+    @Test
+    void testPowHandlesLargeNumbers() {
+        assertEquals(1048576, Pow.pow(2, 20));
+    }
+
+    @Test
+    void testPowHandlesZeroBase() {
+        assertEquals(0, Pow.pow(0, 5));
+    }
+
+    @Test
+    void testPowHandlesOneBase() {
+        assertEquals(1, Pow.pow(1, 100));
+    }
+}