Bug 1106 - Bitstream: Simplify 'msbFirst' case for bulk operations / Add setting of stream position (optional)

- Add setting position entry, optionally supported,
  e.g. ByteBufferStream and ByteArrayStream

- Remove 'msbFirst' parameter on all 'bulk' read/write
  operations.

  These methods use LSB-first always, allowing proper
  stream access of data w/ different bit-sizes.

  Data is now read/write as little-endian
  and swapped accordingly.

  Optimizations are adopted for LSB-first operations.

  This change removes API confusion/bugs:
    - removes one decision (parameter)
    - removes the data reversion case
	- removes bugs w/ different bit-sizes

1 files changed, 332 insertions, 223 deletions

diff --git a/src/java/com/jogamp/common/util/Bitstream.java b/src/java/com/jogamp/common/util/Bitstream.java
index a242faf..e75d820 100644
--- a/src/java/com/jogamp/common/util/Bitstream.java
+++ b/src/java/com/jogamp/common/util/Bitstream.java
@@ -91,6 +91,28 @@ public class Bitstream<T> {
         long position();
 
         /**
+         * Sets this stream's position.
+         * <p>
+         * A set mark is cleared if &gt; new position.
+         * </p>
+         * <p>
+         * Returns {@link Bitstream#EOS} is end-of-stream is reached,
+         * otherwise the new position.
+         * </p>
+         * <p>
+         * Known supporting implementation is {@link ByteBufferStream} and {@link ByteArrayStream}.
+         * </p>
+         *
+         * @param newPosition The new positive position.
+         *
+         * @return The new set position or {@link Bitstream#EOS} if end-of-stream is reached.
+         *
+         * @throws UnsupportedOperationException if not supported, i.e. {@link ByteInputStream} or {@link ByteOutputStream}
+         * @throws IllegalArgumentException If the {@code newPosition} is negative
+         */
+        long position(long newPosition) throws UnsupportedOperationException, IllegalArgumentException;
+
+        /**
          * It is implementation dependent, whether backward skip giving a negative number is supported or not.
          * @param n number of bytes to skip
          * @return actual skipped bytes
@@ -99,9 +121,9 @@ public class Bitstream<T> {
         long skip(final long n) throws IOException;
 
         /**
-         * Set <i>markpos</i> to current position, allowing the stream to be {@link #reset()}.
-         * @param readLimit
-         * @throws UnsupportedOperationException is not supported, i.e. if stream is not an {@link #canInput() input stream}.
+         * Set {@code markpos} to current position, allowing the stream to be {@link #reset()}.
+         * @param readlimit maximum number of bytes able to read before invalidating the {@code markpos}.
+         * @throws UnsupportedOperationException if not supported, i.e. if stream is not an {@link #canInput() input stream}.
          */
         void mark(final int readLimit) throws UnsupportedOperationException;
 
@@ -110,7 +132,7 @@ public class Bitstream<T> {
          * <p>
          * <i>markpos</i> is kept, hence {@link #reset()} can be called multiple times.
          * </p>
-         * @throws UnsupportedOperationException is not supported, i.e. if stream is not an {@link #canInput() input stream}.
+         * @throws UnsupportedOperationException if not supported, i.e. if stream is not an {@link #canInput() input stream}.
          * @throws IllegalStateException if <i>markpos</i> has not been set via {@link #mark(int)} or reset operation failed.
          * @throws IOException if reset operation failed.
          */
@@ -123,7 +145,7 @@ public class Bitstream<T> {
          * otherwise the resulting value.
          * </p>
          * @throws IOException
-         * @throws UnsupportedOperationException is not supported, i.e. if stream is not an {@link #canInput() input stream}.
+         * @throws UnsupportedOperationException if not supported, i.e. if stream is not an {@link #canInput() input stream}.
          */
         int read() throws UnsupportedOperationException, IOException;
 
@@ -134,7 +156,7 @@ public class Bitstream<T> {
          * otherwise the written value.
          * </p>
          * @throws IOException
-         * @throws UnsupportedOperationException is not supported, i.e. if stream is not an {@link #canOutput() output stream}.
+         * @throws UnsupportedOperationException if not supported, i.e. if stream is not an {@link #canOutput() output stream}.
          */
         int write(final byte val) throws UnsupportedOperationException, IOException;
     }
@@ -183,6 +205,18 @@ public class Bitstream<T> {
         public long position() { return pos; }
 
         @Override
+        public long position(final long newPosition) throws UnsupportedOperationException, IllegalArgumentException {
+            if( newPosition >= media.length ) {
+                return Bitstream.EOS;
+            }
+            pos = (int)newPosition;
+            if( posMark > pos ) {
+                posMark = -1;
+            }
+            return pos;
+        }
+
+        @Override
         public long skip(final long n) {
             final long skip;
             if( n >= 0 ) {
@@ -220,7 +254,7 @@ public class Bitstream<T> {
             }
             if( DEBUG ) {
                 if( EOS != r ) {
-                    System.err.println("u8["+(pos-1)+"] -> "+toHexBinString(r, 8));
+                    System.err.println("u8["+(pos-1)+"] -> "+toHexBinString(true, r, 8));
                 } else {
                     System.err.println("u8["+(pos-0)+"] -> EOS");
                 }
@@ -239,7 +273,7 @@ public class Bitstream<T> {
             }
             if( DEBUG ) {
                 if( EOS != r ) {
-                    System.err.println("u8["+(pos-1)+"] <- "+toHexBinString(r, 8));
+                    System.err.println("u8["+(pos-1)+"] <- "+toHexBinString(true, r, 8));
                 } else {
                     System.err.println("u8["+(pos-0)+"] <- EOS");
                 }
@@ -292,6 +326,19 @@ public class Bitstream<T> {
         public long position() { return pos; }
 
         @Override
+        public long position(final long newPosition) throws UnsupportedOperationException, IllegalArgumentException {
+            if( newPosition >= media.limit() ) {
+                return Bitstream.EOS;
+            }
+            media.position((int)newPosition);
+            pos = (int)newPosition;
+            if( posMark > pos ) {
+                posMark = -1;
+            }
+            return pos;
+        }
+
+        @Override
         public long skip(final long n) {
             final long skip;
             if( n >= 0 ) {
@@ -330,7 +377,7 @@ public class Bitstream<T> {
             }
             if( DEBUG ) {
                 if( EOS != r ) {
-                    System.err.println("u8["+(pos-1)+"] -> "+toHexBinString(r, 8));
+                    System.err.println("u8["+(pos-1)+"] -> "+toHexBinString(true, r, 8));
                 } else {
                     System.err.println("u8["+(pos-0)+"] -> EOS");
                 }
@@ -349,7 +396,7 @@ public class Bitstream<T> {
             }
             if( DEBUG ) {
                 if( EOS != r ) {
-                    System.err.println("u8["+(pos-1)+"] <- "+toHexBinString(r, 8));
+                    System.err.println("u8["+(pos-1)+"] <- "+toHexBinString(true, r, 8));
                 } else {
                     System.err.println("u8["+(pos-0)+"] <- EOS");
                 }
@@ -411,6 +458,11 @@ public class Bitstream<T> {
         public long position() { return pos; }
 
         @Override
+        public long position(final long newPosition) throws UnsupportedOperationException, IllegalArgumentException {
+            throw new UnsupportedOperationException("N/a for "+getClass().getCanonicalName());
+        }
+
+        @Override
         public long skip(final long n) throws IOException {
             final long skip = media.skip(n);
             pos += skip;
@@ -438,7 +490,7 @@ public class Bitstream<T> {
             final int r = media.read();
             if(DEBUG) {
                 if( EOS != r ) {
-                    System.err.println("u8["+pos+"] -> "+toHexBinString(r, 8));
+                    System.err.println("u8["+pos+"] -> "+toHexBinString(true, r, 8));
                 } else {
                     System.err.println("u8["+pos+"] -> EOS");
                 }
@@ -505,6 +557,11 @@ public class Bitstream<T> {
         public long position() { return pos; }
 
         @Override
+        public long position(final long newPosition) throws UnsupportedOperationException, IllegalArgumentException {
+            throw new UnsupportedOperationException("N/a for "+getClass().getCanonicalName());
+        }
+
+        @Override
         public long skip(final long n) throws IOException {
             long i = n;
             while(i > 0) {
@@ -539,7 +596,7 @@ public class Bitstream<T> {
             final int r = 0xff & val;
             media.write(r);
             if(DEBUG) {
-                System.err.println("u8["+pos+"] <- "+toHexBinString(r, 8));
+                System.err.println("u8["+pos+"] <- "+toHexBinString(true, r, 8));
             }
             pos++;
             return r;
@@ -685,8 +742,8 @@ public class Bitstream<T> {
     public final boolean canOutput() { return null != bytes ? bytes.canOutput() : false; }
 
     /**
-     * Set <i>markpos</i> to current position, allowing the stream to be {@link #reset()}.
-     * @param readLimit
+     * Set {@code markpos} to current position, allowing the stream to be {@link #reset()}.
+     * @param readlimit maximum number of bytes able to read before invalidating the {@code markpos}.
      * @throws IllegalStateException if not in input mode or stream closed
      */
     public final void mark(final int readLimit) throws IllegalStateException {
@@ -779,46 +836,68 @@ public class Bitstream<T> {
     }
 
     /**
+     * Sets this stream's bit position.
+     * <p>
+     * A set mark is cleared.
+     * </p>
+     * <p>
+     * Returns {@link Bitstream#EOS} is end-of-stream is reached,
+     * otherwise the new position.
+     * </p>
+     * <p>
+     * Known supporting implementation is {@link ByteBufferStream} and {@link ByteArrayStream}.
+     * </p>
+     *
+     * @param newPosition The new positive position.
+     *
+     * @return The new set position or {@link Bitstream#EOS} if end-of-stream is reached.
+     *
+     * @throws UnsupportedOperationException if not supported, i.e. {@link ByteInputStream} or {@link ByteOutputStream}
+     * @throws IllegalArgumentException If the {@code newPosition} is negative
+     * @throws IOException if read error occurs or EOS is reached and {@link #setThrowIOExceptionOnEOF(boolean)} is set to true.
+     * @throws IllegalStateException
+     */
+    public final long position(final long newPosition) throws UnsupportedOperationException, IllegalArgumentException, IllegalStateException, IOException {
+        if( 0 > newPosition ) {
+            throw new IllegalArgumentException("new position not positive: "+newPosition);
+        }
+        bytes.position(0); // throws UnsupportedOperationException
+        resetLocal();
+        if( newPosition > skip(newPosition) ) {
+            return EOS;
+        }
+        return newPosition;
+    }
+
+    /**
      * @param msbFirst if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
      * @return the read bit or {@link #EOS} if end-of-stream is reached.
      * @throws IOException
      * @throws IllegalStateException if not in input mode or stream closed
      */
-    public final int readBit(final boolean msbFirst) throws IllegalStateException, IOException {
+    public final int readBit(final boolean msbFirst) throws UnsupportedOperationException, IllegalStateException, IOException {
         if( outputMode || null == bytes ) {
             throw new IllegalStateException("not in input-mode: "+this);
         }
-        if( msbFirst ) {
-            // MSB
-            if ( 0 < bitCount ) {
-                bitCount--;
+        if ( 0 < bitCount ) {
+            bitCount--;
+            if( msbFirst ) {
                 return  ( bitBuffer >>> bitCount ) & 0x01;
             } else {
-                bitBuffer = bytes.read();
-                if( EOS == bitBuffer ) {
-                    if( throwIOExceptionOnEOF ) {
-                        throw new IOException("EOS "+this);
-                    }
-                    return EOS;
-                } else {
-                    bitCount=7;
-                    return bitBuffer >>> 7;
-                }
+                return  ( bitBuffer >>> ( 7 - bitCount ) ) & 0x01;
             }
         } else {
-            // LSB
-            if ( 0 < bitCount ) {
-                bitCount--;
-                return  ( bitBuffer >>> ( 7 - bitCount ) ) & 0x01;
+            bitBuffer = bytes.read();
+            if( EOS == bitBuffer ) {
+                if( throwIOExceptionOnEOF ) {
+                    throw new IOException("EOS "+this);
+                }
+                return EOS;
             } else {
-                bitBuffer = bytes.read();
-                if( EOS == bitBuffer ) {
-                    if( throwIOExceptionOnEOF ) {
-                        throw new IOException("EOS "+this);
-                    }
-                    return EOS;
+                bitCount=7;
+                if( msbFirst ) {
+                    return bitBuffer >>> 7;
                 } else {
-                    bitCount=7;
                     return bitBuffer & 0x01;
                 }
             }
@@ -836,36 +915,25 @@ public class Bitstream<T> {
         if( !outputMode || null == bytes ) {
             throw new IllegalStateException("not in output-mode: "+this);
         }
-        if( msbFirst ) {
-            // MSB
-            if ( 0 < bitCount ) {
-                bitCount--;
+        if ( 0 < bitCount ) {
+            bitCount--;
+            if( msbFirst ) {
                 bitBuffer |= ( 0x01 & bit ) << bitCount;
-                if( 0 == bitCount ) {
-                    final int r = bytes.write((byte)bitBuffer);
-                    if( throwIOExceptionOnEOF && EOS == r ) {
-                        throw new IOException("EOS "+this);
-                    }
-                    return r;
-                }
             } else {
-                bitCount = 7;
-                bitBuffer = ( 0x01 & bit ) << 7;
-            }
-        } else {
-            // LSB
-            if ( 0 < bitCount ) {
-                bitCount--;
                 bitBuffer |= ( 0x01 & bit ) << ( 7 - bitCount );
-                if( 0 == bitCount ) {
-                    final int r = bytes.write((byte)bitBuffer);
-                    if( throwIOExceptionOnEOF && EOS == r ) {
-                        throw new IOException("EOS "+this);
-                    }
-                    return r;
+            }
+            if( 0 == bitCount ) {
+                final int r = bytes.write((byte)bitBuffer);
+                if( throwIOExceptionOnEOF && EOS == r ) {
+                    throw new IOException("EOS "+this);
                 }
+                return r;
+            }
+        } else {
+            bitCount = 7;
+            if( msbFirst ) {
+                bitBuffer = ( 0x01 & bit ) << 7;
             } else {
-                bitCount = 7;
                 bitBuffer = 0x01 & bit;
             }
         }
@@ -877,7 +945,7 @@ public class Bitstream<T> {
      *
      * @param n number of bits to skip
      * @return actual skipped bits
-     * @throws IOException
+     * @throws IOException if read error occurs or EOS is reached and {@link #setThrowIOExceptionOnEOF(boolean)} is set to true.
      * @throws IllegalStateException if closed
      */
     public long skip(final long n) throws IllegalStateException, IOException {
@@ -939,85 +1007,96 @@ public class Bitstream<T> {
                 return nX - notReadBits;
             }
         } else {
-            // FIXME: Backward skip
+            // Zero skip or backward skip
+            // FIXME: Backward skip n < 0
             return 0;
         }
     }
 
+    private static final boolean useFastPathStream = true;
+    private static final boolean useFastPathTypes = true;
+
     /**
-     * Return incoming bits as read via {@link #readBit(boolean)}.
+     * Return incoming bits as read via {@link #readBit(boolean)} LSB-first as little-endian.
      * <p>
-     * The incoming bits are stored in MSB-first order, i.e. first on highest position and last bit on lowest position.
-     * Hence reading w/ <i>lsbFirst</i>, the bit order will be reversed!
+     * The incoming bit order is from low- to most-significant-bit, maintaining bit LSB-first order.
      * </p>
-     * @param msbFirst if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
      * @param n number of bits, maximum 31 bits
      * @return the read bits from 0-n in the given order or {@link #EOS}.
      * @throws IllegalStateException if not in input mode or stream closed
      * @throws IllegalArgumentException if n > 31
      * @throws IOException
      */
-    public int readBits31(final boolean msbFirst, final int n) throws IllegalArgumentException, IOException {
+    public int readBits31(final int n) throws IllegalArgumentException, IOException {
         if( 31 < n ) {
             throw new IllegalArgumentException("n > 31: "+n);
         }
         if( outputMode || null == bytes ) {
             throw new IllegalStateException("not in input-mode: "+this);
         }
-        if( !msbFirst || 0 == n ) {
-            // Slow path
-            int r = 0;
-            int c = n;
-            while(--c >= 0) {
-                final int b = readBit(msbFirst);
-                if( EOS == b ) {
-                    return EOS;
-                }
-                r |= b << c;
-            }
-            return r;
+        if( 0 == n ) {
+            return 0;
         } else {
-            // fast path: MSB
-            int c = n;
-            final int n1 = Math.min(c, bitCount); // remaining portion
-            int r;
-            if( 0 < n1 ) {
-                final int m1 = ( 1 << n1 ) - 1;
-                bitCount -= n1;
-                c -= n1;
-                r = ( m1 & ( bitBuffer >>> bitCount ) ) << c;
-                if( 0 == c ) {
-                    return r;
+            if( !useFastPathStream ) {
+                // Slow path
+                int r = 0;
+                for(int i=0; i < n; i++) {
+                    final int b = readBit(false /* msbFirst */);
+                    if( EOS == b ) {
+                        if( throwIOExceptionOnEOF ) {
+                            throw new IOException("EOS "+this);
+                        }
+                        return EOS;
+                    }
+                    r |= b << i;
                 }
+                return r;
             } else {
-                r = 0;
-            }
-            assert( 0 == bitCount );
-            do {
-                bitBuffer = bytes.read();
-                if( EOS == bitBuffer ) {
-                    if( throwIOExceptionOnEOF ) {
-                        throw new IOException("EOS "+this);
+                // fast path
+                int c = n;
+                final int n1 = Math.min(n, bitCount); // remaining portion
+                int r;
+                if( 0 < n1 ) {
+                    final int m1 = ( 1 << n1 ) - 1;
+                    final int s1 = 7 - bitCount + 1; // LSBfirst: right-shift to new bits
+                    bitCount -= n1;
+                    c -= n1;
+                    // MSBfirst: r = ( m1 & ( bitBuffer >>> bitCount ) ) << c;
+                    r = ( m1 & ( bitBuffer >>> s1 ) ); // LSBfirst
+                    if( 0 == c ) {
+                        return r;
                     }
-                    return EOS;
+                } else {
+                    r = 0;
                 }
-                final int n2 = Math.min(c, 8); // full portion
-                final int m2 = ( 1 << n2 ) - 1;
-                bitCount = 8 - n2;
-                c -= n2;
-                r |= ( m2 & ( bitBuffer >>> bitCount ) ) << c;
-            } while ( 0 < c );
-            return r;
+                assert( 0 == bitCount );
+                int s = n1; // LSBfirst: left shift for additional elements
+                do {
+                    bitBuffer = bytes.read();
+                    if( EOS == bitBuffer ) {
+                        if( throwIOExceptionOnEOF ) {
+                            throw new IOException("EOS "+this);
+                        }
+                        return EOS;
+                    }
+                    final int n2 = Math.min(c, 8); // full portion
+                    final int m2 = ( 1 << n2 ) - 1;
+                    bitCount = 8 - n2;
+                    c -= n2;
+                    // MSBfirst: r |= ( m2 & ( bitBuffer >>> bitCount ) ) << c;
+                    r |= ( m2 & bitBuffer ) << s; // LSBfirst on new bits
+                    s += n2;
+                } while ( 0 < c );
+                return r;
+            }
         }
     }
 
     /**
-     * Write the given bits via {@link #writeBit(boolean, int)}.
+     * Write the given bits via {@link #writeBit(boolean, int)} LSB-first as little-endian.
      * <p>
-     * The given bits are scanned from LSB-first order.
-     * Hence reading w/ <i>msbFirst</i>, the bit order will be reversed!
+     * The outgoing bit order is from low- to most-significant-bit, maintaining bit LSB-first order.
      * </p>
-     * @param msbFirst if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
      * @param n number of bits, maximum 31 bits
      * @param bits the bits to write
      * @return the written bits or {@link #EOS}.
@@ -1025,76 +1104,81 @@ public class Bitstream<T> {
      * @throws IllegalArgumentException if n > 31
      * @throws IOException
      */
-    public int writeBits31(final boolean msbFirst, final int n, final int bits) throws IllegalStateException, IllegalArgumentException, IOException {
+    public int writeBits31(final int n, final int bits) throws IllegalStateException, IllegalArgumentException, IOException {
         if( 31 < n ) {
             throw new IllegalArgumentException("n > 31: "+n);
         }
         if( !outputMode || null == bytes ) {
             throw new IllegalStateException("not in output-mode: "+this);
         }
-        if( !msbFirst || 0 == n ) {
-            // Slow path
-            int c = n;
-            while(--c >= 0) {
-                final int b = writeBit(msbFirst, ( bits >>> c ) & 0x1);
-                if( EOS == b ) {
-                    return EOS;
-                }
-            }
-        } else {
-            // fast path: MSB
-            int c = n;
-            final int n1 = Math.min(c, bitCount); // remaining portion
-            if( 0 < n1 ) {
-                final int m1 = ( 1 << n1 ) - 1;
-                bitCount -= n1;
-                c -= n1;
-                bitBuffer |= ( m1 & ( bits >> c ) ) << bitCount;
-                if( 0 == bitCount ) {
-                    if( EOS == bytes.write((byte)bitBuffer) ) {
-                        if( throwIOExceptionOnEOF ) {
-                            throw new IOException("EOS "+this);
-                        }
+        if( 0 < n ) {
+            if( !useFastPathStream ) {
+                // Slow path
+                for(int i=0; i < n; i++) {
+                    final int b = writeBit(false /* msbFirst */, ( bits >>> i ) & 0x1);
+                    if( EOS == b ) {
                         return EOS;
                     }
                 }
-                if( 0 == c ) {
-                    return bits;
-                }
-            }
-            assert( 0 == bitCount );
-            do {
-                final int n2 = Math.min(c, 8); // full portion
-                final int m2 = ( 1 << n2 ) - 1;
-                bitCount = 8 - n2;
-                c -= n2;
-                bitBuffer = ( m2 & ( bits >> c ) ) << bitCount;
-                if( 0 == bitCount ) {
-                    if( EOS == bytes.write((byte)bitBuffer) ) {
-                        if( throwIOExceptionOnEOF ) {
-                            throw new IOException("EOS "+this);
+            } else {
+                // fast path
+                int c = n;
+                final int n1 = Math.min(n, bitCount); // remaining portion
+                if( 0 < n1 ) {
+                    final int m1 = ( 1 << n1 ) - 1;
+                    final int s1 = 7 - bitCount + 1; // LSBfirst: left-shift to free bit-pos
+                    bitCount -= n1;
+                    c -= n1;
+                    // MSBfirst: bitBuffer |= ( m1 & ( bits >>> c ) ) << bitCount;
+                    bitBuffer |= ( m1 & bits ) << s1 ; // LSBfirst
+                    if( 0 == bitCount ) {
+                        if( EOS == bytes.write((byte)bitBuffer) ) {
+                            if( throwIOExceptionOnEOF ) {
+                                throw new IOException("EOS "+this);
+                            }
+                            return EOS;
                         }
-                        return EOS;
+                    }
+                    if( 0 == c ) {
+                        return bits;
                     }
                 }
-            } while ( 0 < c );
+                assert( 0 == bitCount );
+                int s = n1; // LSBfirst: left shift for additional elements
+                do {
+                    final int n2 = Math.min(c, 8); // full portion
+                    final int m2 = ( 1 << n2 ) - 1;
+                    bitCount = 8 - n2;
+                    c -= n2;
+                    // MSBfirst: bitBuffer = ( m2 & ( bits >>> c ) ) << bitCount;
+                    bitBuffer = ( m2 & ( bits >>> s ) ); // LSBfirst
+                    s += n2;
+                    if( 0 == bitCount ) {
+                        if( EOS == bytes.write((byte)bitBuffer) ) {
+                            if( throwIOExceptionOnEOF ) {
+                                throw new IOException("EOS "+this);
+                            }
+                            return EOS;
+                        }
+                    }
+                } while ( 0 < c );
+            }
         }
         return bits;
     }
 
     /**
-     * Return incoming <code>uint8_t</code> as read via {@link #readBits31(boolean, int)}.
+     * Return incoming <code>uint8_t</code> as read via {@link #readBits31(int)}.
      * <p>
      * In case of a <code>int8_t</code> 2-complement signed value, simply cast the result to <code>byte</code>
      * after checking for {@link #EOS}.
      * </p>
-     * @param msbFirst if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
      * @return {@link #EOS} or the 8bit unsigned value within the lower bits.
      * @throws IllegalStateException if not in input mode or stream closed
      * @throws IOException
      */
-    public final int readUInt8(final boolean msbFirst) throws IllegalStateException, IOException {
-        if( 0 == bitCount && msbFirst ) {
+    public final int readUInt8() throws IllegalStateException, IOException {
+        if( 0 == bitCount && useFastPathTypes ) {
             // fast path
             if( outputMode || null == bytes ) {
                 throw new IllegalStateException("not in input-mode: "+this);
@@ -1105,19 +1189,18 @@ public class Bitstream<T> {
             }
             return r;
         } else {
-            return readBits31(msbFirst, 8);
+            return readBits31(8);
         }
     }
 
     /**
-     * Write the given 8 bits via {@link #writeBits31(boolean, int, int)}.
-     * @param msbFirst if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
+     * Write the given 8 bits via {@link #writeBits31(int, int)}.
      * @return {@link #EOS} or the written 8bit value.
      * @throws IllegalStateException if not in output mode or stream closed
      * @throws IOException
      */
-    public final int writeInt8(final boolean msbFirst, final byte int8) throws IllegalStateException, IOException {
-        if( 0 == bitCount && msbFirst ) {
+    public final int writeInt8(final byte int8) throws IllegalStateException, IOException {
+        if( 0 == bitCount && useFastPathTypes  ) {
             // fast path
             if( !outputMode || null == bytes ) {
                 throw new IllegalStateException("not in output-mode: "+this);
@@ -1128,25 +1211,24 @@ public class Bitstream<T> {
             }
             return r;
         } else {
-            return this.writeBits31(msbFirst, 8, int8);
+            return this.writeBits31(8, int8);
         }
     }
 
     /**
-     * Return incoming <code>uint16_t</code> as read via {@link #readBits31(boolean, int)}
-     * and swap bytes if !bigEndian.
+     * Return incoming <code>uint16_t</code> as read via {@link #readBits31(int)} LSB-first as little-endian,
+     * hence bytes are swapped if bigEndian.
      * <p>
      * In case of a <code>int16_t</code> 2-complement signed value, simply cast the result to <code>short</code>
      * after checking for {@link #EOS}.
      * </p>
-     * @param msbFirst if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
-     * @param bigEndian if false, swap incoming bytes to little-endian, otherwise leave them as big-endian.
+     * @param bigEndian if true, swap incoming bytes to little-endian, otherwise leave them as little-endian.
      * @return {@link #EOS} or the 16bit unsigned value within the lower bits.
      * @throws IllegalStateException if not in input mode or stream closed
      * @throws IOException
      */
-    public final int readUInt16(final boolean msbFirst, final boolean bigEndian) throws IllegalStateException, IOException {
-        if( 0 == bitCount && msbFirst ) {
+    public final int readUInt16(final boolean bigEndian) throws IllegalStateException, IOException {
+        if( 0 == bitCount && useFastPathTypes ) {
             // fast path
             if( outputMode || null == bytes ) {
                 throw new IllegalStateException("not in input-mode: "+this);
@@ -1164,21 +1246,21 @@ public class Bitstream<T> {
                 return b2 << 8 | b1;
             }
         } else {
-            final int i16 = readBits31(msbFirst, 16);
+            final int i16 = readBits31(16);
             if( EOS == i16 ) {
                 return EOS;
             } else if( bigEndian ) {
-                return i16;
-            } else {
                 final int b1 = 0xff & ( i16 >>> 8 );
                 final int b2 = 0xff &   i16;
                 return b2 << 8 | b1;
+            } else {
+                return i16;
             }
         }
     }
 
     /**
-     * Return incoming <code>uint16_t</code> value and swap bytes if !bigEndian.
+     * Return incoming <code>uint16_t</code> value and swap bytes according to bigEndian.
      * <p>
      * In case of a <code>int16_t</code> 2-complement signed value, simply cast the result to <code>short</code>.
      * </p>
@@ -1199,16 +1281,15 @@ public class Bitstream<T> {
     }
 
     /**
-     * Write the given 16 bits via {@link #writeBits31(boolean, int, int)},
-     * while swapping bytes if !bigEndian beforehand.
-     * @param msbFirst if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
-     * @param bigEndian if false, swap given bytes to little-endian, otherwise leave them as big-endian.
+     * Write the given 16 bits via {@link #writeBits31(int, int)} LSB-first as little-endian,
+     * hence bytes are swapped if bigEndian.
+     * @param bigEndian if true, swap given bytes to little-endian, otherwise leave them as little-endian.
      * @return {@link #EOS} or the written 16bit value.
      * @throws IllegalStateException if not in output mode or stream closed
      * @throws IOException
      */
-    public final int writeInt16(final boolean msbFirst, final boolean bigEndian, final short int16) throws IllegalStateException, IOException {
-        if( 0 == bitCount && msbFirst ) {
+    public final int writeInt16(final boolean bigEndian, final short int16) throws IllegalStateException, IOException {
+        if( 0 == bitCount && useFastPathTypes ) {
             // fast path
             if( !outputMode || null == bytes ) {
                 throw new IllegalStateException("not in output-mode: "+this);
@@ -1233,29 +1314,28 @@ public class Bitstream<T> {
             }
             return EOS;
         } else if( bigEndian ) {
-            return writeBits31(msbFirst, 16, int16);
-        } else {
             final int b1 = 0xff & ( int16 >>> 8 );
             final int b2 = 0xff &   int16;
-            return writeBits31(msbFirst, 16, b2 << 8 | b1);
+            return writeBits31(16, b2 << 8 | b1);
+        } else {
+            return writeBits31(16, int16);
         }
     }
 
     /**
-     * Return incoming <code>uint32_t</code> as read via {@link #readBits31(boolean, int)}
-     * and swap bytes if !bigEndian.
+     * Return incoming <code>uint32_t</code> as read via {@link #readBits31(int)} LSB-first as little-endian,
+     * hence bytes are swapped if bigEndian.
      * <p>
      * In case of a <code>int32_t</code> 2-complement signed value, simply cast the result to <code>int</code>
      * after checking for {@link #EOS}.
      * </p>
-     * @param msbFirst if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
-     * @param bigEndian if false, swap incoming bytes to little-endian, otherwise leave them as big-endian.
+     * @param bigEndian if true, swap incoming bytes to little-endian, otherwise leave them as little-endian.
      * @return {@link #EOS} or the 32bit unsigned value within the lower bits.
      * @throws IllegalStateException if not in input mode or stream closed
      * @throws IOException
      */
-    public final long readUInt32(final boolean msbFirst, final boolean bigEndian) throws IllegalStateException, IOException {
-        if( 0 == bitCount && msbFirst ) {
+    public final long readUInt32(final boolean bigEndian) throws IllegalStateException, IOException {
+        if( 0 == bitCount && useFastPathTypes ) {
             // fast path
             if( outputMode || null == bytes ) {
                 throw new IllegalStateException("not in input-mode: "+this);
@@ -1275,24 +1355,24 @@ public class Bitstream<T> {
                 return 0xffffffffL & ( b4 << 24 | b3 << 16 | b2 << 8 | b1 );
             }
         } else {
-            final int i16a = readBits31(msbFirst, 16);
-            final int i16b = EOS != i16a ? readBits31(msbFirst, 16) : EOS;
+            final int i16a = readBits31(16);
+            final int i16b = EOS != i16a ? readBits31(16) : EOS;
             if( EOS == i16b ) {
                 return EOS;
             } else if( bigEndian ) {
-                return 0xffffffffL & ( i16a << 16 | i16b );
-            } else {
-                final int b1 = 0xff & ( i16a >>> 8 );
-                final int b2 = 0xff &   i16a;
-                final int b3 = 0xff & ( i16b >>> 8 );
-                final int b4 = 0xff &   i16b;
+                final int b1 = 0xff & ( i16b >>> 8 );
+                final int b2 = 0xff &   i16b;
+                final int b3 = 0xff & ( i16a >>> 8 );
+                final int b4 = 0xff &   i16a;
                 return 0xffffffffL & ( b4 << 24 | b3 << 16 | b2 << 8 | b1 );
+            } else {
+                return 0xffffffffL & ( i16b << 16 | i16a );
             }
         }
     }
 
     /**
-     * Return incoming <code>uint32_t</code> and swap bytes if !bigEndian.
+     * Return incoming <code>uint32_t</code> and swap bytes according to bigEndian.
      * <p>
      * In case of a <code>int32_t</code> 2-complement signed value, simply cast the result to <code>int</code>.
      * </p>
@@ -1314,16 +1394,15 @@ public class Bitstream<T> {
     }
 
     /**
-     * Write the given 32 bits via {@link #writeBits31(boolean, int, int)},
-     * while swapping bytes if !bigEndian beforehand.
-     * @param msbFirst if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.
-     * @param bigEndian if false, swap given bytes to little-endian, otherwise leave them as little-endian.
+     * Write the given 32 bits via {@link #writeBits31(int, int)} LSB-first as little-endian,
+     * hence bytes are swapped if bigEndian.
+     * @param bigEndian if true, swap given bytes to little-endian, otherwise leave them as little-endian.
      * @return {@link #EOS} or the written 32bit value.
      * @throws IllegalStateException if not in output mode or stream closed
      * @throws IOException
      */
-    public final int writeInt32(final boolean msbFirst, final boolean bigEndian, final int int32) throws IllegalStateException, IOException {
-        if( 0 == bitCount && msbFirst ) {
+    public final int writeInt32(final boolean bigEndian, final int int32) throws IllegalStateException, IOException {
+        if( 0 == bitCount && useFastPathTypes ) {
             // fast path
             if( !outputMode || null == bytes ) {
                 throw new IllegalStateException("not in output-mode: "+this);
@@ -1358,21 +1437,21 @@ public class Bitstream<T> {
             }
             return EOS;
         } else if( bigEndian ) {
-            final int hi = 0x0000ffff & ( int32 >>> 16 );
-            final int lo = 0x0000ffff &   int32 ;
-            if( EOS != writeBits31(msbFirst, 16, hi) ) {
-                if( EOS != writeBits31(msbFirst, 16, lo) ) {
+            final int p1 = 0xff & ( int32 >>> 24 );
+            final int p2 = 0xff & ( int32 >>> 16 );
+            final int p3 = 0xff & ( int32 >>>  8 );
+            final int p4 = 0xff &   int32         ;
+            if( EOS != writeBits31(16, p2 << 8 | p1) ) {
+                if( EOS != writeBits31(16, p4 << 8 | p3) ) {
                     return int32;
                 }
             }
             return EOS;
         } else {
-            final int p1 = 0xff & ( int32 >>> 24 );
-            final int p2 = 0xff & ( int32 >>> 16 );
-            final int p3 = 0xff & ( int32 >>>  8 );
-            final int p4 = 0xff &   int32         ;
-            if( EOS != writeBits31(msbFirst, 16, p4 << 8 | p3) ) {
-                if( EOS != writeBits31(msbFirst, 16, p2 << 8 | p1) ) {
+            final int hi = 0x0000ffff & ( int32 >>> 16 );
+            final int lo = 0x0000ffff &   int32 ;
+            if( EOS != writeBits31(16, lo) ) {
+                if( EOS != writeBits31(16, hi) ) {
                     return int32;
                 }
             }
@@ -1429,22 +1508,52 @@ public class Bitstream<T> {
             bpos = bytes.position();
         }
         return String.format("%s, pos %d [byteP %d, bitCnt %d], bitbuf %s",
-                mode, position(), bpos, bitCount, toHexBinString(bitBuffer, 8));
+                mode, position(), bpos, bitCount, toHexBinString(true, bitBuffer, 8));
     }
 
     private static final String strZeroPadding= "0000000000000000000000000000000000000000000000000000000000000000"; // 64
-    public static String toBinString(final int v, final int bitCount) {
+    public static String toBinString(final boolean msbFirst, final int v, final int bitCount) {
         if( 0 == bitCount ) {
             return "";
         }
-        final int mask = (int) ( ( 1L << bitCount ) - 1L );
-        final String s0 = Integer.toBinaryString( mask & v );
-        return strZeroPadding.substring(0, bitCount-s0.length())+s0;
+        if( msbFirst ) {
+            final int mask = (int) ( ( 1L << bitCount ) - 1L );
+            final String s0 = Integer.toBinaryString( mask & v );
+            return strZeroPadding.substring(0, bitCount-s0.length())+s0;
+        } else {
+            final char[] c = new char[32];
+            for(int i=0; i<bitCount; i++) {
+                c[i] = 0 != ( v & ( 1 << i ) ) ? '1' : '0';
+            }
+            final String s0 = new String(c, 0, bitCount);
+            return s0+strZeroPadding.substring(0, bitCount-s0.length());
+        }
     }
-    public static String toHexBinString(final int v, final int bitCount) {
+    public static String toHexBinString(final boolean msbFirst, final int v, final int bitCount) {
         final int nibbles = 0 == bitCount ? 2 : ( bitCount + 3 ) / 4;
-        return String.format("[%0"+nibbles+"X, %s]", v, toBinString(v, bitCount));
+        return String.format("[0x%0"+nibbles+"X, msbFirst %b, %s]", v, msbFirst, toBinString(msbFirst, v, bitCount));
+    }
+    public static final String toHexBinString(final boolean msbFirst, final byte[] data, final int offset, final int len) {
+        final StringBuilder sb = new StringBuilder();
+        sb.append("[");
+        for(int i=0; i<len; i++) {
+            final int v = 0xFF & data[offset+i];
+            sb.append(toHexBinString(msbFirst, v, 8)).append(", ");
+        }
+        sb.append("]");
+        return sb.toString();
     }
+    public static final String toHexBinString(final boolean msbFirst, final ByteBuffer data, final int offset, final int len) {
+        final StringBuilder sb = new StringBuilder();
+        sb.append("[");
+        for(int i=0; i<len; i++) {
+            final int v = 0xFF & data.get(offset+i);
+            sb.append(toHexBinString(msbFirst, v, 8)).append(", ");
+        }
+        sb.append("]");
+        return sb.toString();
+    }
+
     public static void checkBounds(final byte[] sb, final int offset, final int remaining) throws IndexOutOfBoundsException {
         if( offset + remaining > sb.length ) {
             throw new IndexOutOfBoundsException("Buffer of size "+sb.length+" cannot hold offset "+offset+" + remaining "+remaining);