feat(bitpacker): implement BitPacker class for bit manipulation and packing

Author: xt0x

src/main/java/com/example/bip39/bit/BitPacker.java

@@ -0,0 +1,107 @@
+package com.example.bip39.bit;
+
+import java.util.Objects;
+
+public final class BitPacker {
+
+  private static final int ELEVEN_BIT_GROUP_SIZE = 11;
+
+  private BitPacker() {}
+
+  public static int readBits(byte[] source, int bitOffset, int bitLength) {
+    Objects.requireNonNull(source, "source must not be null");
+    validateBitAccess(source.length, bitOffset, bitLength);
+    if (bitLength > Integer.SIZE - 1) {
+      throw new IllegalArgumentException("bitLength must be at most 31");
+    }
+
+    int value = 0;
+    for (int bitIndex = 0; bitIndex < bitLength; bitIndex++) {
+      int absoluteBitIndex = bitOffset + bitIndex;
+      int byteIndex = absoluteBitIndex / Byte.SIZE;
+      int bitIndexInByte = 7 - (absoluteBitIndex % Byte.SIZE);
+      int bit = ((source[byteIndex] & 0xff) >> bitIndexInByte) & 0x01;
+      value = (value << 1) | bit;
+    }
+    return value;
+  }
+
+  public static void writeBits(byte[] target, int bitOffset, int bitLength, int value) {
+    Objects.requireNonNull(target, "target must not be null");
+    validateBitAccess(target.length, bitOffset, bitLength);
+    if (bitLength > Integer.SIZE - 1) {
+      throw new IllegalArgumentException("bitLength must be at most 31");
+    }
+    if (bitLength != 0 && value >>> bitLength != 0) {
+      throw new IllegalArgumentException("value does not fit into the requested bit length");
+    }
+
+    for (int bitIndex = 0; bitIndex < bitLength; bitIndex++) {
+      int absoluteBitIndex = bitOffset + bitIndex;
+      int byteIndex = absoluteBitIndex / Byte.SIZE;
+      int bitIndexInByte = 7 - (absoluteBitIndex % Byte.SIZE);
+      int bitMask = 1 << bitIndexInByte;
+      int bit = (value >> (bitLength - 1 - bitIndex)) & 0x01;
+      int clearedByte = target[byteIndex] & ~bitMask;
+      target[byteIndex] = (byte) (clearedByte | (bit << bitIndexInByte));
+    }
+  }
+
+  public static int[] splitTo11BitValues(byte[] source, int totalBitLength) {
+    Objects.requireNonNull(source, "source must not be null");
+    validateTotalBitLength(source.length, totalBitLength);
+    if (totalBitLength % ELEVEN_BIT_GROUP_SIZE != 0) {
+      throw new IllegalArgumentException("totalBitLength must be divisible by 11");
+    }
+
+    int[] values = new int[totalBitLength / ELEVEN_BIT_GROUP_SIZE];
+    for (int valueIndex = 0; valueIndex < values.length; valueIndex++) {
+      values[valueIndex] =
+          readBits(source, valueIndex * ELEVEN_BIT_GROUP_SIZE, ELEVEN_BIT_GROUP_SIZE);
+    }
+    return values;
+  }
+
+  public static byte[] pack11BitValues(int[] values) {
+    Objects.requireNonNull(values, "values must not be null");
+    byte[] packed = new byte[(values.length * ELEVEN_BIT_GROUP_SIZE + 7) / Byte.SIZE];
+    for (int valueIndex = 0; valueIndex < values.length; valueIndex++) {
+      int value = values[valueIndex];
+      if (value < 0 || value > 0x7ff) {
+        throw new IllegalArgumentException("11-bit value out of range: " + value);
+      }
+      writeBits(packed, valueIndex * ELEVEN_BIT_GROUP_SIZE, ELEVEN_BIT_GROUP_SIZE, value);
+    }
+    return packed;
+  }
+
+  public static byte[] extractBytes(byte[] source, int bitOffset, int bitLength) {
+    Objects.requireNonNull(source, "source must not be null");
+    validateBitAccess(source.length, bitOffset, bitLength);
+    if (bitLength % Byte.SIZE != 0) {
+      throw new IllegalArgumentException("bitLength must be divisible by 8");
+    }
+
+    byte[] bytes = new byte[bitLength / Byte.SIZE];
+    for (int byteIndex = 0; byteIndex < bytes.length; byteIndex++) {
+      bytes[byteIndex] = (byte) readBits(source, bitOffset + byteIndex * Byte.SIZE, Byte.SIZE);
+    }
+    return bytes;
+  }
+
+  private static void validateTotalBitLength(int sourceLengthBytes, int totalBitLength) {
+    validateBitAccess(sourceLengthBytes, 0, totalBitLength);
+  }
+
+  private static void validateBitAccess(int sourceLengthBytes, int bitOffset, int bitLength) {
+    if (bitOffset < 0) {
+      throw new IllegalArgumentException("bitOffset must not be negative");
+    }
+    if (bitLength < 0) {
+      throw new IllegalArgumentException("bitLength must not be negative");
+    }
+    if (bitOffset + bitLength > sourceLengthBytes * Byte.SIZE) {
+      throw new IllegalArgumentException("Requested bits exceed source length");
+    }
+  }
+}

src/test/java/com/example/bip39/bit/BitPackerTest.java

@@ -0,0 +1,74 @@
+package com.example.bip39.bit;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import org.junit.jupiter.api.Test;
+
+class BitPackerTest {
+
+  @Test
+  void readsBitsMostSignificantBitFirstFromSignedBytes() {
+    byte[] source = {(byte) 0x80, (byte) 0xf1};
+
+    assertEquals(1, BitPacker.readBits(source, 0, 1));
+    assertEquals(0, BitPacker.readBits(source, 1, 7));
+    assertEquals(0xf1, BitPacker.readBits(source, 8, 8));
+    assertEquals(0x01, BitPacker.readBits(source, 12, 4));
+  }
+
+  @Test
+  void writesBitsAndExtractsBytesWithoutLosingUnsignedValues() {
+    byte[] target = new byte[3];
+
+    BitPacker.writeBits(target, 0, 8, 0x80);
+    BitPacker.writeBits(target, 8, 8, 0x01);
+    BitPacker.writeBits(target, 16, 8, 0xff);
+
+    assertArrayEquals(new byte[] {(byte) 0x80, 0x01, (byte) 0xff}, target);
+    assertArrayEquals(target, BitPacker.extractBytes(target, 0, 24));
+  }
+
+  @Test
+  void extractsBytesAcrossByteBoundaries() {
+    byte[] source = {0x12, 0x34, 0x56};
+
+    assertArrayEquals(new byte[] {0x23, 0x45}, BitPacker.extractBytes(source, 4, 16));
+  }
+
+  @Test
+  void splitsKnownBitSequenceIntoElevenBitValues() {
+    byte[] source = {0x12, 0x34, 0x56};
+
+    assertArrayEquals(new int[] {145, 1301}, BitPacker.splitTo11BitValues(source, 22));
+  }
+
+  @Test
+  void packsElevenBitValuesInMostSignificantBitOrder() {
+    assertArrayEquals(
+        new byte[] {0x12, 0x34, 0x54}, BitPacker.pack11BitValues(new int[] {145, 1301}));
+  }
+
+  @Test
+  void elevenBitPackingAndSplittingRoundTrips() {
+    int[] values = {0, 1, 1024, 2047, 42};
+
+    byte[] packed = BitPacker.pack11BitValues(values);
+
+    assertArrayEquals(values, BitPacker.splitTo11BitValues(packed, values.length * 11));
+  }
+
+  @Test
+  void rejectsInvalidBitAccessAndOutOfRangeValues() {
+    byte[] source = new byte[2];
+
+    assertThrows(IllegalArgumentException.class, () -> BitPacker.readBits(source, -1, 1));
+    assertThrows(IllegalArgumentException.class, () -> BitPacker.readBits(source, 0, 17));
+    assertThrows(IllegalArgumentException.class, () -> BitPacker.writeBits(source, 0, 3, 0b1000));
+    assertThrows(
+        IllegalArgumentException.class, () -> BitPacker.splitTo11BitValues(source, Byte.SIZE));
+    assertThrows(IllegalArgumentException.class, () -> BitPacker.pack11BitValues(new int[] {2048}));
+    assertThrows(IllegalArgumentException.class, () -> BitPacker.extractBytes(source, 0, 7));
+  }
+}