Package io.permazen.util

Class UnsignedIntEncoder

java.lang.Object
io.permazen.util.UnsignedIntEncoder
public final class UnsignedIntEncoder extends Object
Encodes unsigned (i.e., non-negative) int values to/from self-delimited binary, preserving sort order, and such that the length of the encoding is optimized for values near zero and encoded values never begin with 0xff.

The encoding uses a simple prefixing format:

Encoding Format
Encoded Bytes Value
0x00 ... 0xfa Same
0xfb 0xWW 0xWW + 0xfb
0xfc 0xWW 0xXX 0xWWXX + 0xfb
0xfd 0xWW 0xXX 0xYY 0xWWXXYY + 0xfb
0xfe 0xWW 0xXX 0xYY 0xZZ 0xWWXXYYZZ + 0xfb
0xff Illegal

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    MAX_ENCODED_LENGTH
    Maximum possible length of an encoded value.
    static final int
    MIN_MULTI_BYTE_VALUE
    Minimum value that triggers a multi-byte encoding.

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    decode(byte[] data)
    Decode the given value.
    static int
    decodeLength(int first)
    Determine the length (in bytes) of an encoded value based on the first byte.
    static byte[]
    encode(int value)
    Encode the given value.
    static int
    encode(int value, byte[] buf, int off)
    Encode the given value and write the encoded bytes into the given buffer.
    static int
    encodeLength(int value)
    Determine the length (in bytes) of the encoded value.
    static void
    main(String[] args)
    Test routine.
    static int
    read(ByteReader reader)
    Read and decode a value from the input.
    static int
    read(InputStream input)
    Read and decode a value from the given InputStream.
    static int
    read(ByteBuffer buf)
    Read and decode a value from the given ByteBuffer.
    static void
    skip(ByteReader reader)
    Skip a value from the input.
    static void
    write(ByteWriter writer, int value)
    Encode the given value to the output.
    static void
    write(OutputStream out, int value)
    Encode the given value and write it to the given OutputStream.
    static void
    write(ByteBuffer buf, int value)
    Encode the given value and write it to the given ByteBuffer.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • MAX_ENCODED_LENGTH

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

    • MIN_MULTI_BYTE_VALUE

      public static final int MIN_MULTI_BYTE_VALUE
      Minimum value that triggers a multi-byte encoding.
      See Also:

  • Method Details

    • encode

      public static byte[] encode(int value)
      Encode the given value.
      Parameters:
      value - value to encode
      Returns:
      encoded value
      Throws:
      IllegalArgumentException - if value is negative

    • decode

      public static int decode(byte[] data)
      Decode the given value.
      Parameters:
      data - encoded value
      Returns:
      decoded value
      Throws:
      IllegalArgumentException - if bytes contains an invalid encoding, or extra trailing garbage

    • write

      public static void write(ByteWriter writer, int value)
      Encode the given value to the output.
      Parameters:
      writer - destination for the encoded value
      value - value to encode
      Throws:
      IllegalArgumentException - if value is negative

    • write

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

    • write

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

    • read

      public static int read(ByteReader reader)
      Read and decode a value from the input.
      Parameters:
      reader - input holding an encoded value
      Returns:
      the decoded value, always non-negative
      Throws:
      IllegalArgumentException - if the encoded value is truncated
      IllegalArgumentException - if an invalid encoding is encountered

    • read

      public static int 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
      NullPointerException - if input is null

    • read

      public static int 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
      NullPointerException - if buf is null

    • skip

      public static void skip(ByteReader reader)
      Skip a value from the input.
      Parameters:
      reader - input holding an encoded value

    • 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 lower eight bits of first equal 0xff

    • encodeLength

      public static int encodeLength(int 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
      Throws:
      IllegalArgumentException - if value is negative

    • encode

      public static int encode(int value, byte[] buf, int off)
      Encode the given value and write the encoded bytes into the given buffer.
      Parameters:
      value - value to encode
      buf - output buffer
      off - starting offset into output buffer
      Returns:
      the number of encoded bytes written
      Throws:
      IllegalArgumentException - if value is negative
      NullPointerException - if buf is null
      ArrayIndexOutOfBoundsException - if off is negative or the encoded value exceeds the given buffer

    • main

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