Class ByteString (3.19.4)

public abstract class ByteString implements Iterable<Byte>, Serializable

Immutable sequence of bytes. Provides conversions to and from byte[], java.lang.String, ByteBuffer, InputStream, OutputStream. Also provides a conversion to CodedInputStream.

Like String, the contents of a ByteString can never be observed to change, not even in the presence of a data race or incorrect API usage in the client code.

Substring is supported by sharing the reference to the immutable underlying bytes. Concatenation is likewise supported without copying (long strings) by building a tree of pieces in RopeByteString.

Inheritance

Object > ByteString

Implements

Iterable<Byte>, Serializable

Inherited Members

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Static Fields

EMPTY

public static final ByteString EMPTY

Empty ByteString.

Field Value
Type	Description
ByteString

Static Methods

copyFrom(byte[] bytes)

public static ByteString copyFrom(byte[] bytes)

Copies the given bytes into a ByteString.

Parameter
Name	Description
bytes	byte[] to copy

Returns
Type	Description
ByteString	new ByteString

copyFrom(byte[] bytes, int offset, int size)

public static ByteString copyFrom(byte[] bytes, int offset, int size)

Copies the given bytes into a ByteString.

Parameters
Name	Description
bytes	byte[] source array
offset	int offset in source array
size	int number of bytes to copy

Returns
Type	Description
ByteString	new ByteString

copyFrom(Iterable<ByteString> byteStrings)

public static ByteString copyFrom(Iterable<ByteString> byteStrings)

Concatenates all byte strings in the iterable and returns the result. This is designed to run in O(list size), not O(total bytes).

The returned ByteString is not necessarily a unique object. If the list is empty, the returned object is the singleton empty ByteString. If the list has only one element, that ByteString will be returned without copying.

Parameter
Name	Description
byteStrings	Iterable<ByteString> strings to be concatenated

Returns
Type	Description
ByteString	new ByteString

copyFrom(String text, String charsetName)

public static ByteString copyFrom(String text, String charsetName)

Encodes text into a sequence of bytes using the named charset and returns the result as a ByteString.

Parameters
Name	Description
text	String source string
charsetName	String encoding to use

Returns
Type	Description
ByteString	new ByteString

Exceptions
Type	Description
UnsupportedEncodingException	if the encoding isn't found

copyFrom(String text, Charset charset)

public static ByteString copyFrom(String text, Charset charset)

Encodes text into a sequence of bytes using the named charset and returns the result as a ByteString.

Parameters
Name	Description
text	String source string
charset	Charset encode using this charset

Returns
Type	Description
ByteString	new ByteString

copyFrom(ByteBuffer bytes)

public static ByteString copyFrom(ByteBuffer bytes)

Copies the remaining bytes from a java.nio.ByteBuffer into a ByteString.

Parameter
Name	Description
bytes	ByteBuffer sourceBuffer

Returns
Type	Description
ByteString	new ByteString

copyFrom(ByteBuffer bytes, int size)

public static ByteString copyFrom(ByteBuffer bytes, int size)

Copies the next size bytes from a java.nio.ByteBuffer into a ByteString.

Parameters
Name	Description
bytes	ByteBuffer source buffer
size	int number of bytes to copy

Returns
Type	Description
ByteString	new ByteString

copyFromUtf8(String text)

public static ByteString copyFromUtf8(String text)

Encodes text into a sequence of UTF-8 bytes and returns the result as a ByteString.

Parameter
Name	Description
text	String source string

Returns
Type	Description
ByteString	new ByteString

newOutput()

public static ByteString.Output newOutput()

Creates a new Output. Call Output#toByteString() to create the ByteString instance.

A ByteString.Output offers the same functionality as a ByteArrayOutputStream, except that it returns a ByteString rather than a byte array.

Returns
Type	Description
ByteString.Output	OutputStream for building a ByteString

newOutput(int initialCapacity)

public static ByteString.Output newOutput(int initialCapacity)

Creates a new Output with the given initial capacity. Call Output#toByteString() to create the ByteString instance.

A ByteString.Output offers the same functionality as a ByteArrayOutputStream, except that it returns a ByteString rather than a byte array.

Parameter
Name	Description
initialCapacity	int estimate of number of bytes to be written

Returns
Type	Description
ByteString.Output	OutputStream for building a ByteString

readFrom(InputStream streamToDrain)

public static ByteString readFrom(InputStream streamToDrain)

Completely reads the given stream's bytes into a ByteString, blocking if necessary until all bytes are read through to the end of the stream.

Performance notes: The returned ByteString is an immutable tree of byte arrays ("chunks") of the stream data. The first chunk is small, with subsequent chunks each being double the size, up to 8K.

Each byte read from the input stream will be copied twice to ensure that the resulting ByteString is truly immutable.

Parameter
Name	Description
streamToDrain	InputStream The source stream, which is read completely but not closed.

Returns
Type	Description
ByteString	A new ByteString which is made up of chunks of various sizes, depending on the behavior of the underlying stream.

Exceptions
Type	Description
IOException	if there is a problem reading the underlying stream

readFrom(InputStream streamToDrain, int chunkSize)

public static ByteString readFrom(InputStream streamToDrain, int chunkSize)

Completely reads the given stream's bytes into a ByteString, blocking if necessary until all bytes are read through to the end of the stream.

Performance notes: The returned ByteString is an immutable tree of byte arrays ("chunks") of the stream data. The chunkSize parameter sets the size of these byte arrays.

Each byte read from the input stream will be copied twice to ensure that the resulting ByteString is truly immutable.

Parameters
Name	Description
streamToDrain	InputStream The source stream, which is read completely but not closed.
chunkSize	int The size of the chunks in which to read the stream.

Returns
Type	Description
ByteString	A new ByteString which is made up of chunks of the given size.

Exceptions
Type	Description
IOException	if there is a problem reading the underlying stream

readFrom(InputStream streamToDrain, int minChunkSize, int maxChunkSize)

public static ByteString readFrom(InputStream streamToDrain, int minChunkSize, int maxChunkSize)

Helper method that takes the chunk size range as a parameter.

Parameters
Name	Description
streamToDrain	InputStream the source stream, which is read completely but not closed
minChunkSize	int the minimum size of the chunks in which to read the stream
maxChunkSize	int the maximum size of the chunks in which to read the stream

Returns
Type	Description
ByteString	a new ByteString which is made up of chunks within the given size range

Exceptions
Type	Description
IOException	if there is a problem reading the underlying stream

unsignedLexicographicalComparator()

public static Comparator<ByteString> unsignedLexicographicalComparator()

Returns a Comparator which compares ByteString-s lexicographically as sequences of unsigned bytes (i.e. values between 0 and 255, inclusive).

For example, (byte) -1 is considered to be greater than (byte) 1 because it is interpreted as an unsigned value, 255:

• -1 -> 0b11111111 (two's complement) -> 255
• 1 -> 0b00000001 -> 1

Returns
Type	Description
Comparator<ByteString>

Methods

asReadOnlyByteBuffer()

public abstract ByteBuffer asReadOnlyByteBuffer()

Constructs a read-only java.nio.ByteBuffer whose content is equal to the contents of this byte string. The result uses the same backing array as the byte string, if possible.

Returns
Type	Description
ByteBuffer	wrapped bytes

asReadOnlyByteBufferList()

public abstract List<ByteBuffer> asReadOnlyByteBufferList()

Constructs a list of read-only java.nio.ByteBuffer objects such that the concatenation of their contents is equal to the contents of this byte string. The result uses the same backing arrays as the byte string.

By returning a list, implementations of this method may be able to avoid copying even when there are multiple backing arrays.

Returns
Type	Description
List<ByteBuffer>	a list of wrapped bytes

byteAt(int index)

public abstract byte byteAt(int index)

Gets the byte at the given index. This method should be used only for random access to individual bytes. To access bytes sequentially, use the ByteIterator returned by #iterator(), and call #substring(int, int) first if necessary.

Parameter
Name	Description
index	int index of byte

Returns
Type	Description
byte	the value

concat(ByteString other)

public final ByteString concat(ByteString other)

Concatenate the given ByteString to this one. Short concatenations, of total size smaller than ByteString#CONCATENATE_BY_COPY_SIZE, are produced by copying the underlying bytes (as per Rope.java, BAP95 . In general, the concatenate involves no copying.

Parameter
Name	Description
other	ByteString string to concatenate

Returns
Type	Description
ByteString	a new ByteString instance

copyTo(byte[] target, int offset)

public void copyTo(byte[] target, int offset)

Copies bytes into a buffer at the given offset.

To copy a subset of bytes, you call this method on the return value of #substring(int, int). Example: byteString.substring(start, end).copyTo(target, offset)

Parameters
Name	Description
target	byte[] buffer to copy into
offset	int in the target buffer

copyTo(byte[] target, int sourceOffset, int targetOffset, int numberToCopy) (deprecated)

public final void copyTo(byte[] target, int sourceOffset, int targetOffset, int numberToCopy)

Deprecated. Instead, call byteString.substring(sourceOffset, sourceOffset + numberToCopy).copyTo(target, targetOffset)

Copies bytes into a buffer.

Parameters
Name	Description
target	byte[] buffer to copy into
sourceOffset	int offset within these bytes
targetOffset	int offset within the target buffer
numberToCopy	int number of bytes to copy

copyTo(ByteBuffer target)

public abstract void copyTo(ByteBuffer target)

Copies bytes into a ByteBuffer.

To copy a subset of bytes, you call this method on the return value of #substring(int, int). Example: byteString.substring(start, end).copyTo(target)

Parameter
Name	Description
target	ByteBuffer ByteBuffer to copy into.

copyToInternal(byte[] target, int sourceOffset, int targetOffset, int numberToCopy)

protected abstract void copyToInternal(byte[] target, int sourceOffset, int targetOffset, int numberToCopy)

Internal (package private) implementation of #copyTo(byte[],int,int,int). It assumes that all error checking has already been performed and that numberToCopy > 0.

Parameters
Name	Description
target	byte[]
sourceOffset	int
targetOffset	int
numberToCopy	int

endsWith(ByteString suffix)

public final boolean endsWith(ByteString suffix)

Tests if this bytestring ends with the specified suffix. Similar to String#endsWith(String)

Parameter
Name	Description
suffix	ByteString the suffix.

Returns
Type	Description
boolean	true if the byte sequence represented by the argument is a suffix of the byte sequence represented by this string; false otherwise.

equals(Object o)

public abstract boolean equals(Object o)

Parameter
Name	Description
o	Object

Returns
Type	Description
boolean

Overrides

Object.equals(Object)

getTreeDepth()

protected abstract int getTreeDepth()

Return the depth of the tree representing this ByteString, if any, whose root is this node. If this is a leaf node, return 0.

Returns
Type	Description
int	tree depth or zero

hashCode()

public final int hashCode()

Compute the hashCode using the traditional algorithm from ByteString.

Returns
Type	Description
int	hashCode value

Overrides

Object.hashCode()

isBalanced()

protected abstract boolean isBalanced()

Return true if this ByteString is literal (a leaf node) or a flat-enough tree in the sense of RopeByteString.

Returns
Type	Description
boolean	true if the tree is flat enough

isEmpty()

public final boolean isEmpty()

Returns true if the size is 0, false otherwise.

Returns
Type	Description
boolean	true if this is zero bytes long

isValidUtf8()

public abstract boolean isValidUtf8()

Tells whether this ByteString represents a well-formed UTF-8 byte sequence, such that the original bytes can be converted to a String object and then round tripped back to bytes without loss.

More precisely, returns true whenever:

 Arrays.equals(byteString.toByteArray(),
     new String(byteString.toByteArray(), "UTF-8").getBytes("UTF-8"))
 

This method returns false for "overlong" byte sequences, as well as for 3-byte sequences that would map to a surrogate character, in accordance with the restricted definition of UTF-8 introduced in Unicode 3.1. Note that the UTF-8 decoder included in Oracle's JDK has been modified to also reject "overlong" byte sequences, but (as of 2011) still accepts 3-byte surrogate character byte sequences.

See the Unicode Standard,
Table 3-6. UTF-8 Bit Distribution,
Table 3-7. Well Formed UTF-8 Byte Sequences.

Returns
Type	Description
boolean	whether the bytes in this ByteString are a well-formed UTF-8 byte sequence

iterator()

public ByteString.ByteIterator iterator()

Return a ByteString.ByteIterator over the bytes in the ByteString. To avoid auto-boxing, you may get the iterator manually and call ByteIterator#nextByte().

Returns
Type	Description
ByteString.ByteIterator	the iterator

newCodedInput()

public abstract CodedInputStream newCodedInput()

Creates a CodedInputStream which can be used to read the bytes. Using this is often more efficient than creating a CodedInputStream that wraps the result of #newInput().

Returns
Type	Description
CodedInputStream	stream based on wrapped data

newInput()

public abstract InputStream newInput()

Creates an InputStream which can be used to read the bytes.

The InputStream returned by this method is guaranteed to be completely non-blocking. The method InputStream#available() returns the number of bytes remaining in the stream. The methods InputStream#read(byte[]), InputStream#read(byte[],int,int) and InputStream#skip(long) will read/skip as many bytes as are available. The method InputStream#markSupported() returns true.

The methods in the returned InputStream might not be thread safe.

Returns
Type	Description
InputStream	an input stream that returns the bytes of this byte string.

partialHash(int h, int offset, int length)

protected abstract int partialHash(int h, int offset, int length)

Compute the hash across the value bytes starting with the given hash, and return the result. This is used to compute the hash across strings represented as a set of pieces by allowing the hash computation to be continued from piece to piece.

Parameters
Name	Description
h	int starting hash value
offset	int offset into this value to start looking at data values
length	int number of data values to include in the hash computation

Returns
Type	Description
int	ending hash value

partialIsValidUtf8(int state, int offset, int length)

protected abstract int partialIsValidUtf8(int state, int offset, int length)

Tells whether the given byte sequence is a well-formed, malformed, or incomplete UTF-8 byte sequence. This method accepts and returns a partial state result, allowing the bytes for a complete UTF-8 byte sequence to be composed from multiple ByteString segments.

Parameters
Name	Description
state	int either 0 (if this is the initial decoding operation) or the value returned from a call to a partial decoding method for the previous bytes
offset	int offset of the first byte to check
length	int number of bytes to check

Returns
Type	Description
int	-1 if the partial byte sequence is definitely malformed, 0 if it is well-formed (no additional input needed), or, if the byte sequence is "incomplete", i.e. apparently terminated in the middle of a character, an opaque integer "state" value containing enough information to decode the character when passed to a subsequent invocation of a partial decoding method.

peekCachedHashCode()

protected final int peekCachedHashCode()

Return the cached hash code if available.

Returns
Type	Description
int	value of cached hash code or 0 if not computed yet

size()

public abstract int size()

Gets the number of bytes.

Returns
Type	Description
int	size in bytes

startsWith(ByteString prefix)

public final boolean startsWith(ByteString prefix)

Tests if this bytestring starts with the specified prefix. Similar to String#startsWith(String)

Parameter
Name	Description
prefix	ByteString the prefix.

Returns
Type	Description
boolean	true if the byte sequence represented by the argument is a prefix of the byte sequence represented by this string; false otherwise.

substring(int beginIndex)

public final ByteString substring(int beginIndex)

Return the substring from beginIndex, inclusive, to the end of the string.

Parameter
Name	Description
beginIndex	int start at this index

Returns
Type	Description
ByteString	substring sharing underlying data

substring(int beginIndex, int endIndex)

public abstract ByteString substring(int beginIndex, int endIndex)

Return the substring from beginIndex, inclusive, to endIndex, exclusive.

Parameters
Name	Description
beginIndex	int start at this index
endIndex	int the last character is the one before this index

Returns
Type	Description
ByteString	substring sharing underlying data

toByteArray()

public final byte[] toByteArray()

Copies bytes to a byte[].

Returns
Type	Description
byte[]	copied bytes

toString()

public final String toString()

Returns
Type	Description
String

Overrides

Object.toString()

toString(String charsetName)

public final String toString(String charsetName)

Constructs a new String by decoding the bytes using the specified charset.

Parameter
Name	Description
charsetName	String encode using this charset

Returns
Type	Description
String	new string

Exceptions
Type	Description
UnsupportedEncodingException	if charset isn't recognized

toString(Charset charset)

public final String toString(Charset charset)

Constructs a new String by decoding the bytes using the specified charset. Returns the same empty String if empty.

Parameter
Name	Description
charset	Charset encode using this charset

Returns
Type	Description
String	new string

toStringInternal(Charset charset)

protected abstract String toStringInternal(Charset charset)

Constructs a new String by decoding the bytes using the specified charset.

Parameter
Name	Description
charset	Charset encode using this charset

Returns
Type	Description
String	new string

toStringUtf8()

public final String toStringUtf8()

Constructs a new String by decoding the bytes as UTF-8.

Returns
Type	Description
String	new string using UTF-8 encoding

writeTo(OutputStream out)

public abstract void writeTo(OutputStream out)

Writes a copy of the contents of this byte string to the specified output stream argument.

Parameter
Name	Description
out	OutputStream the output stream to which to write the data.

Exceptions
Type	Description
IOException	if an I/O error occurs.