Add binary and base64 serialization to BitSet (#8)

Author: frankdekker

src/Util/BitSet.php

@@ -5,6 +5,7 @@
 
 namespace DR\JBDiff\Util;
 
+use InvalidArgumentException;
 use Stringable;
 
 class BitSet implements Stringable
@@ -83,6 +84,71 @@ public function __unserialize(array $data): void
         $this->words = $data;
     }
 
+    /**
+     * Convert the BitSet to binary string, which can be turned into BitSet again via @see BitSet::fromBinaryString. Note: this method
+     * is not compatible between 32-bit and 64-bit systems.
+     */
+    public function toBinaryString(): string
+    {
+        if (count($this->words) === 0) {
+            return '';
+        }
+
+        $words = [];
+
+        // ensure all slots between 0 and maxKey have a value
+        $maxKey = max(...array_keys($this->words));
+        for ($i = 0; $i <= $maxKey; $i++) {
+            $words[$i] = $this->words[$i] ?? 0;
+        }
+
+        return pack(PHP_INT_SIZE === 4 ? 'N*' : 'J*', ...$words);
+    }
+
+    /**
+     * Convert the BitSet to base64 encode binary string, which can be turned into BitSet again via @see BitSet::fromBase64String. Note: this method
+     * is not compatible between 32-bit and 64-bit systems.
+     */
+    public function toBase64String(): string
+    {
+        return base64_encode($this->toBinaryString());
+    }
+
+    public static function fromBinaryString(string $data): BitSet
+    {
+        $bitSet = new BitSet();
+
+        if ($data === '') {
+            return $bitSet;
+        }
+
+        $words = unpack(PHP_INT_SIZE === 4 ? 'N*' : 'J*', $data);
+        if ($words === false || count($words) === 0) {
+            throw new InvalidArgumentException('Unable to unpack from binary string: ' . base64_encode($data));
+        }
+
+        // cleanup all keys where value = 0;
+        $index = 0;
+        foreach ($words as $value) {
+            if ($value !== 0) {
+                $bitSet->words[$index] = $value;
+            }
+            ++$index;
+        }
+
+        return $bitSet;
+    }
+
+    public static function fromBase64String(string $data): BitSet
+    {
+        $decoded = base64_decode($data, true);
+        if ($decoded === false) {
+            throw new InvalidArgumentException('Unable to decode base64 string: ' . $data);
+        }
+
+        return self::fromBinaryString($decoded);
+    }
+
     /**
      * @return array<int, int>
      */

tests/Unit/Util/BitSetTest.php

@@ -5,6 +5,7 @@
 
 use AssertionError;
 use DR\JBDiff\Util\BitSet;
+use InvalidArgumentException;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\TestCase;
 
@@ -129,4 +130,51 @@ public function testSerialize(): void
 
         static::assertEquals($bitSet, $newBitSet);
     }
+
+    public function testSerializeBinaryString(): void
+    {
+        $bitSet = new BitSet();
+        $bitSet->set(0, 500);
+
+        $binaryString = $bitSet->toBinaryString();
+        $newBitSet    = BitSet::fromBinaryString($binaryString);
+
+        static::assertEquals($bitSet, $newBitSet);
+    }
+
+    public function testSerializeBinaryStringEmptyBitSet(): void
+    {
+        $bitSet = new BitSet();
+
+        $binaryString = $bitSet->toBinaryString();
+        $newBitSet    = BitSet::fromBinaryString($binaryString);
+
+        static::assertEquals($bitSet, $newBitSet);
+    }
+
+    public function testSerializeBinaryStringUnpackFailure(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unable to unpack from binary string');
+        BitSet::fromBinaryString("\x01\x02");
+    }
+
+    public function testSerializeBase64String(): void
+    {
+        $bitSet = new BitSet();
+        $bitSet->set(5, 6);
+        $bitSet->set(200, 201);
+
+        $base64String = $bitSet->toBase64String();
+        $newBitSet    = BitSet::fromBase64String($base64String);
+
+        static::assertEquals($bitSet, $newBitSet);
+    }
+
+    public function testInvalidBase64String(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unable to decode base64 string: ##');
+        BitSet::fromBase64String('##');
+    }
 }