Module datarush.commons
Package 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
    Description
    BinaryBuilder(int initialSize)
    Creates a new buffer sized as specified.

  • Method Summary

    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 final int
    base128Size(int value)
    Computes the length of the base-128 encoding of an int value.
    static final 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 final void
    encodeInt32(int value, byte[] data, int offset)
    Writes a 32-bit integer value into the specified position in the given array.
    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.
    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 final int
    unsignedBase128Size(int value)
    Computes the length of the non-negative biased base-128 encoding of an int value.
    static final 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 Details

    • 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 Details

    • 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:

    • 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:

    • 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:

    • 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:

    • 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