Class 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

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