Merge branch 'master' into master

Author: anant-jain01

DIRECTORY.md

@@ -183,7 +183,7 @@
     <!-- See https://checkstyle.org/checks/misc/index.html -->
     <module name="ArrayTypeStyle"/>
     <!-- TODO <module name="FinalParameters"/> -->
-    <!-- TODO <module name="TodoComment"/> -->
+    <module name="TodoComment"/>
     <module name="UpperEll"/>
 
     <!-- https://checkstyle.org/filters/suppressionxpathfilter.html -->

checkstyle.xml

@@ -40,6 +40,13 @@
             <version>${assertj.version}</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <version>5.14.1</version>
+            <scope>test</scope>
+        </dependency>
+
 
         <dependency>
             <groupId>org.junit.jupiter</groupId>

pom.xml

@@ -87,9 +87,6 @@
         <Bug pattern="RCN_REDUNDANT_NULLCHECK_OF_NONNULL_VALUE" />
     </Match>
     <!-- fb-contrib -->
-    <Match>
-        <Bug pattern="OCP_OVERLY_CONCRETE_PARAMETER" />
-    </Match>
     <Match>
         <Bug pattern="LSC_LITERAL_STRING_COMPARISON" />
     </Match>

spotbugs-exclude.xml

@@ -4,32 +4,44 @@
 import java.util.List;
 
 /**
- * Finds all combinations of 0...n-1 of length k
+ * This class provides methods to find all combinations of integers from 0 to n-1
+ * of a specified length k using backtracking.
  */
 public final class ArrayCombination {
     private ArrayCombination() {
     }
 
     /**
-     * Finds all combinations of length k of 0..n-1 using backtracking.
+     * Generates all possible combinations of length k from the integers 0 to n-1.
      *
-     * @param n Number of the elements.
-     * @param k Length of the combination.
-     * @return A list of all combinations of length k.
+     * @param n The total number of elements (0 to n-1).
+     * @param k The desired length of each combination.
+     * @return A list containing all combinations of length k.
+     * @throws IllegalArgumentException if n or k are negative, or if k is greater than n.
      */
     public static List<List<Integer>> combination(int n, int k) {
         if (n < 0 || k < 0 || k > n) {
-            throw new IllegalArgumentException("Wrong input.");
+            throw new IllegalArgumentException("Invalid input: n must be non-negative, k must be non-negative and less than or equal to n.");
         }
 
         List<List<Integer>> combinations = new ArrayList<>();
         combine(combinations, new ArrayList<>(), 0, n, k);
         return combinations;
     }
 
+    /**
+     * A helper method that uses backtracking to find combinations.
+     *
+     * @param combinations The list to store all valid combinations found.
+     * @param current The current combination being built.
+     * @param start The starting index for the current recursion.
+     * @param n The total number of elements (0 to n-1).
+     * @param k The desired length of each combination.
+     */
     private static void combine(List<List<Integer>> combinations, List<Integer> current, int start, int n, int k) {
-        if (current.size() == k) { // Base case: combination found
-            combinations.add(new ArrayList<>(current)); // Copy to avoid modification
+        // Base case: combination found
+        if (current.size() == k) {
+            combinations.add(new ArrayList<>(current));
             return;
         }
 

src/main/java/com/thealgorithms/backtracking/ArrayCombination.java

@@ -1,6 +1,7 @@
 package com.thealgorithms.backtracking;
 
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.List;
 
 /**
@@ -95,7 +96,7 @@ public static void removeWord(char[][] puzzle, String word, int row, int col, bo
      * @param words  The list of words to be placed.
      * @return true if the crossword is solved, false otherwise.
      */
-    public static boolean solveCrossword(char[][] puzzle, List<String> words) {
+    public static boolean solveCrossword(char[][] puzzle, Collection<String> words) {
         // Create a mutable copy of the words list
         List<String> remainingWords = new ArrayList<>(words);
 

src/main/java/com/thealgorithms/backtracking/CrosswordSolver.java

@@ -0,0 +1,82 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * This class provides methods to convert between BCD (Binary-Coded Decimal) and decimal numbers.
+ *
+ * BCD is a class of binary encodings of decimal numbers where each decimal digit is represented by a fixed number of binary digits, usually four or eight.
+ *
+ * For more information, refer to the
+ * <a href="https://en.wikipedia.org/wiki/Binary-coded_decimal">Binary-Coded Decimal</a> Wikipedia page.
+ *
+ * <b>Example usage:</b>
+ * <pre>
+ * int decimal = BcdConversion.bcdToDecimal(0x1234);
+ * System.out.println("BCD 0x1234 to decimal: " + decimal); // Output: 1234
+ *
+ * int bcd = BcdConversion.decimalToBcd(1234);
+ * System.out.println("Decimal 1234 to BCD: " + Integer.toHexString(bcd)); // Output: 0x1234
+ * </pre>
+ */
+public final class BcdConversion {
+    private BcdConversion() {
+    }
+
+    /**
+     * Converts a BCD (Binary-Coded Decimal) number to a decimal number.
+     * <p>Steps:
+     * <p>1. Validate the BCD number to ensure all digits are between 0 and 9.
+     * <p>2. Extract the last 4 bits (one BCD digit) from the BCD number.
+     * <p>3. Multiply the extracted digit by the corresponding power of 10 and add it to the decimal number.
+     * <p>4. Shift the BCD number right by 4 bits to process the next BCD digit.
+     * <p>5. Repeat steps 1-4 until the BCD number is zero.
+     *
+     * @param bcd The BCD number.
+     * @return The corresponding decimal number.
+     * @throws IllegalArgumentException if the BCD number contains invalid digits.
+     */
+    public static int bcdToDecimal(int bcd) {
+        int decimal = 0;
+        int multiplier = 1;
+
+        // Validate BCD digits
+        while (bcd > 0) {
+            int digit = bcd & 0xF;
+            if (digit > 9) {
+                throw new IllegalArgumentException("Invalid BCD digit: " + digit);
+            }
+            decimal += digit * multiplier;
+            multiplier *= 10;
+            bcd >>= 4;
+        }
+        return decimal;
+    }
+
+    /**
+     * Converts a decimal number to BCD (Binary-Coded Decimal).
+     * <p>Steps:
+     * <p>1. Check if the decimal number is within the valid range for BCD (0 to 9999).
+     * <p>2. Extract the last decimal digit from the decimal number.
+     * <p>3. Shift the digit to the correct BCD position and add it to the BCD number.
+     * <p>4. Remove the last decimal digit from the decimal number.
+     * <p>5. Repeat steps 2-4 until the decimal number is zero.
+     *
+     * @param decimal The decimal number.
+     * @return The corresponding BCD number.
+     * @throws IllegalArgumentException if the decimal number is greater than 9999.
+     */
+    public static int decimalToBcd(int decimal) {
+        if (decimal < 0 || decimal > 9999) {
+            throw new IllegalArgumentException("Value out of bounds for BCD representation: " + decimal);
+        }
+
+        int bcd = 0;
+        int shift = 0;
+        while (decimal > 0) {
+            int digit = decimal % 10;
+            bcd |= (digit << (shift * 4));
+            decimal /= 10;
+            shift++;
+        }
+        return bcd;
+    }
+}

src/main/java/com/thealgorithms/bitmanipulation/BcdConversion.java

@@ -0,0 +1,58 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * This class provides methods to convert between XS-3 (Excess-3) and binary.
+ *
+ * Excess-3, also called XS-3, is a binary-coded decimal (BCD) code in which each decimal digit is represented by its corresponding 4-bit binary value plus 3.
+ *
+ * For more information, refer to the
+ * <a href="https://en.wikipedia.org/wiki/Excess-3">Excess-3</a> Wikipedia page.
+ *
+ * <b>Example usage:</b>
+ * <pre>
+ * int binary = Xs3Conversion.xs3ToBinary(0x4567);
+ * System.out.println("XS-3 0x4567 to binary: " + binary); // Output: 1234
+ *
+ * int xs3 = Xs3Conversion.binaryToXs3(1234);
+ * System.out.println("Binary 1234 to XS-3: " + Integer.toHexString(xs3)); // Output: 0x4567
+ * </pre>
+ */
+public final class Xs3Conversion {
+    private Xs3Conversion() {
+    }
+    /**
+     * Converts an XS-3 (Excess-3) number to binary.
+     *
+     * @param xs3 The XS-3 number.
+     * @return The corresponding binary number.
+     */
+    public static int xs3ToBinary(int xs3) {
+        int binary = 0;
+        int multiplier = 1;
+        while (xs3 > 0) {
+            int digit = (xs3 & 0xF) - 3; // Extract the last 4 bits (one XS-3 digit) and subtract 3
+            binary += digit * multiplier;
+            multiplier *= 10;
+            xs3 >>= 4; // Shift right by 4 bits to process the next XS-3 digit
+        }
+        return binary;
+    }
+
+    /**
+     * Converts a binary number to XS-3 (Excess-3).
+     *
+     * @param binary The binary number.
+     * @return The corresponding XS-3 number.
+     */
+    public static int binaryToXs3(int binary) {
+        int xs3 = 0;
+        int shift = 0;
+        while (binary > 0) {
+            int digit = (binary % 10) + 3; // Extract the last decimal digit and add 3
+            xs3 |= (digit << (shift * 4)); // Shift the digit to the correct XS-3 position
+            binary /= 10; // Remove the last decimal digit
+            shift++;
+        }
+        return xs3;
+    }
+}

src/main/java/com/thealgorithms/bitmanipulation/Xs3Conversion.java

@@ -0,0 +1,147 @@
+package com.thealgorithms.ciphers;
+
+import java.util.Arrays;
+
+/**
+ * The rail fence cipher (also called a zigzag cipher) is a classical type of transposition cipher.
+ * It derives its name from the manner in which encryption is performed, in analogy to a fence built with horizontal rails.
+ * https://en.wikipedia.org/wiki/Rail_fence_cipher
+ * @author https://github.com/Krounosity
+ */
+
+public class RailFenceCipher {
+
+    // Encrypts the input string using the rail fence cipher method with the given number of rails.
+    public String encrypt(String str, int rails) {
+
+        // Base case of single rail or rails are more than the number of characters in the string
+        if (rails == 1 || rails >= str.length()) {
+            return str;
+        }
+
+        // Boolean flag to determine if the movement is downward or upward in the rail matrix.
+        boolean down = true;
+        // Create a 2D array to represent the rails (rows) and the length of the string (columns).
+        char[][] strRail = new char[rails][str.length()];
+
+        // Initialize all positions in the rail matrix with a placeholder character ('\n').
+        for (int i = 0; i < rails; i++) {
+            Arrays.fill(strRail[i], '\n');
+        }
+
+        int row = 0; // Start at the first row
+        int col = 0; // Start at the first column
+
+        int i = 0;
+
+        // Fill the rail matrix with characters from the string based on the rail pattern.
+        while (col < str.length()) {
+            // Change direction to down when at the first row.
+            if (row == 0) {
+                down = true;
+            }
+            // Change direction to up when at the last row.
+            else if (row == rails - 1) {
+                down = false;
+            }
+
+            // Place the character in the current position of the rail matrix.
+            strRail[row][col] = str.charAt(i);
+            col++; // Move to the next column.
+            // Move to the next row based on the direction.
+            if (down) {
+                row++;
+            } else {
+                row--;
+            }
+
+            i++;
+        }
+
+        // Construct the encrypted string by reading characters row by row.
+        StringBuilder encryptedString = new StringBuilder();
+        for (char[] chRow : strRail) {
+            for (char ch : chRow) {
+                if (ch != '\n') {
+                    encryptedString.append(ch);
+                }
+            }
+        }
+        return encryptedString.toString();
+    }
+    // Decrypts the input string using the rail fence cipher method with the given number of rails.
+    public String decrypt(String str, int rails) {
+
+        // Base case of single rail or rails are more than the number of characters in the string
+        if (rails == 1 || rails >= str.length()) {
+            return str;
+        }
+        // Boolean flag to determine if the movement is downward or upward in the rail matrix.
+        boolean down = true;
+
+        // Create a 2D array to represent the rails (rows) and the length of the string (columns).
+        char[][] strRail = new char[rails][str.length()];
+
+        int row = 0; // Start at the first row
+        int col = 0; // Start at the first column
+
+        // Mark the pattern on the rail matrix using '*'.
+        while (col < str.length()) {
+            // Change direction to down when at the first row.
+            if (row == 0) {
+                down = true;
+            }
+            // Change direction to up when at the last row.
+            else if (row == rails - 1) {
+                down = false;
+            }
+
+            // Mark the current position in the rail matrix.
+            strRail[row][col] = '*';
+            col++; // Move to the next column.
+            // Move to the next row based on the direction.
+            if (down) {
+                row++;
+            } else {
+                row--;
+            }
+        }
+
+        int index = 0; // Index to track characters from the input string.
+        // Fill the rail matrix with characters from the input string based on the marked pattern.
+        for (int i = 0; i < rails; i++) {
+            for (int j = 0; j < str.length(); j++) {
+                if (strRail[i][j] == '*') {
+                    strRail[i][j] = str.charAt(index++);
+                }
+            }
+        }
+
+        // Construct the decrypted string by following the zigzag pattern.
+        StringBuilder decryptedString = new StringBuilder();
+        row = 0; // Reset to the first row
+        col = 0; // Reset to the first column
+
+        while (col < str.length()) {
+            // Change direction to down when at the first row.
+            if (row == 0) {
+                down = true;
+            }
+            // Change direction to up when at the last row.
+            else if (row == rails - 1) {
+                down = false;
+            }
+            // Append the character from the rail matrix to the decrypted string.
+            decryptedString.append(strRail[row][col]);
+            col++; // Move to the next column.
+            // Move to the next row based on the direction.
+            if (down) {
+                row++;
+            } else {
+                row--;
+            }
+        }
+
+        return decryptedString.toString();
+    }
+}