Squash sketch

Author: Jin Kwon

README.md

@@ -1,6 +1,7 @@
 # bit-io2
 
 ![Java CI with Maven](https://github.com/jinahya/bit-io2/workflows/Java%20CI%20with%20Maven/badge.svg)
+![Maven Central](https://img.shields.io/maven-central/v/com.github.jinahya/bit-io2)
 [![javadoc](https://javadoc.io/badge2/com.github.jinahya/bit-io2/javadoc.svg)](https://javadoc.io/doc/com.github.jinahya/bit-io2)
 
 A Java 8+ flavored version of [bit-io](https://github.com/jinahya/bit-io).
@@ -40,6 +41,4 @@ CLIENT write-> BitOutput(Adapter)
                                                       ...
 ```
 
-Each `...Adapter` class accepts an instance of `Supplier<? extends T>` which means any byte sources/targets can be lazily initialized only when some bits are read or written.
-
 See [Specifications](https://github.com/jinahya/bit-io2/wiki/Specifications) and [Recipes](https://github.com/jinahya/bit-io2/wiki/Recipes) for more information.

docker.maven.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 # https://stackoverflow.com/questions/3545292/how-to-get-maven-project-version-to-the-bash-command-line
-if [ $# -lt 3 ]; then
+if [ $# -lt 2 ]; then
   echo "Usage: $0 <tag> <phases...>, e.g. $0 3-jdk-11-openj9 clean install"
   echo "See https://hub.docker.com/_/maven for available tags"
   exit 1

pom.xml

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
 
   <parent>
@@ -178,7 +179,7 @@
             </goals>
             <configuration>
               <rules>
-                <dependencyConvergence />
+                <dependencyConvergence/>
                 <requireJavaVersion>
                   <version>[1.8.0,)</version>
                 </requireJavaVersion>

src/main/java/com/github/jinahya/bit/io/BitInput.java

@@ -20,6 +20,7 @@
  * #L%
  */
 
+import java.io.Closeable;
 import java.io.IOException;
 
 import static com.github.jinahya.bit.io.BitIoConstraints.requireValidSizeForByte;
@@ -29,22 +30,33 @@
 import static java.lang.Double.longBitsToDouble;
 import static java.lang.Float.intBitsToFloat;
 import static java.util.Objects.requireNonNull;
+import static java.util.concurrent.ThreadLocalRandom.current;
 
 /**
  * An interface for reading values of an arbitrary number of bits.
  *
  * @author Jin Kwon <jinahya_at_gmail.com>
  * @see BitOutput
  */
-public interface BitInput {
+public interface BitInput extends Closeable {
 
     /**
-     * Reads a {@code 1}-bit {@code boolean} value. This method reads a {@code 1}-bit unsigned {@code int} and returns
-     * {@code true} for {@code 0b1} and {@code false} for {@code 0b0}.
+     * Closes this input and releases any system resources associated with it. The {@code close} method of {@code
+     * BitInput} interface does nothing.
      *
-     * @return {@code true} for {@code 0b1}, {@code false} for {@code 0b0}
      * @throws IOException if an I/O error occurs.
-     * @see BitOutput#writeBoolean(boolean)
+     */
+    @Override
+    default void close() throws IOException {
+        // does nothing.
+    }
+
+    /**
+     * Reads a {@code 1}-bit {@code boolean} value. This method reads a {@code 1}-bit unsigned {@code int} value and
+     * returns {@code true} for {@code 0b1} and {@code false} for {@code 0b0}.
+     *
+     * @return the value read.
+     * @throws IOException if an I/O error occurs.
      */
     default boolean readBoolean() throws IOException {
         return readInt(true, 1) == 0x01;
@@ -54,9 +66,9 @@ default boolean readBoolean() throws IOException {
      * Reads a {@code byte} value of specified number of bits.
      *
      * @param unsigned a flag for indicating unsigned value; {@code true} for unsigned, {@code false} for signed.
-     * @param size     the number of bits to read; between {@code 1} and ({@value java.lang.Byte#SIZE} - (unsigned ?
-     *                 {@code 1} : {@code 0})), both inclusive.
-     * @return a {@code byte} value of specified {@code size}.
+     * @param size     the number of bits to read; between {@code 1} and ({@value java.lang.Byte#SIZE} - ({@code
+     *                 unsigned ? 1 : 0})), both inclusive.
+     * @return a {@code byte} value of specified bit {@code size}.
      * @throws IOException if an I/O error occurs.
      */
     default byte readByte(final boolean unsigned, final int size) throws IOException {
@@ -75,7 +87,7 @@ default byte readByte(final int size) throws IOException {
     }
 
     /**
-     * Reads a signed {@value java.lang.Byte#SIZE}-bit {@code byte} value.
+     * Reads a {@value java.lang.Byte#SIZE}-bit signed {@code byte} value.
      *
      * @return a signed {@value java.lang.Byte#SIZE}-bit {@code byte} value.
      * @throws IOException if an I/O error occurs.
@@ -121,9 +133,9 @@ default short readShort(final int size) throws IOException {
     }
 
     /**
-     * Reads a signed {@value java.lang.Short#SIZE}-bit {@code short} value.
+     * Reads a {@value java.lang.Short#SIZE}-bit signed {@code short} value.
      *
-     * @return a signed {@value java.lang.Short#SIZE}-bit {@code short} value.
+     * @return a {@value java.lang.Short#SIZE}-bit signed {@code short} value read.
      * @throws IOException if an I/O error occurs.
      * @see #readShort(int)
      */
@@ -132,12 +144,18 @@ default short readShort16() throws IOException {
     }
 
     /**
-     * Reads a signed {@value java.lang.Short#SIZE}-bit {@code short} value in little endian byte order.
+     * Reads a {@value java.lang.Short#SIZE}-bit signed {@code short} value in little endian byte order.
      *
-     * @return a signed {@value java.lang.Short#SIZE}-bit {@code short} value in little endian byte order.
+     * @return a {@value java.lang.Short#SIZE}-bit signed {@code short} value read in little endian byte order.
      * @throws IOException if an I/O error occurs.
+     * @deprecated Reads a value with {@link #readShort16()} and reverse bytes with {@link Short#reverseBytes(short)}
+     * method.
      */
+    @Deprecated // forRemoval = true
     default short readShort16Le() throws IOException {
+        if (current().nextBoolean()) {
+            return Short.reverseBytes(readShort16());
+        }
         return (short) ((readByte8() & 0xFF) | (readByte8() << Byte.SIZE));
     }
 
@@ -157,8 +175,8 @@ default short readUnsignedShort(final int size) throws IOException {
      * Reads an {@code int} value of specified number of bits.
      *
      * @param unsigned a flag for indicating unsigned value; {@code true} for unsigned, {@code false} for signed.
-     * @param size     the number of bits to read; between {@code 1} and ({@value java.lang.Integer#SIZE} - (unsigned ?
-     *                 {@code 1} : {@code 0})), both inclusive.
+     * @param size     the number of bits to read; between {@code 1} and ({@value java.lang.Integer#SIZE} - ({@code
+     *                 unsigned ? 1: 0})), both inclusive.
      * @return an {@code int} value of specified {@code size}.
      * @throws IOException if an I/O error occurs.
      */
@@ -176,22 +194,28 @@ default int readInt(final int size) throws IOException {
     }
 
     /**
-     * Reads a signed {@value java.lang.Integer#SIZE}-bit {@code int} value.
+     * Reads a {@value java.lang.Integer#SIZE}-bit signed {@code int} value.
      *
-     * @return a signed {@value java.lang.Integer#SIZE}-bit {@code int} value.
+     * @return a {@value java.lang.Integer#SIZE}-bit signed {@code int} value read.
      * @throws IOException if an I/O error occurs.
      */
     default int readInt32() throws IOException {
         return readInt(Integer.SIZE);
     }
 
     /**
-     * Reads a signed {@value java.lang.Integer#SIZE}-bit {@code int} value in little endian byte order.
+     * Reads a {@value java.lang.Integer#SIZE}-bit signed {@code int} value in little endian byte order.
      *
-     * @return a signed {@value java.lang.Integer#SIZE}-bit {@code int} value.
+     * @return a {@value java.lang.Integer#SIZE}-bit signed {@code int} value.
      * @throws IOException if an I/O error occurs.
+     * @deprecated Reads a value with {@link #readInt32()} method and reverse bytes with {@link
+     * Integer#reverseBytes(int)} method.
      */
+    @Deprecated // forRemoval = true
     default int readInt32Le() throws IOException {
+        if (current().nextBoolean()) {
+            return Integer.reverseBytes(readInt32());
+        }
         return readShort16Le() & 0xFFFF | readShort16Le() << Short.SIZE;
     }
 
@@ -211,8 +235,8 @@ default int readUnsignedInt(final int size) throws IOException {
      * Reads a {@code long} value of specified number of bits.
      *
      * @param unsigned a flag for indicating unsigned value; {@code true} for unsigned, {@code false} for signed.
-     * @param size     the number of bits to read; between {@code 1} and ({@value java.lang.Long#SIZE} - (unsigned ?
-     *                 {@code 1} : {@code 0})), both inclusive.
+     * @param size     the number of bits to read; between {@code 1} and ({@value java.lang.Long#SIZE} - ({@code
+     *                 unsigned ? 1: 0})), both inclusive.
      * @return a {@code long} value of specified bit size.
      * @throws IOException if an I/O error occurs.
      */
@@ -250,22 +274,28 @@ default long readLong(final int size) throws IOException {
     }
 
     /**
-     * Reads a signed {@value java.lang.Long#SIZE}-bit {@code long} value.
+     * Reads a {@value java.lang.Long#SIZE}-bit signed {@code long} value.
      *
-     * @return a signed {@value java.lang.Long#SIZE}-bit {@code long} value.
+     * @return a {@value java.lang.Long#SIZE}-bit signed {@code long} value.
      * @throws IOException if an I/O error occurs.
      */
     default long readLong64() throws IOException {
         return readLong(Long.SIZE);
     }
 
     /**
-     * Reads a signed {@value java.lang.Long#SIZE}-bit {@code long} value in little endian byte order.
+     * Reads a {@value java.lang.Long#SIZE}-bit signed {@code long} value in little endian byte order.
      *
-     * @return a signed {@value java.lang.Long#SIZE}-bit {@code long} value.
+     * @return a {@value java.lang.Long#SIZE}-bit signed {@code long} value read.
      * @throws IOException if an I/O error occurs.
+     * @deprecated Reads a value with {@link #readLong64()} and reverse bytes with {@link Long#reverseBytes(long)}
+     * method.
      */
+    @Deprecated // forRemoval = true
     default long readLong64Le() throws IOException {
+        if (current().nextBoolean()) {
+            return Long.reverseBytes(readLong64());
+        }
         return readInt32Le() & 0xFFFFFFFFL | ((long) readInt32Le()) << Integer.SIZE;
     }
 
@@ -284,7 +314,7 @@ default long readUnsignedLong(final int size) throws IOException {
     /**
      * Reads a {@code char} value of specified bit size.
      *
-     * @param size the number of bits to read.
+     * @param size the number of bits to read; between {@code 1} and {@value java.lang.Character#SIZE}, both inclusive.
      * @return a {@code char} value.
      * @throws IOException if an I/O error occurs.
      * @see #readChar16()
@@ -306,8 +336,8 @@ default char readChar16() throws IOException {
 
     /**
      * Reads a {@value java.lang.Float#SIZE}-bit {@code float} value. The {@code readFloat32()} method of {@code
-     * BitInput} interface reads a {@value java.lang.Integer#SIZE}-bit {@link Float#intBitsToFloat(int) int bits} and
-     * returns it as a {@code float} value.
+     * BitInput} interface reads a {@value java.lang.Integer#SIZE}-bit {@code int} value and returns a {@code float}
+     * value converted with {@link Float#intBitsToFloat(int)} method.
      *
      * @return a {@value java.lang.Float#SIZE}-bit {@code float} value
      * @throws IOException if an I/O error occurs.
@@ -319,8 +349,8 @@ default float readFloat32() throws IOException {
 
     /**
      * Reads a {@value java.lang.Double#SIZE}-bit {@code double} value. The {@code readDouble64()} method of {@code
-     * BitInput} interface reads a {@value java.lang.Long#SIZE}-bit {@link Double#longBitsToDouble(long) long bits} and
-     * returns it as a {@code double} value.
+     * BitInput} interface reads a {@value java.lang.Long#SIZE}-bit {@code long} value and returns a {@code double}
+     * value converted with {@link Double#longBitsToDouble(long)} method.
      *
      * @return a {@value java.lang.Double#SIZE}-bit {@code double} value
      * @throws IOException if an I/O error occurs.
@@ -373,7 +403,8 @@ default void skip(int bits) throws IOException {
     long align(int bytes) throws IOException;
 
     /**
-     * Aligns to a single byte by discarding bits.
+     * Aligns to a single byte by discarding bits. The {@code align()} method of {@code BitInput} interface invokes
+     * {@link #align(int)} with {@value java.lang.Byte#BYTES}.
      *
      * @return the number of bits discarded while aligning.
      * @throws IOException if an I/O error occurs.

src/main/java/com/github/jinahya/bit/io/BitInputAdapter.java

@@ -45,6 +45,20 @@ public BitInputAdapter(final Supplier<? extends ByteInput> inputSupplier) {
         this.inputSupplier = requireNonNull(inputSupplier, "inputSupplier is null");
     }
 
+    /**
+     * Closes this input and releases any system resources associated with it.
+     *
+     * @throws IOException if an I/O error occurs.
+     * @see ByteInput#close()
+     */
+    @Override
+    public void close() throws IOException {
+        BitInput.super.close(); // does nothing.
+        if (input != null) {
+            input.close();
+        }
+    }
+
     @Override
     public int readInt(final boolean unsigned, int size) throws IOException {
         requireValidSizeForInt(unsigned, size);