Package io.permazen.util
Class ByteData
java.lang.Object
io.permazen.util.ByteData
- All Implemented Interfaces:
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 -
Method Summary
Modifier and TypeMethodDescriptionbyte
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
empty()
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
hashCode()
Compute the hash code for this instance.boolean
isEmpty()
Determine whether this instance is empty, i.e., has zero bytes.Create aByteData.Reader
input stream from this instance.newReader
(int off) Create aByteData.Reader
input stream from this instance starting at the given offset.static ByteData.Writer
Create a newByteData.Writer
using the default initial capacity.static ByteData.Writer
newWriter
(int initialCapacity) Create a newByteData.Writer
using the given initial capacity.static int
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 givenbyte[]
array.static ByteData
of
(byte[] data, int off, int len) Obtain an instance containing a copy of the givenbyte[]
array region.static ByteData
of
(int... data) Obtain an instance containing the given byte data expressed as integers.int
size()
Get the number of bytes in this instance.boolean
startsWith
(ByteData prefix) Determine whether this instance has the given prefix.stream()
Create anIntStream
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 abyte[]
array.toHex()
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.toString()
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 abyte[]
array.void
writeTo
(OutputStream output) Write the data to the given output stream.void
writeTo
(ByteBuffer buf) 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.
-
Method Details
-
of
Obtain an instance containing a copy of the givenbyte[]
array.- Parameters:
data
- byte data- Returns:
- instance containing a copy of
data
- Throws:
IllegalArgumentException
- ifdata
is null
-
of
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
- ifdata
is null
-
of
Obtain an instance containing a copy of the givenbyte[]
array region.- Parameters:
data
- byte dataoff
- offset intodata
len
- number of bytes- Returns:
- instance containing a copy of the specified region of
data
- Throws:
IllegalArgumentException
- ifdata
is nullIndexOutOfBoundsException
- ifoff
and/orlen
is invalid
-
fromHex
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 inhex
is not a hex digitIllegalArgumentException
- ifhex
does not have even lengthIllegalArgumentException
- ifhex
is null
-
empty
Obtain an empty instance.- Returns:
- an empty instance
-
zeros
Obtain an instance containing the given number of zero bytes.- Parameters:
len
- number of zero bytes- Returns:
- instance containing
len
zero bytes - Throws:
IllegalArgumentException
- iflen
is negative
-
newWriter
Create a newByteData.Writer
using the default initial capacity.- Returns:
- new data writer
-
newWriter
Create a newByteData.Writer
using the given initial capacity.- Parameters:
initialCapacity
- intiial buffer capcity- Returns:
- new data writer
- Throws:
IllegalArgumentException
- ifinitialCapacity
is negative
-
numEqual
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 instancedata2
- first instanceoff1
- starting offset indata1
off2
- starting offset indata2
- Returns:
- the number of bytes that agree starting at
off1
indata1
andoff2
indata2
- Throws:
IllegalArgumentException
- ifdata1
ordata2
is nullIllegalArgumentException
- ifoff1
oroff2
is invalid
-
stream
Create anIntStream
from this instance.- Returns:
- stream of integer values in the range 0..255
-
newReader
Create aByteData.Reader
input stream from this instance.- Returns:
- data input stream
-
newReader
Create aByteData.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
- ifoff
is invalid
-
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 exceedInteger.MAX_VALUE
-
toHex
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 exceedInteger.MAX_VALUE
IllegalArgumentException
- iflimit
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
- ifindex
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
- ifindex
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
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
- ifbeginIndex
is invalid
-
substring
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
toendIndex
- Throws:
IndexOutOfBoundsException
- ifbeginIndex
and/orendIndex
is invalid
-
concat
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
- ifnext
is nullIllegalArgumentException
- if the concatenation would be longer thanInteger.MAX_VALUE
-
startsWith
Determine whether this instance has the given prefix.- Parameters:
prefix
- prefix data- Returns:
- true if this instance starts with
prefix
- Throws:
IllegalArgumentException
- ifprefix
is null
-
endsWith
Determine whether this instance has the given suffix.- Parameters:
suffix
- suffix data- Returns:
- true if this instance ends with
suffix
- Throws:
IllegalArgumentException
- ifsuffix
is null
-
toByteArray
public byte[] toByteArray()Obtain the data in this instance as abyte[]
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 abyte[]
array.- Parameters:
dest
- destination for dataoff
- offset intodest
to write- Throws:
IndexOutOfBoundsException
- ifoff
is invalidIllegalArgumentException
- ifdest
is null
-
writeTo
Write the data to the given output stream.- Parameters:
output
- destination for data- Throws:
IOException
- if an I/O error occursIllegalArgumentException
- ifoutput
is null
-
writeTo
Write the data into the given byte buffer at its current position (relative write).- Parameters:
buf
- destination for data- Throws:
BufferOverflowException
- ifbuf
has insufficient spaceReadOnlyBufferException
- ifbuf
is read onlyIllegalArgumentException
- ifbuf
is null
-
writeTo
Write the data into the given byte buffer at the specified position (absolute write).- Parameters:
buf
- destination for dataindex
- absolute index inbuf
at which to write the data- Throws:
BufferOverflowException
- ifbuf
has insufficient spaceReadOnlyBufferException
- ifbuf
is read onlyIndexOutOfBoundsException
- ifindex
is invalidIllegalArgumentException
- ifbuf
is null
-
compareTo
Compare this instance with the given instance using using unsigned lexicographical comparison.- Specified by:
compareTo
in interfaceComparable<ByteData>
-
equals
-
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 fromtoByteArray()
. -
toString
-