Merge branch 'master' into reverse_stack_improve

Author: Hardvan

DIRECTORY.md

@@ -100,6 +100,7 @@
             * [IntegerToEnglish](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/conversions/IntegerToEnglish.java)
             * [IntegerToRoman](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/conversions/IntegerToRoman.java)
             * [IPConverter](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/conversions/IPConverter.java)
+            * [IPv6Converter](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/conversions/IPv6Converter.java)
             * [MorseCodeConverter](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/conversions/MorseCodeConverter.java)
             * [OctalToBinary](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/conversions/OctalToBinary.java)
             * [OctalToDecimal](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/conversions/OctalToDecimal.java)
@@ -784,6 +785,7 @@
             * [IntegerToEnglishTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/conversions/IntegerToEnglishTest.java)
             * [IntegerToRomanTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/conversions/IntegerToRomanTest.java)
             * [IPConverterTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/conversions/IPConverterTest.java)
+            * [IPv6ConverterTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/conversions/IPv6ConverterTest.java)
             * [MorseCodeConverterTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/conversions/MorseCodeConverterTest.java)
             * [OctalToBinaryTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/conversions/OctalToBinaryTest.java)
             * [OctalToDecimalTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/conversions/OctalToDecimalTest.java)

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

@@ -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/NonRepeatingNumberFinder.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/NumberAppearingOddTimes.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/NumbersDifferentSigns.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/conversions/IPv6Converter.java

@@ -0,0 +1,98 @@
+package com.thealgorithms.conversions;
+
+import java.net.InetAddress;
+import java.net.UnknownHostException;
+import java.util.Arrays;
+
+/**
+ * A utility class for converting between IPv6 and IPv4 addresses.
+ *
+ * - Converts IPv4 to IPv6-mapped IPv6 address.
+ * - Extracts IPv4 address from IPv6-mapped IPv6.
+ * - Handles exceptions for invalid inputs.
+ *
+ * @author Hardvan
+ */
+public final class IPv6Converter {
+    private IPv6Converter() {
+    }
+
+    /**
+     * Converts an IPv4 address (e.g., "192.0.2.128") to an IPv6-mapped IPv6 address.
+     * Example: IPv4 "192.0.2.128" -> IPv6 "::ffff:192.0.2.128"
+     *
+     * @param ipv4Address The IPv4 address in string format.
+     * @return The corresponding IPv6-mapped IPv6 address.
+     * @throws UnknownHostException If the IPv4 address is invalid.
+     * @throws IllegalArgumentException If the IPv6 address is not a mapped IPv4 address.
+     */
+    public static String ipv4ToIpv6(String ipv4Address) throws UnknownHostException {
+        if (ipv4Address == null || ipv4Address.isEmpty()) {
+            throw new UnknownHostException("IPv4 address is empty.");
+        }
+
+        InetAddress ipv4 = InetAddress.getByName(ipv4Address);
+        byte[] ipv4Bytes = ipv4.getAddress();
+
+        // Create IPv6-mapped IPv6 address (starts with ::ffff:)
+        byte[] ipv6Bytes = new byte[16];
+        ipv6Bytes[10] = (byte) 0xff;
+        ipv6Bytes[11] = (byte) 0xff;
+        System.arraycopy(ipv4Bytes, 0, ipv6Bytes, 12, 4);
+
+        // Manually format to "::ffff:x.x.x.x" format
+        StringBuilder ipv6String = new StringBuilder("::ffff:");
+        for (int i = 12; i < 16; i++) {
+            ipv6String.append(ipv6Bytes[i] & 0xFF);
+            if (i < 15) {
+                ipv6String.append('.');
+            }
+        }
+        return ipv6String.toString();
+    }
+
+    /**
+     * Extracts the IPv4 address from an IPv6-mapped IPv6 address.
+     * Example: IPv6 "::ffff:192.0.2.128" -> IPv4 "192.0.2.128"
+     *
+     * @param ipv6Address The IPv6 address in string format.
+     * @return The extracted IPv4 address.
+     * @throws UnknownHostException If the IPv6 address is invalid or not a mapped IPv4 address.
+     */
+    public static String ipv6ToIpv4(String ipv6Address) throws UnknownHostException {
+        InetAddress ipv6 = InetAddress.getByName(ipv6Address);
+        byte[] ipv6Bytes = ipv6.getAddress();
+
+        // Check if the address is an IPv6-mapped IPv4 address
+        if (isValidIpv6MappedIpv4(ipv6Bytes)) {
+            byte[] ipv4Bytes = Arrays.copyOfRange(ipv6Bytes, 12, 16);
+            InetAddress ipv4 = InetAddress.getByAddress(ipv4Bytes);
+            return ipv4.getHostAddress();
+        } else {
+            throw new IllegalArgumentException("Not a valid IPv6-mapped IPv4 address.");
+        }
+    }
+
+    /**
+     * Helper function to check if the given byte array represents
+     * an IPv6-mapped IPv4 address (prefix 0:0:0:0:0:ffff).
+     *
+     * @param ipv6Bytes Byte array representation of the IPv6 address.
+     * @return True if the address is IPv6-mapped IPv4, otherwise false.
+     */
+    private static boolean isValidIpv6MappedIpv4(byte[] ipv6Bytes) {
+        // IPv6-mapped IPv4 addresses are 16 bytes long, with the first 10 bytes set to 0,
+        // followed by 0xff, 0xff, and the last 4 bytes representing the IPv4 address.
+        if (ipv6Bytes.length != 16) {
+            return false;
+        }
+
+        for (int i = 0; i < 10; i++) {
+            if (ipv6Bytes[i] != 0) {
+                return false;
+            }
+        }
+
+        return ipv6Bytes[10] == (byte) 0xff && ipv6Bytes[11] == (byte) 0xff;
+    }
+}

src/test/java/com/thealgorithms/bitmanipulation/IsPowerTwoTest.java

@@ -3,33 +3,49 @@
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
-import org.junit.jupiter.api.Test;
+import java.util.stream.Stream;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
 
 /**
  * Test case for IsPowerTwo class
  * @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
  */
 
 public class IsPowerTwoTest {
-    @Test
-    public void testIsPowerTwo() {
-        // test some positive powers of 2
-        assertTrue(IsPowerTwo.isPowerTwo(1));
-        assertTrue(IsPowerTwo.isPowerTwo(2));
-        assertTrue(IsPowerTwo.isPowerTwo(4));
-        assertTrue(IsPowerTwo.isPowerTwo(16));
-        assertTrue(IsPowerTwo.isPowerTwo(1024));
 
-        // test some negative numbers
-        assertFalse(IsPowerTwo.isPowerTwo(-1));
-        assertFalse(IsPowerTwo.isPowerTwo(-2));
-        assertFalse(IsPowerTwo.isPowerTwo(-4));
+    @ParameterizedTest
+    @MethodSource("provideNumbersForPowerTwo")
+    public void testIsPowerTwo(int number, boolean expected) {
+        if (expected) {
+            assertTrue(IsPowerTwo.isPowerTwo(number));
+        } else {
+            assertFalse(IsPowerTwo.isPowerTwo(number));
+        }
+    }
 
-        // test some numbers that are not powers of 2
-        assertFalse(IsPowerTwo.isPowerTwo(0));
-        assertFalse(IsPowerTwo.isPowerTwo(3));
-        assertFalse(IsPowerTwo.isPowerTwo(5));
-        assertFalse(IsPowerTwo.isPowerTwo(15));
-        assertFalse(IsPowerTwo.isPowerTwo(1000));
+    private static Stream<Arguments> provideNumbersForPowerTwo() {
+        return Stream.of(Arguments.of(1, Boolean.TRUE), // 2^0
+            Arguments.of(2, Boolean.TRUE), // 2^1
+            Arguments.of(4, Boolean.TRUE), // 2^2
+            Arguments.of(8, Boolean.TRUE), // 2^3
+            Arguments.of(16, Boolean.TRUE), // 2^4
+            Arguments.of(32, Boolean.TRUE), // 2^5
+            Arguments.of(64, Boolean.TRUE), // 2^6
+            Arguments.of(128, Boolean.TRUE), // 2^7
+            Arguments.of(256, Boolean.TRUE), // 2^8
+            Arguments.of(1024, Boolean.TRUE), // 2^10
+            Arguments.of(0, Boolean.FALSE), // 0 is not a power of two
+            Arguments.of(-1, Boolean.FALSE), // Negative number
+            Arguments.of(-2, Boolean.FALSE), // Negative number
+            Arguments.of(-4, Boolean.FALSE), // Negative number
+            Arguments.of(3, Boolean.FALSE), // 3 is not a power of two
+            Arguments.of(5, Boolean.FALSE), // 5 is not a power of two
+            Arguments.of(6, Boolean.FALSE), // 6 is not a power of two
+            Arguments.of(15, Boolean.FALSE), // 15 is not a power of two
+            Arguments.of(1000, Boolean.FALSE), // 1000 is not a power of two
+            Arguments.of(1023, Boolean.FALSE) // 1023 is not a power of two
+        );
     }
 }

src/test/java/com/thealgorithms/bitmanipulation/NonRepeatingNumberFinderTest.java

@@ -2,22 +2,35 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
-import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
 
 /**
  * Test case for Non Repeating Number Finder
+ * This test class validates the functionality of the
+ * NonRepeatingNumberFinder by checking various scenarios.
+ *
  * @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
  */
-
 class NonRepeatingNumberFinderTest {
 
-    @Test
-    void testNonRepeatingNumberFinder() {
-        int[] arr = {1, 2, 1, 2, 6};
-        assertEquals(6, NonRepeatingNumberFinder.findNonRepeatingNumber(arr));
-        int[] arr1 = {1, 2, 1, 2};
-        assertEquals(0, NonRepeatingNumberFinder.findNonRepeatingNumber(arr1));
-        int[] arr2 = {12};
-        assertEquals(12, NonRepeatingNumberFinder.findNonRepeatingNumber(arr2));
+    @ParameterizedTest
+    @MethodSource("testCases")
+    void testNonRepeatingNumberFinder(int[] arr, int expected) {
+        assertEquals(expected, NonRepeatingNumberFinder.findNonRepeatingNumber(arr));
+    }
+
+    private static Arguments[] testCases() {
+        return new Arguments[] {
+            Arguments.of(new int[] {1, 2, 1, 2, 6}, 6), Arguments.of(new int[] {1, 2, 1, 2}, 0), // All numbers repeat
+            Arguments.of(new int[] {12}, 12), // Single non-repeating number
+            Arguments.of(new int[] {3, 5, 3, 4, 4}, 5), // More complex case
+            Arguments.of(new int[] {7, 8, 7, 9, 8, 10, 10}, 9), // Non-repeating in the middle
+            Arguments.of(new int[] {0, -1, 0, -1, 2}, 2), // Testing with negative numbers
+            Arguments.of(new int[] {Integer.MAX_VALUE, 1, 1}, Integer.MAX_VALUE), // Edge case with max int
+            Arguments.of(new int[] {2, 2, 3, 3, 4, 5, 4}, 5), // Mixed duplicates
+            Arguments.of(new int[] {}, 0) // Edge case: empty array (should be handled as per design)
+        };
     }
 }