Class DebugOutputBitStream

  • All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

    public class DebugOutputBitStream
    extends OutputBitStream
    A debugging wrapper for output bit streams.

    This class can be used to wrap an output bit stream. The semantics of the resulting write operations is unchanged, but each operation will be logged.

    To simplify the output, some operations have a simplified representation. In particular:

    |
    flush();
    ->
    position();
    [
    creation;
    ]
    close();
    {x}
    explicit bits;
    {x:b}
    minimal binary coding of x with bound b;
    {M:x}
    write x with coding M; the latter can be U (unary), g (γ), z (ζ), d (δ), G (Golomb), GS (skewed Golomb); when appropriate, x is followed by an extra integer (modulus, etc.).
    Since:
    0.7.1
    Author:
    Paolo Boldi, Sebastiano Vigna
    • Constructor Detail

      • DebugOutputBitStream

        public DebugOutputBitStream​(OutputBitStream obs,
                                    java.io.PrintStream pw)
        Creates a new debug output bit stream wrapping a given output bit stream and logging on a given writer.
        Parameters:
        obs - the output bit stream to wrap.
        pw - a print stream that will receive the logging data.
      • DebugOutputBitStream

        public DebugOutputBitStream​(OutputBitStream obs)
        Creates a new debug output bit stream wrapping a given output bit stream and logging on standard error.
        Parameters:
        obs - the output bit stream to wrap.
    • Method Detail

      • flush

        public void flush()
                   throws java.io.IOException
        Description copied from class: OutputBitStream
        Flushes the bit stream.

        This method will align the stream, write the bit buffer, empty the byte buffer and delegate to the OutputStream.flush() method of the underlying output stream.

        This method is provided so that users of this class can easily wrap repositionable streams (for instance, file-based streams, which can be repositioned using the underlying FileChannel).

        It is guaranteed that after calling this method the underlying stream can be repositioned, and that the next write to the underlying output stream will start with the content of the first write method called afterwards.

        Specified by:
        flush in interface java.io.Flushable
        Overrides:
        flush in class OutputBitStream
        Throws:
        java.io.IOException
      • close

        public void close()
                   throws java.io.IOException
        Description copied from class: OutputBitStream
        Closes the bit stream. All resources associated with the stream are released.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class OutputBitStream
        Throws:
        java.io.IOException
      • writtenBits

        public long writtenBits()
        Description copied from class: OutputBitStream
        Returns the number of bits written to this bit stream.
        Overrides:
        writtenBits in class OutputBitStream
        Returns:
        the number of bits written so far.
      • writtenBits

        public void writtenBits​(long writtenBits)
        Description copied from class: OutputBitStream
        Sets the number of bits written to this bit stream.

        This method is provided so that, for instance, the user can reset via writtenBits(0) the written-bits count after a OutputBitStream.flush().

        Overrides:
        writtenBits in class OutputBitStream
        Parameters:
        writtenBits - the new value for the number of bits written so far.
      • align

        public int align()
                  throws java.io.IOException
        Description copied from class: OutputBitStream
        Aligns the stream. After a call to this method, the stream is byte aligned. Zeroes are used to pad it if necessary.
        Overrides:
        align in class OutputBitStream
        Returns:
        the number of padding bits.
        Throws:
        java.io.IOException
      • position

        public void position​(long position)
                      throws java.io.IOException
        Description copied from class: OutputBitStream
        Sets this stream bit position, if it is based on a RepositionableStream or on a FileChannel.

        Given an underlying stream that implements RepositionableStream or that can provide a FileChannel via the getChannel() method, a call to this method has the same semantics of a OutputBitStream.flush(), followed by a call to position(position / 8) on the byte stream. Currently there is no clean, working way of supporting out-of-byte-boundary positioning.

        Overrides:
        position in class OutputBitStream
        Parameters:
        position - the new position expressed as a bit offset; it must be byte-aligned.
        Throws:
        java.io.IOException
        See Also:
        FileChannel.position(long)
      • write

        public long write​(byte[] bits,
                          long len)
                   throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a sequence of bits. Bits will be written in the natural way: the first bit is bit 7 of the first byte, the eightth bit is bit 0 of the first byte, the ninth bit is bit 7 of the second byte and so on.
        Overrides:
        write in class OutputBitStream
        Parameters:
        bits - a vector containing the bits to be written.
        len - a bit length.
        Returns:
        the number of bits written (len).
        Throws:
        java.io.IOException
      • writeBit

        public int writeBit​(boolean bit)
                     throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a bit.
        Overrides:
        writeBit in class OutputBitStream
        Parameters:
        bit - a bit.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
      • writeBit

        public int writeBit​(int bit)
                     throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a bit.
        Overrides:
        writeBit in class OutputBitStream
        Parameters:
        bit - a bit.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
      • writeInt

        public int writeInt​(int x,
                            int len)
                     throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a fixed number of bits from an integer.
        Overrides:
        writeInt in class OutputBitStream
        Parameters:
        x - an integer.
        len - a bit length; this many lower bits of the first argument will be written (the most significant bit first).
        Returns:
        the number of bits written (len).
        Throws:
        java.io.IOException
      • writeLong

        public int writeLong​(long x,
                             int len)
                      throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a fixed number of bits from a long.
        Overrides:
        writeLong in class OutputBitStream
        Parameters:
        x - a long.
        len - a bit length; this many lower bits of the first argument will be written (the most significant bit first).
        Returns:
        the number of bits written (len).
        Throws:
        java.io.IOException
      • writeUnary

        public int writeUnary​(int x)
                       throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a natural number in unary coding.

        The unary coding of a natural number n is given by 0n1.

        Overrides:
        writeUnary in class OutputBitStream
        Parameters:
        x - a natural number.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
      • writeLongUnary

        public long writeLongUnary​(long x)
                            throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a long natural number in unary coding.
        Overrides:
        writeLongUnary in class OutputBitStream
        Parameters:
        x - a long natural number.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
        See Also:
        OutputBitStream.writeUnary(int)
      • writeGamma

        public int writeGamma​(int x)
                       throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a natural number in γ coding.

        The γ coding of a positive number of k bits is obtained writing k-1 in unary, followed by the lower k-1 bits of the number. The coding of a natural number is obtained by adding one and coding.

        Overrides:
        writeGamma in class OutputBitStream
        Parameters:
        x - a natural number.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
      • writeDelta

        public int writeDelta​(int x)
                       throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a natural number in δ coding. The δ coding of a positive number of k bits is obtained writing k-1 in γ coding, followed by the lower k-1 bits of the number. The coding of a natural number is obtained by adding one and coding.
        Overrides:
        writeDelta in class OutputBitStream
        Parameters:
        x - a natural number.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
      • writeMinimalBinary

        public int writeMinimalBinary​(int x,
                                      int b)
                               throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a natural number in a limited range using a minimal binary coding.

        A minimal binary code is an optimal code for the uniform distribution. This method uses an optimal code in which shorter words are assigned to smaller integers.

        Overrides:
        writeMinimalBinary in class OutputBitStream
        Parameters:
        x - a natural number.
        b - a strict upper bound for x.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
      • writeLongMinimalBinary

        public int writeLongMinimalBinary​(long x,
                                          long b)
                                   throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a long natural number in a limited range using a minimal binary coding.
        Overrides:
        writeLongMinimalBinary in class OutputBitStream
        Parameters:
        x - a natural number.
        b - a strict upper bound for x.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
        See Also:
        OutputBitStream.writeMinimalBinary(int, int)
      • writeGolomb

        public int writeGolomb​(int x,
                               int b)
                        throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a natural number in Golomb coding.

        Golomb coding with modulo b writes a natural number x as the quotient of the division of x and b in unary, followed by the remainder in minimal binary code.

        This method implements also the case in which b is 0: in this case, the argument x may only be zero, and nothing will be written.

        Overrides:
        writeGolomb in class OutputBitStream
        Parameters:
        x - a natural number.
        b - the modulus for the coding.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
      • writeGolomb

        public int writeGolomb​(int x,
                               int b,
                               int log2b)
                        throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a natural number in Golomb coding. This method is faster than OutputBitStream.writeGolomb(int,int) because it does not have to compute log2b.
        Overrides:
        writeGolomb in class OutputBitStream
        Parameters:
        x - a natural number.
        b - the modulus for the coding.
        log2b - the floor of the base-2 logarithm of the coding modulus (it is irrelevant when b is zero).
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
        See Also:
        OutputBitStream.writeGolomb(int, int)
      • writeLongGolomb

        public long writeLongGolomb​(long x,
                                    long b)
                             throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a long natural number in Golomb coding.
        Overrides:
        writeLongGolomb in class OutputBitStream
        Parameters:
        x - a long natural number.
        b - the modulus for the coding.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
        See Also:
        OutputBitStream.writeGolomb(int, int)
      • writeLongGolomb

        public long writeLongGolomb​(long x,
                                    long b,
                                    int log2b)
                             throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a long natural number in Golomb coding. This method is faster than OutputBitStream.writeLongGolomb(long,long) because it does not have to compute log2b.
        Overrides:
        writeLongGolomb in class OutputBitStream
        Parameters:
        x - a long natural number.
        b - the modulus for the coding.
        log2b - the floor of the base-2 logarithm of the coding modulus (it is irrelevant when b is zero).
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
        See Also:
        OutputBitStream.writeGolomb(int, int)
      • writeSkewedGolomb

        public int writeSkewedGolomb​(int x,
                                     int b)
                              throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a natural number in skewed Golomb coding.

        This method implements also the case in which b is 0: in this case, the argument x may only be zero, and nothing will be written.

        Overrides:
        writeSkewedGolomb in class OutputBitStream
        Parameters:
        x - a natural number.
        b - the modulus for the coding.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
      • writeLongSkewedGolomb

        public long writeLongSkewedGolomb​(long x,
                                          long b)
                                   throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a long natural number in skewed Golomb coding.

        This method implements also the case in which b is 0: in this case, the argument x may only be zero, and nothing will be written.

        Overrides:
        writeLongSkewedGolomb in class OutputBitStream
        Parameters:
        x - a long natural number.
        b - the modulus for the coding.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
        See Also:
        OutputBitStream.writeSkewedGolomb(int, int)
      • writeZeta

        public int writeZeta​(int x,
                             int k)
                      throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a natural number in ζ coding.

        ζ coding (with modulo k) records positive numbers in the intervals [1,2k-1],[2k,2k+1-1],…,[2hk,2(h+1)k-1] by coding h in unary, followed by a minimal binary coding of the offset in the interval. The coding of a natural number is obtained by adding one and coding.

        ζ codes were defined by Paolo Boldi and Sebastiano Vigna in “Codes for the World−Wide Web”, Internet Math., 2(4):405-427, 2005. The paper contains also a detailed analysis.

        Overrides:
        writeZeta in class OutputBitStream
        Parameters:
        x - a natural number.
        k - the shrinking factor.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
      • writeLongZeta

        public int writeLongZeta​(long x,
                                 int k)
                          throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a long natural number in ζ coding.
        Overrides:
        writeLongZeta in class OutputBitStream
        Parameters:
        x - a long natural number.
        k - the shrinking factor.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
        See Also:
        OutputBitStream.writeZeta(int, int)
      • writeNibble

        public int writeNibble​(int x)
                        throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a natural number in variable-length nibble coding.

        Variable-length nibble coding records a natural number by padding its binary representation to the left using zeroes, until its length is a multiple of three. Then, the resulting string is broken in blocks of 3 bits, and each block is prefixed with a bit, which is zero for all blocks except for the last one.

        Overrides:
        writeNibble in class OutputBitStream
        Parameters:
        x - a natural number.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
      • writeLongNibble

        public int writeLongNibble​(long x)
                            throws java.io.IOException
        Description copied from class: OutputBitStream
        Writes a long natural number in variable-length nibble coding.
        Overrides:
        writeLongNibble in class OutputBitStream
        Parameters:
        x - a long natural number.
        Returns:
        the number of bits written.
        Throws:
        java.io.IOException
        See Also:
        OutputBitStream.writeNibble(int)