Class ByteString (3.19.4)

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.

Empty ByteString.

Copies the given bytes into a ByteString.

Copies the given bytes into a ByteString.

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.

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

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

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

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

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

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.

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.

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.

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.

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

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

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.

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.

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.

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.

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)

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

Copies bytes into a buffer.

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)

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

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

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

Compute the hashCode using the traditional algorithm from ByteString.

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

Returns true if the size is 0, false otherwise.

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.

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

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().

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.

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.

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.

Return the cached hash code if available.

Gets the number of bytes.

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

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

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

Copies bytes to a byte[].

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

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

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

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

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