Package it.unimi.dsi.io

Class DebugOutputBitStream

  • All Implemented Interfaces:
    Closeable, Flushable, 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,
                            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 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 Flushable
        Overrides:
        flush in class OutputBitStream
        Throws:
        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 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:
        IOException

      • write

        public long write​(byte[] bits,
                  long len)
           throws 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:
        IOException

      • writeInt

        public int writeInt​(int x,
                    int len)
             throws 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:
        IOException

      • writeLong

        public int writeLong​(long x,
                     int len)
              throws 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:
        IOException

      • writeUnary

        public int writeUnary​(int x)
               throws 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:
        IOException

      • writeGamma

        public int writeGamma​(int x)
               throws 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:
        IOException

      • writeDelta

        public int writeDelta​(int x)
               throws 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:
        IOException

      • writeMinimalBinary

        public int writeMinimalBinary​(int x,
                              int b)
                       throws 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:
        IOException

      • writeGolomb

        public int writeGolomb​(int x,
                       int b)
                throws 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:
        IOException

      • writeSkewedGolomb

        public int writeSkewedGolomb​(int x,
                             int b)
                      throws 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:
        IOException

      • writeZeta

        public int writeZeta​(int x,
                     int k)
              throws 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:
        IOException

      • writeNibble

        public int writeNibble​(int x)
                throws 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:
        IOException