Package io.permazen.util

Class ByteUtil

java.lang.Object
io.permazen.util.ByteUtil
public final class ByteUtil extends Object
Byte manipulation utilities.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Comparator<byte[]>
    COMPARATOR
    Comparator that compares two byte arrays lexicographically using unsigned values.
    static final byte[]
    EMPTY
    An empty byte array.
    static final Converter<byte[],String>
    STRING_CONVERTER
    A Converter that converts between byte[] arrays and hexadecimal Strings.

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    compare(byte[] b1, byte[] b2)
    Compare two byte arrays lexicographically using unsigned values.
    static byte[]
    fromDouble(double value)
    Performs the inverse of toDouble().
    static byte[]
    getKeyAfterPrefix(byte[] prefix)
    Get the first key that would be greater than the given key in unsigned lexicographic ordering and that does not have the given key as a prefix.
    static byte[]
    getNextKey(byte[] key)
    Get the next key greater than the given key in unsigned lexicographic ordering.
    static boolean
    isConsecutive(byte[] key1, byte[] key2)
    Determine whether key2 is the next key after key1.
    static boolean
    isPrefixOf(byte[] prefix, byte[] value)
    Determine if the first of two byte[] arrays is a prefix of the second.
    static byte[]
    max(byte[] b1, byte[] b2)
    Determine the larger of two byte arrays when compared lexicographically using unsigned values.
    static byte[]
    min(byte[] b1, byte[] b2)
    Determine the smaller of two byte arrays when compared lexicographically using unsigned values.
    static byte[]
    parse(String text)
    Decode a hexadecimal String into a byte[] array.
    static int
    readInt(ByteReader reader)
    Read an int as four big-endian bytes.
    static long
    readLong(ByteReader reader)
    Read a long as eight big-endian bytes.
    static double
    toDouble(byte[] key)
    Map a byte[] array into the range [0.0, 1.0) in a way that preserves order.
    static String
    toString(byte[] buf)
    Convert a byte array into a string of hex digits, or "null" if buf is null.
    static void
    writeInt(ByteWriter writer, int value)
    Write an int as four big-endian bytes.
    static void
    writeLong(ByteWriter writer, long value)
    Write a long as eight big-endian bytes.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • EMPTY

      public static final byte[] EMPTY
      An empty byte array. This is the minimum value according to COMPARATOR.

    • COMPARATOR

      public static final Comparator<byte[]> COMPARATOR
      Comparator that compares two byte arrays lexicographically using unsigned values.

    • STRING_CONVERTER

      public static final Converter<byte[],String> STRING_CONVERTER
      A Converter that converts between byte[] arrays and hexadecimal Strings.

  • Method Details

    • compare

      public static int compare(byte[] b1, byte[] b2)
      Compare two byte arrays lexicographically using unsigned values.
      Parameters:
      b1 - first byte array
      b2 - second byte array
      Returns:
      -1 if b1 < b2, 1 if b1 > b2, or zero if b1 = b2
      Throws:
      NullPointerException - if b1 or b2 is null

    • min

      public static byte[] min(byte[] b1, byte[] b2)
      Determine the smaller of two byte arrays when compared lexicographically using unsigned values.
      Parameters:
      b1 - first byte array
      b2 - second byte array
      Returns:
      b1 if b1 <= b2, otherwise b2
      Throws:
      NullPointerException - if b1 or b2 is null

    • max

      public static byte[] max(byte[] b1, byte[] b2)
      Determine the larger of two byte arrays when compared lexicographically using unsigned values.
      Parameters:
      b1 - first byte array
      b2 - second byte array
      Returns:
      b1 if b1 >= b2, otherwise b2
      Throws:
      NullPointerException - if b1 or b2 is null

    • isPrefixOf

      public static boolean isPrefixOf(byte[] prefix, byte[] value)
      Determine if the first of two byte[] arrays is a prefix of the second.
      Parameters:
      prefix - prefix to check
      value - value to check for having prefix as a prefix
      Returns:
      true if prefix is a prefix of value
      Throws:
      NullPointerException - if prefix or value is null

    • getNextKey

      public static byte[] getNextKey(byte[] key)
      Get the next key greater than the given key in unsigned lexicographic ordering. This creates a new key simply by appending a 0x00 byte to the data contained in the given key.
      Parameters:
      key - previous key
      Returns:
      next key after key
      Throws:
      NullPointerException - if key is null

    • isConsecutive

      public static boolean isConsecutive(byte[] key1, byte[] key2)
      Determine whether key2 is the next key after key1.
      Parameters:
      key1 - first key
      key2 - second key
      Returns:
      true if key2 immediately follows key1
      Throws:
      NullPointerException - if either parameter is null

    • getKeyAfterPrefix

      public static byte[] getKeyAfterPrefix(byte[] prefix)
      Get the first key that would be greater than the given key in unsigned lexicographic ordering and that does not have the given key as a prefix.
      Parameters:
      prefix - lower bound prefix key
      Returns:
      next key not having prefix as a prefix
      Throws:
      IllegalArgumentException - if prefix has zero length
      IllegalArgumentException - if prefix contains only 0xff bytes
      NullPointerException - if prefix is null

    • toString

      public static String toString(byte[] buf)
      Convert a byte array into a string of hex digits, or "null" if buf is null.
      Parameters:
      buf - bytes
      Returns:
      string encoding of buf
      See Also:

    • parse

      public static byte[] parse(String text)
      Decode a hexadecimal String into a byte[] array. The string must have an even number of digits and contain no other characters (e.g., whitespace).
      Parameters:
      text - string previously encoded by toString(byte[])
      Returns:
      byte[] decoding of text
      Throws:
      IllegalArgumentException - if any non-hexadecimal characters are found or the number of characters is odd
      NullPointerException - if text is null
      See Also:

    • readInt

      public static int readInt(ByteReader reader)
      Read an int as four big-endian bytes.
      Parameters:
      reader - input
      Returns:
      decoded integer
      Throws:
      IndexOutOfBoundsException - if less than four bytes remain in reader
      NullPointerException - if reader is null
      See Also:

    • writeInt

      public static void writeInt(ByteWriter writer, int value)
      Write an int as four big-endian bytes.
      Parameters:
      writer - byte destination
      value - value to write
      Throws:
      NullPointerException - if writer is null
      See Also:

    • readLong

      public static long readLong(ByteReader reader)
      Read a long as eight big-endian bytes.
      Parameters:
      reader - input
      Returns:
      decoded long
      Throws:
      IndexOutOfBoundsException - if less than eight bytes remain in reader
      See Also:

    • writeLong

      public static void writeLong(ByteWriter writer, long value)
      Write a long as eight big-endian bytes.
      Parameters:
      writer - byte destination
      value - value to write
      Throws:
      NullPointerException - if writer is null
      See Also:

    • toDouble

      public static double toDouble(byte[] key)
      Map a byte[] array into the range [0.0, 1.0) in a way that preserves order.

      This allows calculations that require a notion of "distance" between two keys.

      This method simply maps the first 6.5 bytes of key into the 52 mantissa bits of a double value. Obviously, the mapping is not reversible: some keys will map equal double values, but otherwise the mapping is order-preserving.

      Parameters:
      key - input key
      Returns:
      nearest corresponding value between zero (inclusive) and one (exclusive)
      Throws:
      IllegalArgumentException - if key is null

    • fromDouble

      public static byte[] fromDouble(double value)
      Performs the inverse of toDouble().

      The mapping of toDouble() is not reversible: some keys will map to the same double value, so this method does not always return the original byte[] key.

      Parameters:
      value - input value; must be >= 0.0 and < 1.0
      Returns:
      a byte[] key that maps to value
      Throws:
      IllegalArgumentException - if value is not a number between zero (inclusive) and one (exclusive)