Class ByteData

java.lang.Object
io.permazen.util.ByteData
All Implemented Interfaces:
Comparable<ByteData>

public final class ByteData extends Object implements Comparable<ByteData>
Zero or more bytes in read-only form.

Instances are thread-safe and immutable.

Instances order themselves using unsigned lexical comparison.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    Reads out the data from an underlying ByteData instance.
    static final class 
    Gathers data from which to build a ByteData instance.
  • Method Summary

    Modifier and Type
    Method
    Description
    byte
    byteAt(int index)
    Obtain the byte at the given index.
    int
    Compare this instance with the given instance using using unsigned lexicographical comparison.
    Obtain an instance containing the concatenation of this instance and the given instance.
    static ByteData
    Obtain an empty instance.
    boolean
    Determine whether this instance has the given suffix.
    boolean
     
    static ByteData
    Return an instance decoded from the given string of hex digits.
    int
    Compute the hash code for this instance.
    boolean
    Determine whether this instance is empty, i.e., has zero bytes.
    Create a ByteData.Reader input stream from this instance.
    newReader(int off)
    Create a ByteData.Reader input stream from this instance starting at the given offset.
    Create a new ByteData.Writer using the default initial capacity.
    newWriter(int initialCapacity)
    Create a new ByteData.Writer using the given initial capacity.
    static int
    numEqual(ByteData data1, int off1, ByteData data2, int off2)
    Determine how many identical bytes there are at specified offsets in two instances.
    static ByteData
    of(byte... data)
    Obtain an instance containing a copy of the given byte[] array.
    static ByteData
    of(byte[] data, int off, int len)
    Obtain an instance containing a copy of the given byte[] array region.
    static ByteData
    of(int... data)
    Obtain an instance containing the given byte data expressed as integers.
    int
    Get the number of bytes in this instance.
    boolean
    Determine whether this instance has the given prefix.
    Create an IntStream from this instance.
    substring(int beginIndex)
    Obtain an instance containing the subsequence of this instance starting at the given offset.
    substring(int beginIndex, int endIndex)
    Obtain an instance containing the subsequence of this instance between the given offsets.
    byte[]
    Obtain the data in this instance as a byte[] array.
    Return the data in this instance as a string of lowercase hex digits.
    toHex(int limit)
    Return the data in this instance as a string of lowercase hex digits, truncated if necessary.
     
    int
    ubyteAt(int index)
    Obtain the byte at the given index as an unsigned value.
    void
    writeTo(byte[] dest, int off)
    Write the data in this instance into a byte[] array.
    void
    Write the data to the given output stream.
    void
    Write the data into the given byte buffer at its current position (relative write).
    void
    writeTo(ByteBuffer buf, int index)
    Write the data into the given byte buffer at the specified position (absolute write).
    static ByteData
    zeros(int len)
    Obtain an instance containing the given number of zero bytes.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Method Details

    • of

      public static ByteData of(byte... data)
      Obtain an instance containing a copy of the given byte[] array.
      Parameters:
      data - byte data
      Returns:
      instance containing a copy of data
      Throws:
      IllegalArgumentException - if data is null
    • of

      public static ByteData of(int... data)
      Obtain an instance containing the given byte data expressed as integers.
      Parameters:
      data - bytes expressed as integers; only the lower 8 bits of each value are used
      Returns:
      instance containing a copy of data
      Throws:
      IllegalArgumentException - if data is null
    • of

      public static ByteData of(byte[] data, int off, int len)
      Obtain an instance containing a copy of the given byte[] array region.
      Parameters:
      data - byte data
      off - offset into data
      len - number of bytes
      Returns:
      instance containing a copy of the specified region of data
      Throws:
      IllegalArgumentException - if data is null
      IndexOutOfBoundsException - if off and/or len is invalid
    • fromHex

      public static ByteData fromHex(String hex)
      Return an instance decoded from the given string of hex digits.

      Digits greater than 9 may be uppercase or lowercase.

      Parameters:
      hex - zero or more hexadeximal digits
      Returns:
      hex decoded as hexadeximal
      Throws:
      IllegalArgumentException - if any character in hex is not a hex digit
      IllegalArgumentException - if hex does not have even length
      IllegalArgumentException - if hex is null
    • empty

      public static ByteData empty()
      Obtain an empty instance.
      Returns:
      an empty instance
    • zeros

      public static ByteData zeros(int len)
      Obtain an instance containing the given number of zero bytes.
      Parameters:
      len - number of zero bytes
      Returns:
      instance containing len zero bytes
      Throws:
      IllegalArgumentException - if len is negative
    • newWriter

      public static ByteData.Writer newWriter()
      Create a new ByteData.Writer using the default initial capacity.
      Returns:
      new data writer
    • newWriter

      public static ByteData.Writer newWriter(int initialCapacity)
      Create a new ByteData.Writer using the given initial capacity.
      Parameters:
      initialCapacity - intiial buffer capcity
      Returns:
      new data writer
      Throws:
      IllegalArgumentException - if initialCapacity is negative
    • numEqual

      public static int numEqual(ByteData data1, int off1, ByteData data2, int off2)
      Determine how many identical bytes there are at specified offsets in two instances.

      A starting offset is given for each instance. This method returns the number of consecutive pairs of bytes that are equal in both instances, starting at the corresponding offsets. The comparison stops when a non-equal pair of bytes is encountered, or the end of either array is reached.

      Parameters:
      data1 - first instance
      data2 - first instance
      off1 - starting offset in data1
      off2 - starting offset in data2
      Returns:
      the number of bytes that agree starting at off1 in data1 and off2 in data2
      Throws:
      IllegalArgumentException - if data1 or data2 is null
      IllegalArgumentException - if off1 or off2 is invalid
    • stream

      public IntStream stream()
      Create an IntStream from this instance.
      Returns:
      stream of integer values in the range 0..255
    • newReader

      public ByteData.Reader newReader()
      Create a ByteData.Reader input stream from this instance.
      Returns:
      data input stream
    • newReader

      public ByteData.Reader newReader(int off)
      Create a ByteData.Reader input stream from this instance starting at the given offset.

      Equivalent to: substring(off).newReader().

      Parameters:
      off - starting offset
      Returns:
      data input stream starting at offset off
      Throws:
      IndexOutOfBoundsException - if off is invalid
    • toHex

      public String toHex()
      Return the data in this instance as a string of lowercase hex digits.
      Returns:
      this instance's data in hexadecimal
      Throws:
      IndexOutOfBoundsException - if the resulting string length would exceed Integer.MAX_VALUE
    • toHex

      public String toHex(int limit)
      Return the data in this instance as a string of lowercase hex digits, truncated if necessary.

      If there are more than limit bytes to display, then this will truncate the result and add an ellipsis.

      Parameters:
      limit - maximum number bytes to display
      Returns:
      up to limit bytes of this instance's data in hexadecimal
      Throws:
      IndexOutOfBoundsException - if the resulting string length would exceed Integer.MAX_VALUE
      IllegalArgumentException - if limit is negative
    • byteAt

      public byte byteAt(int index)
      Obtain the byte at the given index.
      Parameters:
      index - index into byte data
      Returns:
      the byte at index
      Throws:
      IndexOutOfBoundsException - if index is invalid
    • ubyteAt

      public int ubyteAt(int index)
      Obtain the byte at the given index as an unsigned value.
      Parameters:
      index - index into byte data
      Returns:
      the byte at index as a integer in the range 0 to 255
      Throws:
      IndexOutOfBoundsException - if index is invalid
    • size

      public int size()
      Get the number of bytes in this instance.
      Returns:
      number of bytes
    • isEmpty

      public boolean isEmpty()
      Determine whether this instance is empty, i.e., has zero bytes.
      Returns:
      true if empty
    • substring

      public ByteData substring(int beginIndex)
      Obtain an instance containing the subsequence of this instance starting at the given offset.
      Parameters:
      beginIndex - starting offset (inclusive)
      Returns:
      substring of this instance from beginIndex to the end of this instance
      Throws:
      IndexOutOfBoundsException - if beginIndex is invalid
    • substring

      public ByteData substring(int beginIndex, int endIndex)
      Obtain an instance containing the subsequence of this instance between the given offsets.
      Parameters:
      beginIndex - starting offset (inclusive)
      endIndex - ending offset (exclusive)
      Returns:
      substring of this instance from beginIndex to endIndex
      Throws:
      IndexOutOfBoundsException - if beginIndex and/or endIndex is invalid
    • concat

      public ByteData concat(ByteData next)
      Obtain an instance containing the concatenation of this instance and the given instance.
      Parameters:
      next - the instance to append
      Returns:
      concatenation of this instance followed by next
      Throws:
      IllegalArgumentException - if next is null
      IllegalArgumentException - if the concatenation would be longer than Integer.MAX_VALUE
    • startsWith

      public boolean startsWith(ByteData prefix)
      Determine whether this instance has the given prefix.
      Parameters:
      prefix - prefix data
      Returns:
      true if this instance starts with prefix
      Throws:
      IllegalArgumentException - if prefix is null
    • endsWith

      public boolean endsWith(ByteData suffix)
      Determine whether this instance has the given suffix.
      Parameters:
      suffix - suffix data
      Returns:
      true if this instance ends with suffix
      Throws:
      IllegalArgumentException - if suffix is null
    • toByteArray

      public byte[] toByteArray()
      Obtain the data in this instance as a byte[] array.
      Returns:
      byte[] array containing a copy of this instance's data
    • writeTo

      public void writeTo(byte[] dest, int off)
      Write the data in this instance into a byte[] array.
      Parameters:
      dest - destination for data
      off - offset into dest to write
      Throws:
      IndexOutOfBoundsException - if off is invalid
      IllegalArgumentException - if dest is null
    • writeTo

      public void writeTo(OutputStream output) throws IOException
      Write the data to the given output stream.
      Parameters:
      output - destination for data
      Throws:
      IOException - if an I/O error occurs
      IllegalArgumentException - if output is null
    • writeTo

      public void writeTo(ByteBuffer buf)
      Write the data into the given byte buffer at its current position (relative write).
      Parameters:
      buf - destination for data
      Throws:
      BufferOverflowException - if buf has insufficient space
      ReadOnlyBufferException - if buf is read only
      IllegalArgumentException - if buf is null
    • writeTo

      public void writeTo(ByteBuffer buf, int index)
      Write the data into the given byte buffer at the specified position (absolute write).
      Parameters:
      buf - destination for data
      index - absolute index in buf at which to write the data
      Throws:
      BufferOverflowException - if buf has insufficient space
      ReadOnlyBufferException - if buf is read only
      IndexOutOfBoundsException - if index is invalid
      IllegalArgumentException - if buf is null
    • compareTo

      public int compareTo(ByteData that)
      Compare this instance with the given instance using using unsigned lexicographical comparison.
      Specified by:
      compareTo in interface Comparable<ByteData>
    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Compute the hash code for this instance.

      This returns the same hash code as Arrays.hashCode(byte[]) would on the result from toByteArray().

      Overrides:
      hashCode in class Object
    • toString

      public String toString()
      Overrides:
      toString in class Object