- 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. ABinaryBuilder
is similar in function toStringBuilder
, although it does not allow mutation of previously written data.
-
-
Constructor Summary
Constructors Constructor Description BinaryBuilder(int initialSize)
Creates a new buffer sized as specified.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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(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
append(CharSequence values)
Appends a sequence of character values 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 aByteBuffer
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 specifiedOutputStream
.
-
-
-
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 updatedata
- 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 appendoffset
- the starting position of the subsequencelength
- 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 thanappendBase128(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 thanappendBase128(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 byFloat.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 byDouble.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 aByteBuffer
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 copyoffset
- 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 specifiedOutputStream
. This is more efficient than callingout.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 writedata
- the buffer to updateoffset
- 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-128data
- the buffer to updateoffset
- the byte offset at which to write
-
-