Package io.permazen.util

Class LongEncoder

java.lang.Object
io.permazen.util.LongEncoder
public final class LongEncoder extends Object
Encodes long values to/from binary, preserving sort order, and such that the length of the encoding is optimized for values near zero.

Some examples (in numerical order):

Encoding Examples
Value (decimal) Value (hex) Length Bytes
0x8000000000000000 -9223372036854775808 9 018000000000000076
0xfeffffffffffff89 -72057594037928055 9 01feffffffffffffff
0xfeffffffffffff8a -72057594037928054 8 0200000000000000
0xff00000000000000 -72057594037927936 8 0200000000000076
0xfffeffffffffff89 -281474976710775 8 02feffffffffffff
0xfffeffffffffff8a -281474976710774 7 03000000000000
0xffff000000000000 -281474976710656 7 03000000000076
0xfffffeffffffff89 -1099511627895 7 03feffffffffff
0xfffffeffffffff8a -1099511627894 6 040000000000
0xffffff0000000000 -1099511627776 6 040000000076
0xfffffffeffffff89 -4294967415 6 04feffffffff
0xfffffffeffffff8a -4294967414 5 0500000000
0xffffffff00000000 -4294967296 5 0500000076
0xfffffffffeffff89 -16777335 5 05feffffff
0xfffffffffeffff8a -16777334 4 06000000
0xffffffffff000000 -16777216 4 06000076
0xfffffffffffeff89 -65655 4 06feffff
0xfffffffffffeff8a -65654 3 070000
0xffffffffffff0000 -65536 3 070076
0xfffffffffffffe89 -375 3 07feff
0xfffffffffffffe8a -374 2 0800
0xffffffffffffff00 -256 2 0876
0xffffffffffffff89 -119 2 08ff
0xffffffffffffff8a -118 1 09
0xffffffffffffff8b -117 1 0a
0xffffffffffffff8c -116 1 0b
0xffffffffffffffa9 -87 1 28
0xffffffffffffffc9 -55 1 48
0xffffffffffffffe9 -23 1 68
0xfffffffffffffffe -2 1 7d
0xffffffffffffffff -1 1 7e
0x0000000000000000 0 1 7f
0x0000000000000001 1 1 80
0x0000000000000002 2 1 81
0x0000000000000071 113 1 f0
0x0000000000000077 119 1 f6
0x0000000000000078 120 2 f700
0x0000000000000177 375 2 f7ff
0x0000000000000178 376 3 f80100
0x0000000000010077 65655 3 f8ffff
0x0000000000010078 65656 4 f9010000
0x0000000001000077 16777335 4 f9ffffff
0x0000000001000078 16777336 5 fa01000000
0x0000000100000077 4294967415 5 faffffffff
0x0000000100000078 4294967416 6 fb0100000000
0x0000010000000077 1099511627895 6 fbffffffffff
0x0000010000000078 1099511627896 7 fc010000000000
0x0001000000000077 281474976710775 7 fcffffffffffff
0x0001000000000078 281474976710776 8 fd01000000000000
0x0100000000000077 72057594037928055 8 fdffffffffffffff
0x0100000000000078 72057594037928056 9 fe0100000000000000
0x7fffffffffffff78 9223372036854775672 9 fe7fffffffffffff00
0x7fffffffffffffff 9223372036854775807 9 fe7fffffffffffff87

Encoded values are guaranteed to not start with 0x00 or 0xff.

  • Field Details

    • MAX_ENCODED_LENGTH

      public static final int MAX_ENCODED_LENGTH
      Maximum possible length of an encoded value.
      See Also:

    • MIN_SINGLE_BYTE_ENCODED

      public static final int MIN_SINGLE_BYTE_ENCODED
      Minimum value for the first byte of a single byte encoded value. Lower values indicate a multiple byte encoded negative value.
      See Also:

    • MAX_SINGLE_BYTE_ENCODED

      public static final int MAX_SINGLE_BYTE_ENCODED
      Maximum value for the first byte of a single byte encoded value. Higher values indicate a multiple byte encoded positive value.
      See Also:

    • ZERO_ADJUST

      public static final int ZERO_ADJUST
      Adjustment applied to single byte encoded values before encoding.
      See Also:

    • MIN_SINGLE_BYTE_VALUE

      public static final int MIN_SINGLE_BYTE_VALUE
      Minimum value that can be encoded as a single byte.
      See Also:

    • MAX_SINGLE_BYTE_VALUE

      public static final int MAX_SINGLE_BYTE_VALUE
      Maximum value that can be encoded as a single byte.
      See Also:

    • NEGATIVE_ADJUST

      public static final int NEGATIVE_ADJUST
      Adjustment applied to multi-byte encoded negative values before encoding.
      See Also:

    • POSITIVE_ADJUST

      public static final int POSITIVE_ADJUST
      Adjustment applied to multi-byte encoded positive values before encoding.
      See Also:

  • Method Details

    • encode

      public static ByteData encode(long value)
      Encode the given value.
      Parameters:
      value - value to encode
      Returns:
      encoded value

    • write

      public static void write(ByteData.Writer writer, long value)
      Encode the given value.
      Parameters:
      writer - destination for the encoded value
      value - value to encode
      Throws:
      IllegalArgumentException - if writer is null

    • write

      public static void write(OutputStream out, long value) throws IOException
      Encode the given value.
      Parameters:
      out - destination for the encoded value
      value - value to encode
      Throws:
      IOException - if an I/O error occurs
      IllegalArgumentException - if out is null

    • write

      public static void write(ByteBuffer buf, long value)
      Encode the given value.
      Parameters:
      buf - destination for the encoded value
      value - value to encode
      Throws:
      BufferOverflowException - if buf overflows
      ReadOnlyBufferException - if buf is read-only
      IllegalArgumentException - if buf is null

    • encodeLength

      public static int encodeLength(long value)
      Determine the length (in bytes) of the encoded value.
      Parameters:
      value - value to encode
      Returns:
      the length of the encoded value, a value between one and MAX_ENCODED_LENGTH

    • decode

      public static long decode(ByteData data)
      Decode the given value.
      Parameters:
      data - encoded value
      Returns:
      decoded value
      Throws:
      IllegalArgumentException - if data contains an invalid encoding, or extra trailing garbage
      IllegalArgumentException - if data is null

    • read

      public static long read(ByteData.Reader reader)
      Read and decode a value from the input.
      Parameters:
      reader - input holding an encoded value
      Returns:
      the decoded value
      Throws:
      IllegalArgumentException - if an invalid encoding is encountered
      IllegalArgumentException - if the encoded value is truncated
      IllegalArgumentException - if reader is null

    • read

      public static long read(InputStream input) throws IOException
      Read and decode a value from the given InputStream.
      Parameters:
      input - input source for the encoded value
      Returns:
      the decoded value
      Throws:
      IOException - if an I/O error occurs
      EOFException - if an unexpected EOF is encountered
      IllegalArgumentException - if an invalid encoding is encountered
      IllegalArgumentException - if input is null

    • read

      public static long read(ByteBuffer buf)
      Read and decode a value from the given ByteBuffer.
      Parameters:
      buf - input source for the encoded value
      Returns:
      the decoded value
      Throws:
      BufferUnderflowException - if buf underflows
      IllegalArgumentException - if an invalid encoding is encountered
      IllegalArgumentException - if buf is null

    • skip

      public static void skip(ByteData.Reader reader)
      Skip a value from the input.
      Parameters:
      reader - input holding an encoded value
      Throws:
      IllegalArgumentException - if the first byte is 0xff
      IllegalArgumentException - if reader is null

    • decodeLength

      public static int decodeLength(int first)
      Determine the length (in bytes) of an encoded value based on the first byte.
      Parameters:
      first - first byte of encoded value (in lower eight bits; other bits are ignored)
      Returns:
      the length of the encoded value (including first)
      Throws:
      IllegalArgumentException - if the first byte is 0xff

    • main

      public static void main(String[] args)
      Test routine.
      Parameters:
      args - command line arguments