Merge branch 'master' into test/PalindromeTest

Author: alxkm

pom.xml

@@ -107,7 +107,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-checkstyle-plugin</artifactId>
-                <version>3.4.0</version>
+                <version>3.5.0</version>
                 <configuration>
                     <configLocation>checkstyle.xml</configLocation>
                     <consoleOutput>true</consoleOutput>

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;

src/main/java/com/thealgorithms/maths/TwinPrime.java

@@ -16,7 +16,7 @@ private TwinPrime() {
     /**
      * This method returns twin prime of the integer value passed as argument
      *
-     * @param input_number Integer value of which twin prime is to be found
+     * @param inputNumber Integer value of which twin prime is to be found
      * @return (number + 2) if number and (number + 2) are prime, -1 otherwise
      */
     static int getTwinPrime(int inputNumber) {

src/main/java/com/thealgorithms/strings/PermuteString.java

@@ -1,51 +1,89 @@
 package com.thealgorithms.strings;
 
-/*
-Backtracking algorithm used in the program:-
+import java.util.HashSet;
+import java.util.Set;
 
->>Fix a character in the first position and swap the rest of the character with the first character.
-  Like in ABC, in the first iteration three strings are formed: ABC, BAC, and CBA by swapping A with
-  A, B and C respectively.
->>Repeat step 1 for the rest of the characters like fixing second character B and so on.
->>Now swap again to go back to the previous position. E.g., from ABC, we formed ABC by fixing B
-again, and we backtrack to the previous position and swap B with C. So, now we got ABC and ACB.
->>Repeat these steps for BAC and CBA, to get all the permutations.
+/**
+ * This class provides methods for generating all permutations of a given string using a backtracking algorithm.
+ * <p>
+ * The algorithm works as follows:
+ * <ol>
+ *     <li>Fix a character in the current position and swap it with each of the remaining characters.
+ *         For example, for the string "ABC":
+ *         <ul>
+ *             <li>Fix 'A' at the first position: permutations are "ABC", "BAC", "CBA" (obtained by swapping 'A' with 'B' and 'C' respectively).</li>
+ *         </ul>
+ *     </li>
+ *     <li>Repeat the process for the next character.
+ *         For instance, after fixing 'B' in the second position:
+ *         <ul>
+ *             <li>For "BAC", the permutations include "BAC" and "BCA" (after swapping 'A' and 'C').</li>
+ *         </ul>
+ *     </li>
+ *     <li>After generating permutations for the current position, backtrack by swapping the characters back to their original positions to restore the state.
+ *         For example, after generating permutations for "ABC", swap back to restore "BAC" and continue with further permutations.</li>
+ *     <li>Repeat the process for all characters to get all possible permutations.</li>
+ * </ol>
+ * </p>
  */
 public final class PermuteString {
     private PermuteString() {
     }
 
-    // Function for swapping the characters at position I with character at position j
-    public static String swapString(String a, int i, int j) {
-        char[] b = a.toCharArray();
-        char ch;
-        ch = b[i];
-        b[i] = b[j];
-        b[j] = ch;
-        return String.valueOf(b);
+    /**
+     * Generates all possible permutations of the given string.
+     *
+     * <p>This method returns a set containing all unique permutations of the input string. It leverages
+     * a recursive helper method to generate these permutations.
+     *
+     * @param str The input string for which permutations are to be generated.
+     *            If the string is null or empty, the result will be an empty set.
+     * @return A {@link Set} of strings containing all unique permutations of the input string.
+     *         If the input string has duplicate characters, the set will ensure that only unique permutations
+     *         are returned.
+     */
+    public static Set<String> getPermutations(String str) {
+        Set<String> permutations = new HashSet<>();
+        generatePermutations(str, 0, str.length(), permutations);
+        return permutations;
     }
 
-    public static void main(String[] args) {
-        String str = "ABC";
-        int len = str.length();
-        System.out.println("All the permutations of the string are: ");
-        generatePermutation(str, 0, len);
-    }
-
-    // Function for generating different permutations of the string
-    public static void generatePermutation(String str, int start, int end) {
-        // Prints the permutations
+    /**
+     * Generates all permutations of the given string and collects them into a set.
+     *
+     * @param str the string to permute
+     * @param start the starting index for the current permutation
+     * @param end the end index (length of the string)
+     * @param permutations the set to collect all unique permutations
+     */
+    private static void generatePermutations(String str, int start, int end, Set<String> permutations) {
         if (start == end - 1) {
-            System.out.println(str);
+            permutations.add(str);
         } else {
-            for (int i = start; i < end; i++) {
-                // Swapping the string by fixing a character
-                str = swapString(str, start, i);
-                // Recursively calling function generatePermutation() for rest of the characters
-                generatePermutation(str, start + 1, end);
-                // Backtracking and swapping the characters again.
-                str = swapString(str, start, i);
+            for (int currentIndex = start; currentIndex < end; currentIndex++) {
+                // Swap the current character with the character at the start index
+                str = swapCharacters(str, start, currentIndex);
+                // Recursively generate permutations for the remaining characters
+                generatePermutations(str, start + 1, end, permutations);
+                // Backtrack: swap the characters back to their original positions
+                str = swapCharacters(str, start, currentIndex);
             }
         }
     }
+
+    /**
+     * Swaps the characters at the specified positions in the given string.
+     *
+     * @param str the string in which characters will be swapped
+     * @param i the position of the first character to swap
+     * @param j the position of the second character to swap
+     * @return a new string with the characters at positions i and j swapped
+     */
+    private static String swapCharacters(String str, int i, int j) {
+        char[] chars = str.toCharArray();
+        char temp = chars[i];
+        chars[i] = chars[j];
+        chars[j] = temp;
+        return new String(chars);
+    }
 }

src/main/java/com/thealgorithms/strings/StringCompression.java

@@ -10,7 +10,7 @@ private StringCompression() {
     /**
      * Returns the compressed or encoded string
      *
-     * @param ch character array that contains the group of characters to be encoded
+     * @param input character array that contains the group of characters to be encoded
      * @return the compressed character array as string
      */
     public static String compress(String input) {

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));
+    }
+}

src/test/java/com/thealgorithms/strings/PermuteStringTest.java

@@ -0,0 +1,29 @@
+package com.thealgorithms.strings;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.util.Set;
+import java.util.stream.Stream;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
+
+public class PermuteStringTest {
+
+    private static Stream<TestData> provideTestCases() {
+        return Stream.of(new TestData("ABC", Set.of("ABC", "ACB", "BAC", "BCA", "CAB", "CBA")), new TestData("AB", Set.of("AB", "BA")), new TestData("A", Set.of("A")), new TestData("AA", Set.of("AA")), new TestData("123", Set.of("123", "132", "213", "231", "312", "321")),
+            new TestData("aA", Set.of("aA", "Aa")), new TestData("AaB", Set.of("AaB", "ABa", "aAB", "aBA", "BAa", "BaA")), new TestData("!@", Set.of("!@", "@!")), new TestData("!a@", Set.of("!a@", "!@a", "a!@", "a@!", "@!a", "@a!")),
+            new TestData("ABCD", Set.of("ABCD", "ABDC", "ACBD", "ACDB", "ADBC", "ADCB", "BACD", "BADC", "BCAD", "BCDA", "BDAC", "BDCA", "CABD", "CADB", "CBAD", "CBDA", "CDAB", "CDBA", "DABC", "DACB", "DBAC", "DBCA", "DCAB", "DCBA")),
+            new TestData("A B", Set.of("A B", "AB ", " AB", " BA", "BA ", "B A")),
+            new TestData("abcd", Set.of("abcd", "abdc", "acbd", "acdb", "adbc", "adcb", "bacd", "badc", "bcad", "bcda", "bdac", "bdca", "cabd", "cadb", "cbad", "cbda", "cdab", "cdba", "dabc", "dacb", "dbac", "dbca", "dcab", "dcba")));
+    }
+
+    @ParameterizedTest
+    @MethodSource("provideTestCases")
+    void testPermutations(TestData testData) {
+        Set<String> actualPermutations = PermuteString.getPermutations(testData.input);
+        assertEquals(testData.expected, actualPermutations, "The permutations of '" + testData.input + "' are not correct.");
+    }
+
+    record TestData(String input, Set<String> expected) {
+    }
+}