it.unimi.dsi.io
Class DebugOutputBitStream

java.lang.Object
  it.unimi.dsi.io.OutputBitStream
      it.unimi.dsi.io.DebugOutputBitStream

All Implemented Interfaces:

Closeable, Flushable

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

Field Summary

Fields inherited from class it.unimi.dsi.io.OutputBitStream

avail, buffer, DEFAULT_BUFFER_SIZE, DELTA, fileChannel, free, GAMMA, MAX_PRECOMPUTED, os, pos, position, repositionableStream, SHIFTED_GAMMA, wrapping, ZETA_3

Constructor Summary

DebugOutputBitStream(OutputBitStream obs)
Creates a new debug output bit stream wrapping a given output bit stream and logging on standard error.

DebugOutputBitStream(OutputBitStream obs, PrintStream pw)
Creates a new debug output bit stream wrapping a given output bit stream and logging on a given writer.

Method Summary

int	align() Aligns the stream.
void	close() Closes the bit stream.
void	flush() Flushes the bit stream.
void	position(long position) Sets this stream bit position, if it is based on a RepositionableStream or on a FileChannel.
long	write(byte[] bits, long len) Writes a sequence of bits.
int	writeBit(boolean bit) Writes a bit.
int	writeBit(int bit) Writes a bit.
int	writeDelta(int x) Writes a natural number in δ coding.
int	writeGamma(int x) Writes a natural number in γ coding.
int	writeGolomb(int x, int b) Writes a natural number in Golomb coding.
int	writeGolomb(int x, int b, int log2b) Writes a natural number in Golomb coding.
int	writeInt(int x, int len) Writes a fixed number of bits from an integer.
int	writeLong(long x, int len) Writes a fixed number of bits from a long.
int	writeLongDelta(long x) Writes a long natural number in δ coding.
int	writeLongGamma(long x) Writes a long natural number in γ coding.
long	writeLongGolomb(long x, long b) Writes a long natural number in Golomb coding.
long	writeLongGolomb(long x, long b, int log2b) Writes a long natural number in Golomb coding.
int	writeLongMinimalBinary(long x, long b) Writes a long natural number in a limited range using a minimal binary coding.
int	writeLongMinimalBinary(long x, long b, int log2b) Writes a long natural number in a limited range using a minimal binary coding.
int	writeLongNibble(long x) Writes a long natural number in variable-length nibble coding.
long	writeLongSkewedGolomb(long x, long b) Writes a long natural number in skewed Golomb coding.
long	writeLongUnary(long x) Writes a long natural number in unary coding.
int	writeLongZeta(long x, int k) Writes a long natural number in ζ coding.
int	writeMinimalBinary(int x, int b) Writes a natural number in a limited range using a minimal binary coding.
int	writeMinimalBinary(int x, int b, int log2b) Writes a natural number in a limited range using a minimal binary coding.
int	writeNibble(int x) Writes a natural number in variable-length nibble coding.
int	writeSkewedGolomb(int x, int b) Writes a natural number in skewed Golomb coding.
int	writeUnary(int x) Writes a natural number in unary coding.
int	writeZeta(int x, int k) Writes a natural number in ζ coding.
long	writtenBits() Returns the number of bits written to this bit stream.
void	writtenBits(long writtenBits) Sets the number of bits written to this bit stream.

Methods inherited from class it.unimi.dsi.io.OutputBitStream

write, write, writeByteOffset, writeLongShiftedGamma, writeShiftedGamma

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

close

public void close()
           throws IOException

Description copied from class: OutputBitStream

Closes the bit stream. All resources associated with the stream are released.

Specified by:

close in interface Closeable

Overrides:

close 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

position

public void position(long position)
              throws 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:

IOException

See Also:

FileChannel.position(long)

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

writeBit

public int writeBit(boolean bit)
             throws 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:

IOException

writeBit

public int writeBit(int bit)
             throws 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:

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 0ⁿ1.

Overrides:

writeUnary in class OutputBitStream

Parameters:

x - a natural number.

Returns:

the number of bits written.

Throws:

IOException

writeLongUnary

public long writeLongUnary(long x)
                    throws 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:

IOException

See Also:

OutputBitStream.writeUnary(int)

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

writeLongGamma

public int writeLongGamma(long x)
                   throws IOException

Description copied from class: OutputBitStream

Writes a long natural number in γ coding.

Overrides:

writeLongGamma in class OutputBitStream

Parameters:

x - a long natural number.

Returns:

the number of bits written.

Throws:

IOException

See Also:

OutputBitStream.writeGamma(int)

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

writeLongDelta

public int writeLongDelta(long x)
                   throws IOException

Description copied from class: OutputBitStream

Writes a long natural number in δ coding.

Overrides:

writeLongDelta in class OutputBitStream

Parameters:

x - a long natural number.

Returns:

the number of bits written.

Throws:

IOException

See Also:

OutputBitStream.writeDelta(int)

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

writeMinimalBinary

public int writeMinimalBinary(int x,
                              int b,
                              int log2b)
                       throws IOException

Description copied from class: OutputBitStream

Writes a natural number in a limited range using a minimal binary coding. This method is faster than OutputBitStream.writeMinimalBinary(int,int) because it does not have to compute log2b.

Overrides:

writeMinimalBinary in class OutputBitStream

Parameters:

x - a natural number.

b - a strict upper bound for x.

log2b - the floor of the base-2 logarithm of the bound.

Returns:

the number of bits written.

Throws:

IOException

See Also:

OutputBitStream.writeMinimalBinary(int, int)

writeLongMinimalBinary

public int writeLongMinimalBinary(long x,
                                  long b)
                           throws 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:

IOException

See Also:

OutputBitStream.writeMinimalBinary(int, int)

writeLongMinimalBinary

public int writeLongMinimalBinary(long x,
                                  long b,
                                  int log2b)
                           throws IOException

Description copied from class: OutputBitStream

Writes a long natural number in a limited range using a minimal binary coding. This method is faster than OutputBitStream.writeLongMinimalBinary(long,long) because it does not have to compute log2b.

Overrides:

writeLongMinimalBinary in class OutputBitStream

Parameters:

x - a long natural number.

b - a strict upper bound for x.

log2b - the floor of the base-2 logarithm of the bound.

Returns:

the number of bits written.

Throws:

IOException

See Also:

OutputBitStream.writeMinimalBinary(int, int)

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

writeGolomb

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

IOException

See Also:

OutputBitStream.writeGolomb(int, int)

writeLongGolomb

public long writeLongGolomb(long x,
                            long b)
                     throws 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:

IOException

See Also:

OutputBitStream.writeGolomb(int, int)

writeLongGolomb

public long writeLongGolomb(long x,
                            long b,
                            int log2b)
                     throws 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:

IOException

See Also:

OutputBitStream.writeGolomb(int, int)

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

writeLongSkewedGolomb

public long writeLongSkewedGolomb(long x,
                                  long b)
                           throws 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:

IOException

See Also:

OutputBitStream.writeSkewedGolomb(int, int)

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,2^k-1],[2^k,2^k+1-1],…,[2^hk,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

writeLongZeta

public int writeLongZeta(long x,
                         int k)
                  throws 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:

IOException

See Also:

OutputBitStream.writeZeta(int, int)

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

writeLongNibble

public int writeLongNibble(long x)
                    throws 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:

IOException

See Also:

OutputBitStream.writeNibble(int)