feat: Add Xs3Conversion algo with JUnit tests

DIRECTORY.md

@@ -47,6 +47,7 @@
             * [SingleElement](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/bitmanipulation/SingleElement.java)
             * [SwapAdjacentBits](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/bitmanipulation/SwapAdjacentBits.java)
             * [TwosComplement](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/bitmanipulation/TwosComplement.java)
+            * [Xs3Conversion](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/bitmanipulation/Xs3Conversion.java)
           * ciphers
             * a5
               * [A5Cipher](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/ciphers/a5/A5Cipher.java)
@@ -679,6 +680,7 @@
             * [SingleElementTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/bitmanipulation/SingleElementTest.java)
             * [SwapAdjacentBitsTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/bitmanipulation/SwapAdjacentBitsTest.java)
             * [TwosComplementTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/bitmanipulation/TwosComplementTest.java)
+            * [Xs3ConversionTest](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/bitmanipulation/Xs3ConversionTest.java)
           * ciphers
             * a5
               * [A5CipherTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/ciphers/a5/A5CipherTest.java)

src/main/java/com/thealgorithms/bitmanipulation/Xs3Conversion.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/test/java/com/thealgorithms/bitmanipulation/Xs3ConversionTest.java

@@ -0,0 +1,65 @@
+package com.thealgorithms.bitmanipulation;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Unit tests for the Xs3Conversion class.
+ */
+public class Xs3ConversionTest {
+
+    /**
+     * Test the xs3ToBinary method with an XS-3 number.
+     */
+    @Test
+    public void testXs3ToBinary() {
+        int binary = Xs3Conversion.xs3ToBinary(0x4567);
+        assertEquals(1234, binary); // XS-3 0x4567 should convert to binary 1234
+    }
+
+    /**
+     * Test the binaryToXs3 method with a binary number.
+     */
+    @Test
+    public void testBinaryToXs3() {
+        int xs3 = Xs3Conversion.binaryToXs3(1234);
+        assertEquals(0x4567, xs3); // Binary 1234 should convert to XS-3 0x4567
+    }
+
+    /**
+     * Test the xs3ToBinary method with zero.
+     */
+    @Test
+    public void testXs3ToBinaryZero() {
+        int binary = Xs3Conversion.xs3ToBinary(0x0);
+        assertEquals(0, binary); // XS-3 0x0 should convert to binary 0
+    }
+
+    /**
+     * Test the binaryToXs3 method with zero.
+     */
+    @Test
+    public void testBinaryToXs3Zero() {
+        int xs3 = Xs3Conversion.binaryToXs3(0);
+        assertEquals(0x0, xs3); // Binary 0 should convert to XS-3 0x0
+    }
+
+    /**
+     * Test the xs3ToBinary method with a single digit XS-3 number.
+     */
+    @Test
+    public void testXs3ToBinarySingleDigit() {
+        int binary = Xs3Conversion.xs3ToBinary(0x5);
+        assertEquals(2, binary); // XS-3 0x5 should convert to binary 2
+    }
+
+    /**
+     * Test the binaryToXs3 method with a single digit binary number.
+     */
+    @Test
+    public void testBinaryToXs3SingleDigit() {
+        int xs3 = Xs3Conversion.binaryToXs3(2);
+        assertEquals(0x5, xs3); // Binary 2 should convert to XS-3 0x5
+    }
+}