Added putValue and getValue to allow for optimal compression.

Author: jhg023

pom.xml

@@ -12,7 +12,7 @@
 
     <groupId>com.github.jhg023</groupId>
     <artifactId>BitBuffer</artifactId>
-    <version>1.0.0</version>
+    <version>1.0.1</version>
     <packaging>jar</packaging>
 
     <name>BitBuffer</name>

src/main/java/bitbuffer/BitBuffer.java

@@ -285,7 +285,32 @@ public BitBuffer putShort(int s, ByteOrder order) {
         var value = (short) s;
         return putBits(order == ByteOrder.BIG_ENDIAN ? Short.reverseBytes(value) : value, Short.SIZE);
     }
-
+    
+    /**
+     * Given the specified {@code maxValue}, this method writes the specified value to this {@link BitBuffer}
+     * using the optimal amount of bits, thus providing free compression.
+     *
+     * @param value    the value to write to this {@link BitBuffer}.
+     * @param maxValue the maximum possible value that {@code value} can be; a lower {@code maxValue} results in a
+     *                 better compression ratio.
+     * @return this {@link BitBuffer} to allow for the convenience of method-chaining.
+     * @throws IllegalArgumentException if {@code maxValue} is negative or if the absolute value of {@code value} is
+     * greater than {@code maxValue}.
+     */
+    public BitBuffer putValue(long value, long maxValue) throws IllegalArgumentException {
+        if (maxValue < 0) {
+            throw new IllegalArgumentException("maxValue must be positive!");
+        }
+        
+        if (Math.abs(value) > maxValue) {
+            throw new IllegalArgumentException("value must be less than or equal to maxValue!");
+        }
+        
+        int numBits = Long.SIZE - Long.numberOfLeadingZeros(maxValue) + 1;
+        
+        return putBits(value, numBits);
+    }
+    
     /**
      * After a series of relative {@code put} operations, flip the <i>cache</i> to prepare for a series of relative
      * {@code get} operations.
@@ -499,6 +524,28 @@ public short getShort(ByteOrder order) {
         return order == ByteOrder.BIG_ENDIAN ? Short.reverseBytes(value) : value;
     }
 
+    /**
+     * Given the specified {@code maxValue}, this method reads a value from this {@link BitBuffer} using the optimal
+     * amount of bits, thus providing free compression.
+     * <br><br>
+     * The value of {@code maxValue} should be the same as what was used when calling {@link #putValue(long, long)}.
+     *
+     * @param maxValue the maximum possible value that the value being read can be; a lower {@code maxValue} results
+     *                 in a better compression ratio.
+     * @return the value read from this {@link BitBuffer} as a {@code long}.
+     * @throws IllegalArgumentException if {@code maxValue} is negative.
+     */
+    public long getValue(long maxValue) {
+        if (maxValue < 0) {
+            throw new IllegalArgumentException("maxValue must be positive!");
+        }
+        
+        int numBits = Long.SIZE - Long.numberOfLeadingZeros(maxValue) + 1;
+        int unused = Long.SIZE - numBits;
+        
+        return getBits(numBits) << unused >> unused;
+    }
+    
     /**
      * Gets the capacity of the backing {@link ByteBuffer}.
      *

src/test/java/bitbuffer/BitBufferTests.java

@@ -115,6 +115,13 @@ void testReadDoubleLittleEndian(double value) {
                 .flip().getDouble(ByteOrder.LITTLE_ENDIAN));
     }
 
+    @ParameterizedTest
+    @ValueSource(longs = {Long.MIN_VALUE, -10L, -1L, 0L, 1L, 10L, Long.MAX_VALUE})
+    void testReadValue(long value) {
+        Assertions.assertEquals(value, buffer.putValue(value, Long.MAX_VALUE)
+                .flip().getValue(Long.MAX_VALUE));
+    }
+    
     /**
      * This method tests whether the {@code long} cache is cleared properly.
      */
@@ -124,6 +131,8 @@ void testDoubleFlip() {
         Assertions.assertEquals(42, buffer.getInt());
         buffer.flip();
         buffer.flip();
+        buffer.flip();
+        buffer.flip();
         Assertions.assertEquals(26, buffer.getInt());
     }