@Immutable public final class ByteString extends Object implements ByteSequence
BYTE_ARRAY_COMPARATOR, COMPARATOR
Modifier and Type | Method and Description |
---|---|
static ByteString[] |
asArray(Object... objects)
Returns an array containing the provided objects converted to byte strings using
valueOfObject(Object) . |
static List<ByteString> |
asList(Object... objects)
Returns a list containing the provided objects converted to byte strings using
valueOfObject(Object) . |
ByteSequenceReader |
asReader()
Returns a
ByteSequenceReader which can be used to incrementally
read and decode data from this byte string. |
byte |
byteAt(int index)
Returns the byte value at the specified index.
|
int |
compareTo(byte[] bytes,
int offset,
int length)
Compares this byte sequence with the specified byte array sub-sequence
for order.
|
int |
compareTo(ByteSequence o)
Compares this byte sequence with the specified byte sequence for order.
|
byte[] |
copyTo(byte[] bytes)
Copies the contents of this byte sequence to the provided byte array.
|
byte[] |
copyTo(byte[] bytes,
int offset)
Copies the contents of this byte sequence to the specified location in
the provided byte array.
|
ByteBuffer |
copyTo(ByteBuffer byteBuffer)
Appends the content of this byte sequence to the provided
ByteBuffer starting at it's current position. |
ByteStringBuilder |
copyTo(ByteStringBuilder builder)
Appends the entire contents of this byte sequence to the provided
ByteStringBuilder . |
boolean |
copyTo(CharBuffer charBuffer,
CharsetDecoder decoder)
Appends the content of this byte sequence decoded using provided charset decoder to the provided
CharBuffer starting at it's current position. |
OutputStream |
copyTo(OutputStream stream)
Copies the entire contents of this byte sequence to the provided
OutputStream . |
static ByteString |
empty()
Returns an empty byte string.
|
boolean |
equals(byte[] bytes,
int offset,
int length)
Indicates whether the provided byte array sub-sequence is equal to this
byte sequence.
|
boolean |
equals(Object o)
Indicates whether the provided object is equal to this byte string.
|
int |
hashCode()
Returns a hash code for this byte string.
|
boolean |
isEmpty()
Returns
true if this byte sequence has a length of zero. |
int |
length()
Returns the length of this byte sequence.
|
boolean |
startsWith(ByteSequence prefix)
Tests if this ByteSequence starts with the specified prefix.
|
ByteString |
subSequence(int start,
int end)
Returns a new byte sequence that is a subsequence of this byte sequence.
|
String |
toAsciiString()
Returns a 7-bit ASCII string representation.
|
String |
toBase64String()
Returns the Base64 encoded string representation of this byte string.
|
byte[] |
toByteArray()
Returns a byte array containing the bytes in this sequence in the same
order as this sequence.
|
ByteBuffer |
toByteBuffer()
Returns the read-only
ByteBuffer representation of this byte sequence. |
ByteString |
toByteString()
Returns the
ByteString representation of this byte sequence. |
char[] |
toCharArray()
Returns the UTF-8 decoded char array representation of this byte
sequence.
|
String |
toHexPlusAsciiString(int indent)
Returns a string representation of the data in this byte sequence using
the specified indent.
|
String |
toHexString()
Returns a string representation of the contents of this byte sequence
using hexadecimal characters and a space between each byte.
|
int |
toInt()
Returns the integer value represented by the first four bytes of this
byte string in big-endian order.
|
long |
toLong()
Returns the long value represented by the first eight bytes of this byte
string in big-endian order.
|
String |
toPercentHexString()
Returns a string representation of the contents of this byte sequence
using hexadecimal characters and a percent prefix (%) before each char.
|
String |
toString()
Returns the UTF-8 decoded string representation of this byte sequence.
|
static ByteString |
valueOfBase64(String s)
Returns a byte string containing the Base64 decoded bytes of the provided
string.
|
static ByteString |
valueOfBytes(byte[] bytes)
Returns a byte string containing the contents of the provided byte array.
|
static ByteString |
valueOfBytes(byte[] bytes,
int offset,
int length)
Returns a byte string containing a subsequence of the contents of the
provided byte array.
|
static ByteString |
valueOfHex(String hexString)
Returns a byte string containing the bytes of the provided hexadecimal string.
|
static ByteString |
valueOfInt(int i)
Returns a byte string containing the big-endian encoded bytes of the
provided integer.
|
static ByteString |
valueOfLong(long l)
Returns a byte string containing the big-endian encoded bytes of the
provided long.
|
static ByteString |
valueOfObject(Object o)
Returns a byte string representation of the provided object.
|
static ByteString |
valueOfUtf8(char[] chars)
Returns a byte string containing the UTF-8 encoded bytes of the provided
char array.
|
static ByteString |
valueOfUtf8(CharSequence s)
Returns a byte string containing the UTF-8 encoded bytes of the provided
char sequence.
|
static ByteString |
wrap(byte[] bytes)
Returns a byte string that wraps the provided byte array.
|
static ByteString |
wrap(byte[] bytes,
int offset,
int length)
Returns a byte string that wraps a subsequence of the provided byte
array.
|
public static ByteString empty()
public static ByteString valueOfInt(int i)
i
- The integer to encode.public static ByteString valueOfLong(long l)
l
- The long to encode.public static ByteString valueOfObject(Object o)
ByteSequence
then this method
is equivalent to calling o.toByteString()
byte[]
then this method is equivalent to
calling valueOfBytes(byte[])
char[]
then this method is equivalent to
calling valueOfUtf8(char[])
valueOfUtf8(CharSequence)
with the toString()
representation of
the provided object.
Long
and Integer
objects
like any other type of Object
. More specifically, the following
invocations are not equivalent:
valueOf(0)
is not equivalent to valueOf((Object) 0)
valueOf(0L)
is not equivalent to valueOf((Object) 0L)
o
- The object to use.public static ByteString valueOfUtf8(CharSequence s)
s
- The char sequence to use.public static ByteString valueOfBase64(String s)
s
- The string to use.LocalizedIllegalArgumentException
- If the provided string does not contain valid Base64 encoded
content.toBase64String()
public static ByteString valueOfHex(String hexString)
hexString
- The hexadecimal string to convert to a byte array.LocalizedIllegalArgumentException
- If the provided string contains invalid hexadecimal digits or
does not contain an even number of digits.public static ByteString valueOfBytes(byte[] bytes)
This method differs from wrap(byte[])
in that it defensively
copies the provided byte array.
bytes
- The byte array to use.public static ByteString valueOfBytes(byte[] bytes, int offset, int length)
This method differs from wrap(byte[], int, int)
in that it
defensively copies the provided byte array.
bytes
- The byte array to use.offset
- The offset of the byte array to be used; must be non-negative
and no larger than bytes.length
.length
- The length of the byte array to be used; must be non-negative
and no larger than bytes.length - offset
.public static ByteString valueOfUtf8(char[] chars)
chars
- The char array to use.public static ByteString wrap(byte[] bytes)
NOTE: this method takes ownership of the provided byte array and, therefore, the byte array MUST NOT be altered directly after this method returns.
bytes
- The byte array to wrap.public static ByteString wrap(byte[] bytes, int offset, int length)
NOTE: this method takes ownership of the provided byte array and, therefore, the byte array MUST NOT be altered directly after this method returns.
bytes
- The byte array to wrap.offset
- The offset of the byte array to be used; must be non-negative
and no larger than bytes.length
.length
- The length of the byte array to be used; must be non-negative
and no larger than bytes.length - offset
.IndexOutOfBoundsException
- If offset
is negative or if length
is
negative or if offset + length
is greater than
bytes.length
.public static List<ByteString> asList(Object... objects)
valueOfObject(Object)
.objects
- The list of objects to be converted to byte strings.valueOfObject(Object)
.public static ByteString[] asArray(Object... objects)
valueOfObject(Object)
.objects
- The list of objects to be converted to byte strings.valueOfObject(Object)
.public String toAsciiString()
public ByteSequenceReader asReader()
ByteSequenceReader
which can be used to incrementally
read and decode data from this byte string.asReader
in interface ByteSequence
ByteSequenceReader
which can be used to incrementally
read and decode data from this byte string.public byte byteAt(int index)
ByteSequence
An index ranges from zero to length() - 1
. The first byte value
of the sequence is at index zero, the next at index one, and so on, as
for array indexing.
byteAt
in interface ByteSequence
index
- The index of the byte to be returned.public int compareTo(byte[] bytes, int offset, int length)
ByteSequence
compareTo
in interface ByteSequence
bytes
- The byte array to compare.offset
- The offset of the sub-sequence in the byte array to be
compared; must be non-negative and no larger than
bytes.length
.length
- The length of the sub-sequence in the byte array to be
compared; must be non-negative and no larger than
bytes.length - offset
.public int compareTo(ByteSequence o)
ByteSequence
compareTo
in interface Comparable<ByteSequence>
compareTo
in interface ByteSequence
o
- The byte sequence to be compared.public byte[] copyTo(byte[] bytes)
ByteSequence
Copying will stop when either the entire content of this sequence has been copied or if the end of the provided byte array has been reached.
An invocation of the form:
src.copyTo(bytes)Behaves in exactly the same way as the invocation:
src.copyTo(bytes, 0);
copyTo
in interface ByteSequence
bytes
- The byte array to which bytes are to be copied.public byte[] copyTo(byte[] bytes, int offset)
ByteSequence
Copying will stop when either the entire content of this sequence has been copied or if the end of the provided byte array has been reached.
An invocation of the form:
src.copyTo(bytes, offset)Behaves in exactly the same way as the invocation:
int len = Math.min(src.length(), bytes.length - offset); for (int i = 0; i < len; i++) bytes[offset + i] = src.get(i);Except that it is potentially much more efficient.
copyTo
in interface ByteSequence
bytes
- The byte array to which bytes are to be copied.offset
- The offset within the array of the first byte to be written;
must be non-negative and no larger than bytes.length.public ByteBuffer copyTo(ByteBuffer byteBuffer)
ByteSequence
ByteBuffer
starting at it's current position.
The position of the buffer is then incremented by the length of this sequence.copyTo
in interface ByteSequence
byteBuffer
- The buffer to copy to.
It must be large enough to receive all bytes.public ByteStringBuilder copyTo(ByteStringBuilder builder)
ByteSequence
ByteStringBuilder
.copyTo
in interface ByteSequence
builder
- The builder to copy to.public boolean copyTo(CharBuffer charBuffer, CharsetDecoder decoder)
ByteSequence
CharBuffer
starting at it's current position. The position of charBuffer is then incremented by the
length of this sequence.copyTo
in interface ByteSequence
charBuffer
- The buffer to copy to, if decoding is successful.
It must be large enough to receive all decoded characters.decoder
- The charset decoder to use for decoding.true
if byte string was successfully decoded and charBuffer is
large enough to receive the resulting string, false
otherwisepublic OutputStream copyTo(OutputStream stream) throws IOException
ByteSequence
OutputStream
.copyTo
in interface ByteSequence
stream
- The OutputStream
to copy to.OutputStream
.IOException
- If an error occurs while writing to the OutputStream
.public boolean equals(byte[] bytes, int offset, int length)
ByteSequence
equals
in interface ByteSequence
bytes
- The byte array for which to make the determination.offset
- The offset of the sub-sequence in the byte array to be
compared; must be non-negative and no larger than
bytes.length
.length
- The length of the sub-sequence in the byte array to be
compared; must be non-negative and no larger than
bytes.length - offset
.true
if the content of the provided byte array
sub-sequence is equal to that of this byte sequence, or
false
if not.public boolean equals(Object o)
equals
in interface ByteSequence
equals
in class Object
o
- The object for which to make the determination.true
if the provided object is a byte sequence whose
content is equal to that of this byte string, or false
if
not.public int hashCode()
hashCode
in interface ByteSequence
hashCode
in class Object
public boolean isEmpty()
ByteSequence
true
if this byte sequence has a length of zero.isEmpty
in interface ByteSequence
true
if this byte sequence has a length of zero.public int length()
ByteSequence
length
in interface ByteSequence
public ByteString subSequence(int start, int end)
ByteSequence
The subsequence starts with the byte value at the specified start
index and ends with the byte value at index end - 1
. The length
(in bytes) of the returned sequence is end - start
, so if
start
== end
then an empty sequence is returned.
NOTE: changes to the underlying byte sequence (if mutable) may render the returned sub-sequence invalid.
subSequence
in interface ByteSequence
start
- The start index, inclusive.end
- The end index, exclusive.public boolean startsWith(ByteSequence prefix)
ByteSequence
startsWith
in interface ByteSequence
prefix
- The prefix.public String toBase64String()
ByteSequence
toBase64String
in interface ByteSequence
valueOfBase64(String)
public String toHexString()
public String toPercentHexString()
public String toHexPlusAsciiString(int indent)
The data will be formatted with sixteen hex bytes in a row followed by the ASCII representation, then wrapping to a new line as necessary. The state of the byte buffer is not changed.
indent
- The number of spaces to indent the output.public byte[] toByteArray()
ByteSequence
An invocation of the form:
src.toByteArray()Behaves in exactly the same way as the invocation:
src.copyTo(new byte[src.length()]);
toByteArray
in interface ByteSequence
public ByteString toByteString()
ByteSequence
ByteString
representation of this byte sequence.toByteString
in interface ByteSequence
ByteString
representation of this byte sequence.public ByteBuffer toByteBuffer()
ByteSequence
ByteBuffer
representation of this byte sequence.toByteBuffer
in interface ByteSequence
ByteBuffer
representation of this byte sequence.public char[] toCharArray()
public int toInt()
IndexOutOfBoundsException
- If this byte string has less than four bytes.public long toLong()
IndexOutOfBoundsException
- If this byte string has less than eight bytes.public String toString()
ByteSequence
toString
in interface ByteSequence
toString
in class Object
Copyright 2010-2022 ForgeRock AS.