Package net.solarnetwork.util

Class ByteUtils

java.lang.Object
net.solarnetwork.util.ByteUtils
public final class ByteUtils extends Object
Utilities for working with bytes.

Some routines have been adapted from Apache Commons Codec's Hex.java class.

Since:
1.54
Version:
1.3
Author:
matt

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Charset
    ASCII
    The ASCII character set.
    static final String
    ASCII_CHARSET
    The ASCII character set name.
    static final Charset
    LATIN1
    The ISO-8859-1 (ISO-LATIN-1) character set.
    static final String
    LATIN1_CHARSET
    The ISO-8859-1 (ISO-LATIN-1) character set name.
    static final Charset
    UTF8
    The UTF-8 character set.
    static final String
    UTF8_CHARSET
    The UTF-8 character set name.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ByteUtils()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static byte[]
    byteArray(Byte[] array)
    Convert an array of bytes to Byte objects.
    static byte[]
    byteArray(Byte[] array, byte nullValue)
    Convert an array of bytes to Byte objects.
    static byte[]
    decodeHexPadStart(char[] chars)
    Convert a hex-encoded string to a byte array.
    static byte[]
    decodeHexString(String s)
    Convert a hex-encoded string to a byte array.
    static char[]
    encodeHex(byte b, char[] toDigits, char[] dest, int destIndex)
    Encode a single byte as hex characters.
    static char[]
    encodeHexLowerCase(byte b, char[] dest, int destIndex)
    Encode a single byte as lower-case hex characters.
    static String
    encodeHexString(byte[] data, int fromIndex, int toIndex, boolean space)
    Encode a byte array into a hex-encoded upper-case string.
    static String
    encodeHexString(byte[] data, int fromIndex, int toIndex, boolean space, boolean lowerCase)
    Encode a byte array into a hex-encoded upper-case string.
    static char[]
    encodeHexUpperCase(byte b, char[] dest, int destIndex)
    Encode a single byte as upper-case hex characters.
    static void
    encodeInt16(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
    Encode a 16-bit signed integer value into a raw byte value.
    static void
    encodeInt32(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
    Encode a 32-bit signed integer value into a raw byte value.
    static void
    encodeInt64(long l, byte[] dest, int offset, ByteOrdering byteOrder)
    Encode a 64-bit signed integer value into a raw byte value.
    static void
    encodeInt64(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
    Encode a 64-bit signed integer value into a raw byte value.
    static void
    encodeInt8(Number n, byte[] dest, int offset)
    Encode an 8-bit signed integer value into a raw byte value.
    static void
    encodeUnsignedInt16(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
    Encode a 16-bit unsigned integer value into a raw byte value.
    static void
    encodeUnsignedInt32(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
    Encode a 32-bit unsigned integer value into a raw byte value.
    static void
    encodeUnsignedInt64(long l, byte[] dest, int offset, ByteOrdering byteOrder)
    Encode a 64-bit unsigned integer value into a raw byte value.
    static void
    encodeUnsignedInt64(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
    Encode a 64-bit unsigned integer value into a raw byte value.
    static void
    encodeUnsignedInt8(Number n, byte[] dest, int offset)
    Encode an 8-bit unsigned integer value into a raw byte value.
    static String
    humanReadableByteCount(long count)
    Format a byte count in a "human readable" format, with progressively larger binary units (powers of 1024).
    static Byte[]
    objectArray(byte[] array)
    Convert an array of bytes to Byte objects.
    static byte[]
    parseBytes(byte[] data, int offset, int length, ByteOrdering byteOrder)
    Parse any number of byte values as a series of bytes.
    static BigDecimal
    parseDecimalCharacterString(byte[] data, int offset, int length, ByteOrdering byteOrder, Charset charset)
    Parse any number of byte values representing characters into a decimal string.
    static Float
    parseFloat32(byte d, byte c, byte b, byte a)
    Parse an IEEE-754 32-bit float value from raw byte values.
    static Double
    parseFloat64(byte h, byte g, byte f, byte e, byte d, byte c, byte b, byte a)
    Parse an IEEE-754 64-bit floating point value from raw byte values.
    static Short
    parseInt16(byte hi, byte lo)
    Parse a 16-bit signed integer value from a raw byte value.
    static Integer
    parseInt32(byte d, byte c, byte b, byte a)
    Parse a 32-bit signed integer value from raw byte values.
    static Long
    parseInt64(byte h, byte g, byte f, byte e, byte d, byte c, byte b, byte a)
    Parse a 64-bit signed integer value from raw byte values.
    static Byte
    parseInt8(byte b)
    Parse an 8-bit signed integer value from a raw byte value.
    static BigInteger
    parseInteger(byte[] data, int offset, int length, ByteOrdering byteOrder)
    Parse any number of byte values into an signed BigInteger.
    static Number
    parseNumber(BitDataType dataType, byte[] data, int offset, int length, ByteOrdering byteOrder)
    Parse a number from raw byte data.
    static Number
    parseNumber(BitDataType dataType, byte[] data, int offset, ByteOrdering byteOrder)
    Parse a number from raw byte data.
    static Integer
    parseUnsignedInt16(byte hi, byte lo)
    Parse a 16-bit unsigned integer value from a raw byte value.
    static Long
    parseUnsignedInt32(byte d, byte c, byte b, byte a)
    Parse a 32-bit unsigned integer value from raw byte values.
    static BigInteger
    parseUnsignedInt64(byte h, byte g, byte f, byte e, byte d, byte c, byte b, byte a)
    Construct an 64-bit unsigned integer from raw byte values.
    static Short
    parseUnsignedInt8(byte b)
    Parse an 8-bit unsigned integer value from a raw byte value.
    static BigInteger
    parseUnsignedInteger(byte[] data, int offset, int length, ByteOrdering byteOrder)
    Parse any number of byte values into an unsigned BigInteger.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • UTF8_CHARSET

      public static final String UTF8_CHARSET
      The UTF-8 character set name.
      See Also:

    • UTF8

      public static final Charset UTF8
      The UTF-8 character set.

    • ASCII_CHARSET

      public static final String ASCII_CHARSET
      The ASCII character set name.
      See Also:

    • ASCII

      public static final Charset ASCII
      The ASCII character set.

    • LATIN1_CHARSET

      public static final String LATIN1_CHARSET
      The ISO-8859-1 (ISO-LATIN-1) character set name.
      Since:
      1.1
      See Also:

    • LATIN1

      public static final Charset LATIN1
      The ISO-8859-1 (ISO-LATIN-1) character set.
      Since:
      1.1

  • Constructor Details

    • ByteUtils

      public ByteUtils()

  • Method Details

    • encodeHex

      public static char[] encodeHex(byte b, char[] toDigits, char[] dest, int destIndex)
      Encode a single byte as hex characters.
      Parameters:
      b - the byte to encode
      toDigits - the hex alphabet to use
      dest - the destination character buffer to write the hex encoding to
      destIndex - the index within dest to write the hex encoding at, along with destIndex + 1
      Returns:
      the dest array

    • encodeHexUpperCase

      public static char[] encodeHexUpperCase(byte b, char[] dest, int destIndex)
      Encode a single byte as upper-case hex characters.
      Parameters:
      b - the byte to encode
      dest - the destination character buffer to write the hex encoding to
      destIndex - the index within dest to write the hex encoding at, along with destIndex + 1
      Returns:
      the dest array

    • encodeHexLowerCase

      public static char[] encodeHexLowerCase(byte b, char[] dest, int destIndex)
      Encode a single byte as lower-case hex characters.
      Parameters:
      b - the byte to encode
      dest - the destination character buffer to write the hex encoding to
      destIndex - the index within dest to write the hex encoding at, along with destIndex + 1
      Returns:
      the dest array

    • encodeHexString

      public static String encodeHexString(byte[] data, int fromIndex, int toIndex, boolean space)
      Encode a byte array into a hex-encoded upper-case string.
      Parameters:
      data - the data to encode as hex strings
      fromIndex - the starting index within data to encode (inclusive)
      toIndex - the ending index within data to encode (exclusive)
      space - true to add a single space character between each hex pair
      Returns:
      the string, never null

    • encodeHexString

      public static String encodeHexString(byte[] data, int fromIndex, int toIndex, boolean space, boolean lowerCase)
      Encode a byte array into a hex-encoded upper-case string.
      Parameters:
      data - the data to encode as hex strings
      fromIndex - the starting index within data to encode (inclusive)
      toIndex - the ending index within data to encode (exclusive)
      space - true to add a single space character between each hex
      lowerCase - true to use lower case, false for upper case pair
      Returns:
      the string, never null

    • decodeHexString

      public static byte[] decodeHexString(String s)
      Convert a hex-encoded string to a byte array.

      If the string does not have an even number of characters, a 0 will be inserted at the start of the string.

      Parameters:
      s - the string to decode
      Returns:
      the bytes, never null
      See Also:

    • decodeHexPadStart

      public static byte[] decodeHexPadStart(char[] chars)
      Convert a hex-encoded string to a byte array.

      If the string does not have an even number of characters, a 0 will be inserted at the start of the string.

      Parameters:
      chars - the characters to decode
      Returns:
      the bytes, never null

    • encodeInt8

      public static void encodeInt8(Number n, byte[] dest, int offset)
      Encode an 8-bit signed integer value into a raw byte value.
      Parameters:
      n - the number to encode
      dest - the destination to encode the number to
      offset - the offset within dest to encode the number to
      Throws:
      ArrayIndexOutOfBoundsException - if dest is not long enough to hold the number's byte value

    • encodeUnsignedInt8

      public static void encodeUnsignedInt8(Number n, byte[] dest, int offset)
      Encode an 8-bit unsigned integer value into a raw byte value.
      Parameters:
      n - the number to encode
      dest - the destination to encode the number to
      offset - the offset within dest to encode the number to
      Throws:
      ArrayIndexOutOfBoundsException - if dest is not long enough to hold the number's byte value

    • encodeInt16

      public static void encodeInt16(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
      Encode a 16-bit signed integer value into a raw byte value.
      Parameters:
      n - the number to encode
      dest - the destination to encode the number to
      offset - the offset within dest to encode the number to
      byteOrder - the byte order to encode into dest
      Throws:
      ArrayIndexOutOfBoundsException - if dest is not long enough to hold the number's byte value

    • encodeUnsignedInt16

      public static void encodeUnsignedInt16(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
      Encode a 16-bit unsigned integer value into a raw byte value.
      Parameters:
      n - the number to encode
      dest - the destination to encode the number to
      offset - the offset within dest to encode the number to
      byteOrder - the byte order to encode into dest
      Throws:
      ArrayIndexOutOfBoundsException - if dest is not long enough to hold the number's byte value

    • encodeInt32

      public static void encodeInt32(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
      Encode a 32-bit signed integer value into a raw byte value.
      Parameters:
      n - the number to encode
      dest - the destination to encode the number to
      offset - the offset within dest to encode the number to
      byteOrder - the byte order to encode into dest
      Throws:
      ArrayIndexOutOfBoundsException - if dest is not long enough to hold the number's byte value

    • encodeUnsignedInt32

      public static void encodeUnsignedInt32(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
      Encode a 32-bit unsigned integer value into a raw byte value.
      Parameters:
      n - the number to encode
      dest - the destination to encode the number to
      offset - the offset within dest to encode the number to
      byteOrder - the byte order to encode into dest
      Throws:
      ArrayIndexOutOfBoundsException - if dest is not long enough to hold the number's byte value

    • encodeInt64

      public static void encodeInt64(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
      Encode a 64-bit signed integer value into a raw byte value.
      Parameters:
      n - the number to encode
      dest - the destination to encode the number to
      offset - the offset within dest to encode the number to
      byteOrder - the byte order to encode into dest
      Throws:
      ArrayIndexOutOfBoundsException - if dest is not long enough to hold the number's byte value

    • encodeInt64

      public static void encodeInt64(long l, byte[] dest, int offset, ByteOrdering byteOrder)
      Encode a 64-bit signed integer value into a raw byte value.
      Parameters:
      l - the number to encode
      dest - the destination to encode the number to
      offset - the offset within dest to encode the number to
      byteOrder - the byte order to encode into dest
      Throws:
      ArrayIndexOutOfBoundsException - if dest is not long enough to hold the number's byte value

    • encodeUnsignedInt64

      public static void encodeUnsignedInt64(Number n, byte[] dest, int offset, ByteOrdering byteOrder)
      Encode a 64-bit unsigned integer value into a raw byte value.
      Parameters:
      n - the number to encode
      dest - the destination to encode the number to
      offset - the offset within dest to encode the number to
      byteOrder - the byte order to encode into dest
      Throws:
      ArrayIndexOutOfBoundsException - if dest is not long enough to hold the number's byte value

    • encodeUnsignedInt64

      public static void encodeUnsignedInt64(long l, byte[] dest, int offset, ByteOrdering byteOrder)
      Encode a 64-bit unsigned integer value into a raw byte value.
      Parameters:
      l - the number to encode
      dest - the destination to encode the number to
      offset - the offset within dest to encode the number to
      byteOrder - the byte order to encode into dest
      Throws:
      ArrayIndexOutOfBoundsException - if dest is not long enough to hold the number's byte value

    • parseNumber

      public static Number parseNumber(BitDataType dataType, byte[] data, int offset, ByteOrdering byteOrder)
      Parse a number from raw byte data.

      This method is suitable for fixed-length data types only.

      Parameters:
      dataType - the desired data type
      data - an array of byte values
      offset - an offset within data to start reading from
      byteOrder - the byte order of data
      Returns:
      the parsed number, or null if data is null or not long enough for the requested data type
      Throws:
      IllegalArgumentException - if dataType is not supported

    • parseNumber

      public static Number parseNumber(BitDataType dataType, byte[] data, int offset, int length, ByteOrdering byteOrder)
      Parse a number from raw byte data.
      Parameters:
      dataType - the desired data type
      data - an array of byte values
      offset - an offset within data to start reading from
      length - for types of variable length, the number of bytes to consume; for types of fixed length this value is ignored
      byteOrder - the byte order of data
      Returns:
      the parsed number, or null if data is null or not long enough for the requested data type
      Throws:
      IllegalArgumentException - if dataType is not supported

    • parseInt8

      public static Byte parseInt8(byte b)
      Parse an 8-bit signed integer value from a raw byte value.
      Parameters:
      b - bits 7-0
      Returns:
      the parsed integer, never null

    • parseUnsignedInt8

      public static Short parseUnsignedInt8(byte b)
      Parse an 8-bit unsigned integer value from a raw byte value.

      Note a Short is returned to support unsigned 8-bit values.

      Parameters:
      b - bits 7-0
      Returns:
      the parsed integer, never null

    • parseInt16

      public static Short parseInt16(byte hi, byte lo)
      Parse a 16-bit signed integer value from a raw byte value.
      Parameters:
      hi - bits 15-8
      lo - bits 7-0
      Returns:
      the parsed integer, never null

    • parseUnsignedInt16

      public static Integer parseUnsignedInt16(byte hi, byte lo)
      Parse a 16-bit unsigned integer value from a raw byte value.

      Note a Integer is returned to support unsigned 16-bit values.

      Parameters:
      hi - bits 15-8
      lo - bits 7-0
      Returns:
      the parsed integer, never null

    • parseInt32

      public static Integer parseInt32(byte d, byte c, byte b, byte a)
      Parse a 32-bit signed integer value from raw byte values.
      Parameters:
      d - bits 31-24
      c - bits 23-16
      b - bits 15-8
      a - bits 7-0
      Returns:
      the parsed integer, never null

    • parseUnsignedInt32

      public static Long parseUnsignedInt32(byte d, byte c, byte b, byte a)
      Parse a 32-bit unsigned integer value from raw byte values.

      Note a Long is returned to support unsigned 32-bit values.

      Parameters:
      d - bits 31-24
      c - bits 23-16
      b - bits 15-8
      a - bits 7-0
      Returns:
      the parsed integer, never null

    • parseInt64

      public static Long parseInt64(byte h, byte g, byte f, byte e, byte d, byte c, byte b, byte a)
      Parse a 64-bit signed integer value from raw byte values.
      Parameters:
      h - bits 63-56
      g - bits 55-48
      f - bits 47-40
      e - bits 39-32
      d - bits 31-24
      c - bits 23-16
      b - bits 15-8
      a - bits 7-0
      Returns:
      the parsed integer, never null

    • parseUnsignedInt64

      public static BigInteger parseUnsignedInt64(byte h, byte g, byte f, byte e, byte d, byte c, byte b, byte a)
      Construct an 64-bit unsigned integer from raw byte values.

      Note a BigInteger is returned to support unsigned 64-bit values.

      Parameters:
      h - bits 63-56
      g - bits 55-48
      f - bits 47-40
      e - bits 39-32
      d - bits 31-24
      c - bits 23-16
      b - bits 15-8
      a - bits 7-0
      Returns:
      the parsed integer, never null

    • parseFloat32

      public static Float parseFloat32(byte d, byte c, byte b, byte a)
      Parse an IEEE-754 32-bit float value from raw byte values.
      Parameters:
      d - bits 31-24
      c - bits 23-16
      b - bits 15-8
      a - bits 7-0
      Returns:
      the parsed float, or null if not available or parsed float is NaN

    • parseFloat64

      public static Double parseFloat64(byte h, byte g, byte f, byte e, byte d, byte c, byte b, byte a)
      Parse an IEEE-754 64-bit floating point value from raw byte values.
      Parameters:
      h - bits 63-56
      g - bits 55-48
      f - bits 47-40
      e - bits 39-32
      d - bits 31-24
      c - bits 23-16
      b - bits 15-8
      a - bits 7-0
      Returns:
      the parsed float, or null if the result is NaN

    • parseBytes

      public static byte[] parseBytes(byte[] data, int offset, int length, ByteOrdering byteOrder)
      Parse any number of byte values as a series of bytes.
      Parameters:
      data - the data
      offset - the byte offset to start from
      length - the number of bytes to consume
      byteOrder - the byte order of data
      Returns:
      the parsed bytes, never null

    • parseInteger

      public static BigInteger parseInteger(byte[] data, int offset, int length, ByteOrdering byteOrder)
      Parse any number of byte values into an signed BigInteger.
      Parameters:
      data - the data to parse
      offset - the offset within data to start reading from
      length - the number of bytes to consume
      byteOrder - the byte order of data
      Returns:
      the integer value

    • parseUnsignedInteger

      public static BigInteger parseUnsignedInteger(byte[] data, int offset, int length, ByteOrdering byteOrder)
      Parse any number of byte values into an unsigned BigInteger.
      Parameters:
      data - the data to parse
      offset - the offset within data to start reading from
      length - the number of bytes to consume
      byteOrder - the byte order of data
      Returns:
      the integer value

    • parseDecimalCharacterString

      public static BigDecimal parseDecimalCharacterString(byte[] data, int offset, int length, ByteOrdering byteOrder, Charset charset)
      Parse any number of byte values representing characters into a decimal string.

      This method interprets the data bytes as a string encoded as charset, whose string value contains a string decimal number. For example, a big-endian ASCII encoded byte array of 0x31 0x30 0x32 0x34 is interpreted as the string "1024" which is then parsed as a BigDecimal.

      Parameters:
      data - the data to parse
      offset - the offset within data to start reading from
      length - the number of bytes to consume
      byteOrder - the byte order of data
      charset - the character set to interpret the bytes as
      Returns:
      the number

    • objectArray

      public static Byte[] objectArray(byte[] array)
      Convert an array of bytes to Byte objects.
      Parameters:
      array - the array to convert
      Returns:
      the converted array, or null if array is null
      Since:
      1.1

    • byteArray

      public static byte[] byteArray(Byte[] array)
      Convert an array of bytes to Byte objects.

      0 will be used for any null object values.

      Parameters:
      array - the array to convert
      Returns:
      the converted array, or null if array is null
      Since:
      1.1

    • byteArray

      public static byte[] byteArray(Byte[] array, byte nullValue)
      Convert an array of bytes to Byte objects.
      Parameters:
      array - the array to convert
      nullValue - the byte value to use for null Byte values
      Returns:
      the converted array, or null if array is null
      Since:
      1.1

    • humanReadableByteCount

      public static String humanReadableByteCount(long count)
      Format a byte count in a "human readable" format, with progressively larger binary units (powers of 1024).

      For example this method will return 6.8 MiB for input of 7077888.

      Adapted from @aioobe on Stack Overflow

      Parameters:
      count - the byte count to format
      Returns:
      the count formatted as a string
      Since:
      1.3