com.pervasive.datarush.io

Class BinaryBuilder

java.lang.Object

com.pervasive.datarush.io.BinaryBuilder

public class BinaryBuilder
extends Object

A buffer for building variable-length binary valued data. An internal buffer is used to accumulate the binary value, resizing as necessary. Additionally, a number of encodings for multi-byte values such as (but not limited to) longs and doubles is supported. A BinaryBuilder is similar in function to StringBuilder, although it does not allow mutation of previously written data.

Constructor Summary

Constructors

Constructor and Description
BinaryBuilder(int initialSize) Creates a new buffer sized as specified.

Method Summary

Modifier and Type	Method and Description
void	append(byte value) Appends a byte to the buffer.
void	append(byte[] values) Appends a sequence of bytes to the buffer.
void	append(byte[] values, int offset, int length) Appends a subsequence of bytes to the buffer.
void	append(char data) Appends a character value to the buffer.
void	append(CharSequence values) Appends a sequence of character values to the buffer.
void	append(double value) Appends a a double value to the buffer.
void	append(float value) Appends a float value to the buffer.
void	append(int value) Appends an int value to the buffer.
void	append(long value) Appends a long value to the buffer.
void	appendBase128(int value) Appends an int value to the buffer, using variable length base-128 encoding.
void	appendBase128(long value) Appends a long value to the buffer, using variable length base-128 encoding.
void	appendSingleByte(CharSequence values) Appends a sequence of character values to the buffer using only a single byte per character.
void	appendUnsignedBase128(int value) Appends an int value to the buffer, using variable length base-128 encoding with bias towards non-negative values.
void	appendUnsignedBase128(long value) Appends a long value to the buffer, using variable length base-128 encoding with bias towards non-negative values.
static int	base128Size(int value) Computes the length of the base-128 encoding of an int value.
static int	base128Size(long value) Computes the length of the base-128 encoding of an long value.
void	copy(byte[] dest, int offset) Extracts the current contents of the builder to the specified array at the given offset.
static void	encodeInt32(int value, byte[] data, int offset) Writes a 32-bit integer value into the specified position in the given array.
static void	encodeUnsignedBase128(long value, byte[] data, int offset) Writes a 64-bit integer value using base-128 encoding into the specified position in the given array.
void	reset() Resets the buffer to empty.
void	set(int position, int data) Sets 4 bytes beginning at the specified position to the given value.
int	size() Gets the current size of the binary sequence represented by the builder.
byte[]	toBinary() Gets the current contents of the builder.
ByteBuffer	toByteBuffer() Gets a ByteBuffer that wraps the internal bytes storage of this builder object.
String	toString()
static int	unsignedBase128Size(int value) Computes the length of the non-negative biased base-128 encoding of an int value.
static int	unsignedBase128Size(long value) Computes the length of the non-negative biased base-128 encoding of an long value.
void	writeToStream(OutputStream out) Writes the current contents of the builder to the specified OutputStream.

Methods inherited from class java.lang.Object

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

Constructor Detail

BinaryBuilder

public BinaryBuilder(int initialSize)

Creates a new buffer sized as specified. The buffer is initially empty.

Parameters:

initialSize - the size, in bytes, of the internal storage buffer

Method Detail

size

public int size()

Gets the current size of the binary sequence represented by the builder.

Returns:

the current size of the binary data

set

public void set(int position,
                int data)

Sets 4 bytes beginning at the specified position to the given value.

Parameters:

position - the byte offset at which to write the update

data - the 4 byte value to write

append

public void append(byte value)

Appends a byte to the buffer.

Parameters:

value - the byte to append

append

public void append(byte[] values)

Appends a sequence of bytes to the buffer.

This is equivalent to calling append(values, 0, values.length).

Parameters:

values - the bytes to append

append

public void append(byte[] values,
                   int offset,
                   int length)

Appends a subsequence of bytes to the buffer.

Parameters:

values - the sequence containing the bytes to append

offset - the starting position of the subsequence

length - the length of the subsequence

append

public void append(char data)

Appends a character value to the buffer. Values are represented using 2 bytes.

Parameters:

data - the character to append

append

public void append(CharSequence values)

Appends a sequence of character values to the buffer.

Functionally equivalent to calling append(char) on every element in the sequence, though slightly more efficient.

Parameters:

values - the character values to append

appendSingleByte

public void appendSingleByte(CharSequence values)

Appends a sequence of character values to the buffer using only a single byte per character. The least significant byte is encoded. Therefore this encoding can be lossy if any characters cannot be represented in a single byte.

Parameters:

values - the character values to append

append

public void append(int value)

Appends an int value to the buffer. Values are represented using 4 bytes.

Parameters:

value - the value to append

appendUnsignedBase128

public void appendUnsignedBase128(int value)

Appends an int value to the buffer, using variable length base-128 encoding with bias towards non-negative values. If values are known to be non-negative, this guarantees an equal or smaller sized encoding than appendBase128(int) produces. Negative values will always encode to the maximum length.

Base-128 can produce more compact encodings, with the size being proportional to the size of the value. Encodings will vary between 1 and 5 bytes, depending on the value encoded.

Parameters:

value - the unsigned value to append in base-128

appendBase128

public void appendBase128(int value)

Appends an int value to the buffer, using variable length base-128 encoding. Encoding is unbiased with respect to sign, so that values with smaller absolute values will have shorter encodings.

Base-128 can produce more compact encodings, with the size being proportional to the size of the value. Encodings will vary between 1 and 5 bytes, depending on the value encoded.

Parameters:

value - the signed value to append in base-128

append

public void append(long value)

Appends a long value to the buffer. Values are represented using 8 bytes.

Parameters:

value - the value to append

appendUnsignedBase128

public void appendUnsignedBase128(long value)

Appends a long value to the buffer, using variable length base-128 encoding with bias towards non-negative values. If values are known to be non-negative, this guarantees an equal or smaller sized encoding than appendBase128(long) produces. Negative values will always encode to the maximum length.

Base-128 can produce more compact encodings, with the size being proportional to the size of the value. Encodings will vary between 1 and 10 bytes, depending on the value encoded.

Parameters:

value - the unsigned value to append in base-128

appendBase128

public void appendBase128(long value)

Appends a long value to the buffer, using variable length base-128 encoding. Encoding is unbiased with respect to sign, so that values with smaller absolute values will have shorter encodings.

Base-128 can produce more compact encodings, with the size being proportional to the size of the value. Encodings will vary between 1 and 10 bytes, depending on the value encoded.

Parameters:

value - the signed value to append in base-128

append

public void append(float value)

Appends a float value to the buffer. Values are represented using 4 bytes, as mapped by Float.floatToRawIntBits(float).

Parameters:

value - the value to append

append

public void append(double value)

Appends a a double value to the buffer. Values are represented using 8 bytes, as mapped by Double.doubleToRawLongBits(double).

Parameters:

value - the value to append

toBinary

public byte[] toBinary()

Gets the current contents of the builder.

Returns:

a copy of the current buffer

toByteBuffer

public ByteBuffer toByteBuffer()

Gets a ByteBuffer that wraps the internal bytes storage of this builder object. The byte buffer will wrap from the start of the internal byte storage to its current size.

Returns:

ByteBuffer wrapping the internal storage of this builder

copy

public void copy(byte[] dest,
                 int offset)

Extracts the current contents of the builder to the specified array at the given offset.

Parameters:

dest - the target array into which to copy

offset - the offset into the target array at which to start

writeToStream

public void writeToStream(OutputStream out)
                   throws IOException

Writes the current contents of the builder to the specified OutputStream. This is more efficient than calling out.write(toBinary()), as it avoids making an extra copy of the data.

Parameters:

out - the target to which to write the buffer contents

Throws:

IOException - if an error occurs during the write

reset

public void reset()

Resets the buffer to empty.

base128Size

public static final int base128Size(int value)

Computes the length of the base-128 encoding of an int value.

Parameters:

value - the value for which to determine the encoding size

Returns:

the length, in bytes, of the encoding

See Also:

appendBase128(int)

unsignedBase128Size

public static final int unsignedBase128Size(int value)

Computes the length of the non-negative biased base-128 encoding of an int value.

Parameters:

value - the value for which to determine the encoding size

Returns:

the length, in bytes, of the encoding

See Also:

appendUnsignedBase128(int)

base128Size

public static final int base128Size(long value)

Computes the length of the base-128 encoding of an long value.

Parameters:

value - the value for which to determine the encoding size

Returns:

the length, in bytes, of the encoding

See Also:

appendBase128(long)

unsignedBase128Size

public static final int unsignedBase128Size(long value)

Computes the length of the non-negative biased base-128 encoding of an long value.

Parameters:

value - the value for which to determine the encoding size

Returns:

the length, in bytes, of the encoding

See Also:

appendUnsignedBase128(int)

encodeInt32

public static final void encodeInt32(int value,
                                     byte[] data,
                                     int offset)

Writes a 32-bit integer value into the specified position in the given array.

Parameters:

value - the value to write

data - the buffer to update

offset - the byte offset at which to write

encodeUnsignedBase128

public static final void encodeUnsignedBase128(long value,
                                               byte[] data,
                                               int offset)

Writes a 64-bit integer value using base-128 encoding into the specified position in the given array.

Parameters:

value - the value to write in base-128

data - the buffer to update

offset - the byte offset at which to write

toString

public String toString()

Overrides:

toString in class Object