Merge branch 'master' into twos_improve

Author: Hardvan

DIRECTORY.md

@@ -20,7 +20,7 @@
             <dependency>
                 <groupId>org.junit</groupId>
                 <artifactId>junit-bom</artifactId>
-                <version>5.11.2</version>
+                <version>5.11.3</version>
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
@@ -31,7 +31,7 @@
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter</artifactId>
-            <version>5.11.2</version>
+            <version>5.11.3</version>
             <scope>test</scope>
         </dependency>
         <dependency>
@@ -43,15 +43,15 @@
         <dependency>
             <groupId>org.mockito</groupId>
             <artifactId>mockito-core</artifactId>
-            <version>5.14.1</version>
+            <version>5.14.2</version>
             <scope>test</scope>
         </dependency>
 
 
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter-api</artifactId>
-            <version>5.11.2</version>
+            <version>5.11.3</version>
             <scope>test</scope>
         </dependency>
         <dependency>
@@ -132,7 +132,7 @@
             <plugin>
                 <groupId>com.github.spotbugs</groupId>
                 <artifactId>spotbugs-maven-plugin</artifactId>
-                <version>4.8.6.4</version>
+                <version>4.8.6.5</version>
                 <configuration>
                     <excludeFilterFile>spotbugs-exclude.xml</excludeFilterFile>
                     <includeTests>true</includeTests>

pom.xml

@@ -1,13 +1,27 @@
 package com.thealgorithms.bitmanipulation;
 
 /**
- * Is number power of 2
+ * Utility class for checking if a number is a power of two.
+ * A power of two is a number that can be expressed as 2^n where n is a non-negative integer.
+ * This class provides a method to determine if a given integer is a power of two using bit manipulation.
+ *
  * @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
  */
-
 public final class IsPowerTwo {
     private IsPowerTwo() {
     }
+
+    /**
+     * Checks if the given integer is a power of two.
+     *
+     * A number is considered a power of two if it is greater than zero and
+     * has exactly one '1' bit in its binary representation. This method
+     * uses the property that for any power of two (n), the expression
+     * (n & (n - 1)) will be zero.
+     *
+     * @param number the integer to check
+     * @return true if the number is a power of two, false otherwise
+     */
     public static boolean isPowerTwo(int number) {
         if (number <= 0) {
             return false;

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

@@ -1,14 +1,30 @@
 package com.thealgorithms.bitmanipulation;
 
 /**
- * Find Non Repeating Number
+ * A utility class to find the non-repeating number in an array where every other number repeats.
+ * This class contains a method to identify the single unique number using bit manipulation.
+ *
+ * The solution leverages the properties of the XOR operation, which states that:
+ * - x ^ x = 0 for any integer x (a number XORed with itself is zero)
+ * - x ^ 0 = x for any integer x (a number XORed with zero is the number itself)
+ *
+ * Using these properties, we can find the non-repeating number in linear time with constant space.
+ *
+ * Example:
+ * Given the input array [2, 3, 5, 2, 3], the output will be 5 since it does not repeat.
+ *
  * @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
  */
-
 public final class NonRepeatingNumberFinder {
     private NonRepeatingNumberFinder() {
     }
 
+    /**
+     * Finds the non-repeating number in the given array.
+     *
+     * @param arr an array of integers where every number except one appears twice
+     * @return the integer that appears only once in the array or 0 if the array is empty
+     */
     public static int findNonRepeatingNumber(int[] arr) {
         int result = 0;
         for (int num : arr) {

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

@@ -1,21 +1,41 @@
 package com.thealgorithms.bitmanipulation;
 
 /**
- * Find the Number Appearing Odd Times in an array
+ * This class provides a method to find the element that appears an
+ * odd number of times in an array. All other elements in the array
+ * must appear an even number of times for the logic to work.
+ *
+ * The solution uses the XOR operation, which has the following properties:
+ * - a ^ a = 0 (XOR-ing the same numbers cancels them out)
+ * - a ^ 0 = a
+ * - XOR is commutative and associative.
+ *
+ * Time Complexity: O(n), where n is the size of the array.
+ * Space Complexity: O(1), as no extra space is used.
+ *
+ * Usage Example:
+ * int result = NumberAppearingOddTimes.findOddOccurrence(new int[]{1, 2, 1, 2, 3});
+ * // result will be 3
+ *
  * @author Lakshyajeet Singh Goyal (https://github.com/DarkMatter-999)
  */
 
 public final class NumberAppearingOddTimes {
     private NumberAppearingOddTimes() {
     }
+
+    /**
+     * Finds the element in the array that appears an odd number of times.
+     *
+     * @param arr the input array containing integers, where all elements
+     *            except one appear an even number of times.
+     * @return the integer that appears an odd number of times.
+     */
     public static int findOddOccurrence(int[] arr) {
         int result = 0;
-
-        // XOR all elements in the array
         for (int num : arr) {
             result ^= num;
         }
-
         return result;
     }
 }

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

@@ -1,14 +1,29 @@
 package com.thealgorithms.bitmanipulation;
 
 /**
- * Numbers Different Signs
+ * This class provides a method to determine whether two integers have
+ * different signs. It utilizes the XOR operation on the two numbers:
+ *
+ * - If two numbers have different signs, their most significant bits
+ *   (sign bits) will differ, resulting in a negative XOR result.
+ * - If two numbers have the same sign, the XOR result will be non-negative.
+ *
+ * Time Complexity: O(1) - Constant time operation.
+ * Space Complexity: O(1) - No extra space used.
+ *
  * @author Bama Charan Chhandogi
  */
-
 public final class NumbersDifferentSigns {
     private NumbersDifferentSigns() {
     }
 
+    /**
+     * Determines if two integers have different signs using bitwise XOR.
+     *
+     * @param num1 the first integer
+     * @param num2 the second integer
+     * @return true if the two numbers have different signs, false otherwise
+     */
     public static boolean differentSigns(int num1, int num2) {
         return (num1 ^ num2) < 0;
     }

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

@@ -1,34 +1,68 @@
 package com.thealgorithms.bitmanipulation;
 
-/*
+/**
+ * A utility class for performing single-bit operations on integers.
+ * These operations include flipping, setting, clearing, and getting
+ * individual bits at specified positions.
+ *
+ * Bit positions are zero-indexed (i.e., the least significant bit is at position 0).
+ * These methods leverage bitwise operations for optimal performance.
+ *
+ * Examples:
+ * - `flipBit(3, 1)` flips the bit at index 1 in binary `11` (result: `1`).
+ * - `setBit(4, 0)` sets the bit at index 0 in `100` (result: `101` or 5).
+ * - `clearBit(7, 1)` clears the bit at index 1 in `111` (result: `101` or 5).
+ * - `getBit(6, 0)` checks if the least significant bit is set (result: `0`).
+ *
+ * Time Complexity: O(1) for all operations.
+ *
  * Author: lukasb1b (https://github.com/lukasb1b)
  */
-
 public final class SingleBitOperations {
     private SingleBitOperations() {
     }
+
     /**
-     * Flip the bit at position 'bit' in 'num'
+     * Flips (toggles) the bit at the specified position.
+     *
+     * @param num the input number
+     * @param bit the position of the bit to flip (0-indexed)
+     * @return the new number after flipping the specified bit
      */
     public static int flipBit(final int num, final int bit) {
         return num ^ (1 << bit);
     }
+
     /**
-     * Set the bit at position 'bit' to 1 in the 'num' variable
+     * Sets the bit at the specified position to 1.
+     *
+     * @param num the input number
+     * @param bit the position of the bit to set (0-indexed)
+     * @return the new number after setting the specified bit to 1
      */
     public static int setBit(final int num, final int bit) {
         return num | (1 << bit);
     }
+
     /**
-     * Clears the bit located at 'bit' from 'num'
+     * Clears the bit at the specified position (sets it to 0).
+     *
+     * @param num the input number
+     * @param bit the position of the bit to clear (0-indexed)
+     * @return the new number after clearing the specified bit
      */
     public static int clearBit(final int num, final int bit) {
         return num & ~(1 << bit);
     }
+
     /**
-     * Get the bit located at 'bit' from 'num'
+     * Gets the bit value (0 or 1) at the specified position.
+     *
+     * @param num the input number
+     * @param bit the position of the bit to retrieve (0-indexed)
+     * @return 1 if the bit is set, 0 otherwise
      */
     public static int getBit(final int num, final int bit) {
-        return ((num >> bit) & 1);
+        return (num >> bit) & 1;
     }
 }

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

@@ -0,0 +1,71 @@
+package com.thealgorithms.ciphers;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * The Baconian Cipher is a substitution cipher where each letter is represented
+ * by a group of five binary digits (A's and B's). It can also be used to hide
+ * messages within other texts, making it a simple form of steganography.
+ * https://en.wikipedia.org/wiki/Bacon%27s_cipher
+ *
+ * @author Bennybebo
+ */
+public class BaconianCipher {
+
+    private static final Map<Character, String> BACONIAN_MAP = new HashMap<>();
+    private static final Map<String, Character> REVERSE_BACONIAN_MAP = new HashMap<>();
+
+    static {
+        // Initialize the Baconian cipher mappings
+        String[] baconianAlphabet = {"AAAAA", "AAAAB", "AAABA", "AAABB", "AABAA", "AABAB", "AABBA", "AABBB", "ABAAA", "ABAAB", "ABABA", "ABABB", "ABBAA", "ABBAB", "ABBBA", "ABBBB", "BAAAA", "BAAAB", "BAABA", "BAABB", "BABAA", "BABAB", "BABBA", "BABBB", "BBAAA", "BBAAB"};
+        char letter = 'A';
+        for (String code : baconianAlphabet) {
+            BACONIAN_MAP.put(letter, code);
+            REVERSE_BACONIAN_MAP.put(code, letter);
+            letter++;
+        }
+
+        // Handle I/J as the same letter
+        BACONIAN_MAP.put('I', BACONIAN_MAP.get('J'));
+        REVERSE_BACONIAN_MAP.put(BACONIAN_MAP.get('I'), 'I');
+    }
+
+    /**
+     * Encrypts the given plaintext using the Baconian cipher.
+     *
+     * @param plaintext The plaintext message to encrypt.
+     * @return The ciphertext as a binary (A/B) sequence.
+     */
+    public String encrypt(String plaintext) {
+        StringBuilder ciphertext = new StringBuilder();
+        plaintext = plaintext.toUpperCase().replaceAll("[^A-Z]", ""); // Remove non-letter characters
+
+        for (char letter : plaintext.toCharArray()) {
+            ciphertext.append(BACONIAN_MAP.get(letter));
+        }
+
+        return ciphertext.toString();
+    }
+
+    /**
+     * Decrypts the given ciphertext encoded in binary (A/B) format using the Baconian cipher.
+     *
+     * @param ciphertext The ciphertext to decrypt.
+     * @return The decrypted plaintext message.
+     */
+    public String decrypt(String ciphertext) {
+        StringBuilder plaintext = new StringBuilder();
+
+        for (int i = 0; i < ciphertext.length(); i += 5) {
+            String code = ciphertext.substring(i, i + 5);
+            if (REVERSE_BACONIAN_MAP.containsKey(code)) {
+                plaintext.append(REVERSE_BACONIAN_MAP.get(code));
+            } else {
+                throw new IllegalArgumentException("Invalid Baconian code: " + code);
+            }
+        }
+
+        return plaintext.toString();
+    }
+}

src/main/java/com/thealgorithms/ciphers/BaconianCipher.java

@@ -0,0 +1,36 @@
+package com.thealgorithms.ciphers;
+
+import java.math.BigInteger;
+
+public final class DiffieHellman {
+
+    private final BigInteger base;
+    private final BigInteger secret;
+    private final BigInteger prime;
+
+    // Constructor to initialize base, secret, and prime
+    public DiffieHellman(BigInteger base, BigInteger secret, BigInteger prime) {
+        // Check for non-null and positive values
+        if (base == null || secret == null || prime == null || base.signum() <= 0 || secret.signum() <= 0 || prime.signum() <= 0) {
+            throw new IllegalArgumentException("Base, secret, and prime must be non-null and positive values.");
+        }
+        this.base = base;
+        this.secret = secret;
+        this.prime = prime;
+    }
+
+    // Method to calculate public value (g^x mod p)
+    public BigInteger calculatePublicValue() {
+        // Returns g^x mod p
+        return base.modPow(secret, prime);
+    }
+
+    // Method to calculate the shared secret key (otherPublic^secret mod p)
+    public BigInteger calculateSharedSecret(BigInteger otherPublicValue) {
+        if (otherPublicValue == null || otherPublicValue.signum() <= 0) {
+            throw new IllegalArgumentException("Other public value must be non-null and positive.");
+        }
+        // Returns b^x mod p or a^y mod p
+        return otherPublicValue.modPow(secret, prime);
+    }
+}