java.lang.Object
- com.google.protobuf.ByteString

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<java.lang.Byte>

Direct Known Subclasses:

ByteString.LeafByteString, RopeByteString
```
@CheckReturnValue
public abstract class ByteString
extends java.lang.Object
implements java.lang.Iterable<java.lang.Byte>, java.io.Serializable
```
Immutable sequence of bytes. Provides conversions to and from byte[], 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.

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`(package private) static class`	`ByteString.AbstractByteIterator`
`private static class`	`ByteString.ArraysByteArrayCopier`	Implementation of `ByteArrayCopier` which uses `Arrays.copyOfRange(T[], int, int)`.
`private static class`	`ByteString.BoundedByteString`	This class is used to represent the substring of a `ByteString` over a single byte array.
`private static interface`	`ByteString.ByteArrayCopier`	An interface to efficiently copy `byte[]`.
`static interface`	`ByteString.ByteIterator`	This interface extends `Iterator<Byte>`, so that we can return an unboxed `byte`.
`(package private) static class`	`ByteString.CodedBuilder`	See `newCodedBuilder(int)`.
`(package private) static class`	`ByteString.LeafByteString`	Base class for leaf `ByteString`s (i.e.
`private static class`	`ByteString.LiteralByteString`	This class implements a `ByteString` backed by a single array of bytes, contiguous in memory.
`private static class`	`ByteString.NioByteString`	A `ByteString` that wraps around a `ByteBuffer`.
`static class`	`ByteString.Output`	Outputs to a `ByteString` instance.
`private static class`	`ByteString.SystemByteArrayCopier`	Implementation of `ByteArrayCopier` which uses `System.arraycopy(java.lang.Object, int, java.lang.Object, int, int)`.

Field Summary

Fields
Modifier and Type	Field	Description
`private static ByteString.ByteArrayCopier`	`byteArrayCopier`
`(package private) static int`	`CONCATENATE_BY_COPY_SIZE`	When two strings to be concatenated have a combined length shorter than this, we just copy their bytes on `concat(ByteString)`.
`static ByteString`	`EMPTY`	Empty `ByteString`.
`private int`	`hash`	Cached hash value.
`(package private) static int`	`MAX_READ_FROM_CHUNK_SIZE`
`(package private) static int`	`MIN_READ_FROM_CHUNK_SIZE`	When copying an InputStream into a ByteString with .readFrom(), the chunks in the underlying rope start at 256 bytes, but double each iteration up to 8192 bytes.
`private static long`	`serialVersionUID`
`private static int`	`UNSIGNED_BYTE_MASK`
`private static java.util.Comparator<ByteString>`	`UNSIGNED_LEXICOGRAPHICAL_COMPARATOR`	Compares two `ByteString`s lexicographically, treating their contents as unsigned byte values between 0 and 255 (inclusive).

Constructor Summary

Constructors
Constructor Description

ByteString()

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`abstract java.nio.ByteBuffer`	`asReadOnlyByteBuffer()`	Constructs a read-only `java.nio.ByteBuffer` whose content is equal to the contents of this byte string.
`abstract java.util.List<java.nio.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.
`private static ByteString`	`balancedConcat(java.util.Iterator<ByteString> iterator, int length)`
`abstract byte`	`byteAt(int index)`	Gets the byte at the given index.
`(package private) static void`	`checkIndex(int index, int size)`	Checks that the given index falls within the specified array size.
`(package private) static int`	`checkRange(int startIndex, int endIndex, int size)`	Checks that the given range falls within the bounds of an array
`ByteString`	`concat(ByteString other)`	Concatenate the given `ByteString` to this one.
`static ByteString`	`copyFrom(byte[] bytes)`	Copies the given bytes into a `ByteString`.
`static ByteString`	`copyFrom(byte[] bytes, int offset, int size)`	Copies the given bytes into a `ByteString`.
`static ByteString`	`copyFrom(java.lang.Iterable<ByteString> byteStrings)`	Concatenates all byte strings in the iterable and returns the result.
`static ByteString`	`copyFrom(java.lang.String text, java.lang.String charsetName)`	Encodes `text` into a sequence of bytes using the named charset and returns the result as a `ByteString`.
`static ByteString`	`copyFrom(java.lang.String text, java.nio.charset.Charset charset)`	Encodes `text` into a sequence of bytes using the named charset and returns the result as a `ByteString`.
`static ByteString`	`copyFrom(java.nio.ByteBuffer bytes)`	Copies the remaining bytes from a `java.nio.ByteBuffer` into a `ByteString`.
`static ByteString`	`copyFrom(java.nio.ByteBuffer bytes, int size)`	Copies the next `size` bytes from a `java.nio.ByteBuffer` into a `ByteString`.
`static ByteString`	`copyFromUtf8(java.lang.String text)`	Encodes `text` into a sequence of UTF-8 bytes and returns the result as a `ByteString`.
`void`	`copyTo(byte[] target, int offset)`	Copies bytes into a buffer at the given offset.
`void`	`copyTo(byte[] target, int sourceOffset, int targetOffset, int numberToCopy)`	Deprecated. Instead, call `byteString.substring(sourceOffset, sourceOffset + numberToCopy).copyTo(target, targetOffset)`
`abstract void`	`copyTo(java.nio.ByteBuffer target)`	Copies bytes into a ByteBuffer.
`protected abstract void`	`copyToInternal(byte[] target, int sourceOffset, int targetOffset, int numberToCopy)`	Internal (package private) implementation of `copyTo(byte[],int,int,int)`.
`static ByteString`	`empty()`	Returns an empty `ByteString` of size `0`.
`boolean`	`endsWith(ByteString suffix)`	Tests if this bytestring ends with the specified suffix.
`abstract boolean`	`equals(java.lang.Object o)`
`private static int`	`extractHexDigit(java.lang.String hexString, int index)`	Returns the numeric value of the given character at index in hexString.
`static ByteString`	`fromHex(java.lang.String hexString)`	Returns a `ByteString` from a hexadecimal String.
`protected abstract int`	`getTreeDepth()`	Return the depth of the tree representing this `ByteString`, if any, whose root is this node.
`int`	`hashCode()`	Compute the hashCode using the traditional algorithm from `ByteString`.
`private static int`	`hexDigit(char c)`	Returns the numeric value of the given character in hex, or -1 if invalid.
`(package private) abstract byte`	`internalByteAt(int index)`	Gets the byte at the given index, assumes bounds checking has already been performed.
`protected abstract boolean`	`isBalanced()`	Return `true` if this ByteString is literal (a leaf node) or a flat-enough tree in the sense of `RopeByteString`.
`boolean`	`isEmpty()`	Returns `true` if the size is `0`, `false` otherwise.
`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.
`ByteString.ByteIterator`	`iterator()`	Return a `ByteString.ByteIterator` over the bytes in the ByteString.
`(package private) static ByteString.CodedBuilder`	`newCodedBuilder(int size)`	Constructs a new `ByteString` builder, which allows you to efficiently construct a `ByteString` by writing to a `CodedOutputStream`.
`abstract CodedInputStream`	`newCodedInput()`	Creates a `CodedInputStream` which can be used to read the bytes.
`abstract java.io.InputStream`	`newInput()`	Creates an `InputStream` which can be used to read the bytes.
`static ByteString.Output`	`newOutput()`	Creates a new `ByteString.Output`.
`static ByteString.Output`	`newOutput(int initialCapacity)`	Creates a new `ByteString.Output` with the given initial capacity.
`(package private) static ByteString`	`nioByteString(java.nio.ByteBuffer buffer)`
`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.
`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.
`protected int`	`peekCachedHashCode()`	Return the cached hash code if available.
`private static ByteString`	`readChunk(java.io.InputStream in, int chunkSize)`	Blocks until a chunk of the given size can be made from the stream, or EOF is reached.
`static ByteString`	`readFrom(java.io.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.
`static ByteString`	`readFrom(java.io.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.
`static ByteString`	`readFrom(java.io.InputStream streamToDrain, int minChunkSize, int maxChunkSize)`	Helper method that takes the chunk size range as a parameter.
`abstract int`	`size()`	Gets the number of bytes.
`boolean`	`startsWith(ByteString prefix)`	Tests if this bytestring starts with the specified prefix.
`ByteString`	`substring(int beginIndex)`	Return the substring from `beginIndex`, inclusive, to the end of the string.
`abstract ByteString`	`substring(int beginIndex, int endIndex)`	Return the substring from `beginIndex`, inclusive, to `endIndex`, exclusive.
`byte[]`	`toByteArray()`	Copies bytes to a `byte[]`.
`private static int`	`toInt(byte value)`	Returns the value of the given byte as an integer, interpreting the byte as an unsigned value.
`java.lang.String`	`toString()`
`java.lang.String`	`toString(java.lang.String charsetName)`	Constructs a new `String` by decoding the bytes using the specified charset.
`java.lang.String`	`toString(java.nio.charset.Charset charset)`	Constructs a new `String` by decoding the bytes using the specified charset.
`protected abstract java.lang.String`	`toStringInternal(java.nio.charset.Charset charset)`	Constructs a new `String` by decoding the bytes using the specified charset.
`java.lang.String`	`toStringUtf8()`	Constructs a new `String` by decoding the bytes as UTF-8.
`private java.lang.String`	`truncateAndEscapeForDisplay()`
`static java.util.Comparator<ByteString>`	`unsignedLexicographicalComparator()`	Returns a `Comparator` which compares `ByteString`-s lexicographically as sequences of unsigned bytes (i.e.
`(package private) static ByteString`	`wrap(byte[] bytes)`	Wraps the given bytes into a `ByteString`.
`(package private) static ByteString`	`wrap(byte[] bytes, int offset, int length)`	Wraps the given bytes into a `ByteString`.
`(package private) static ByteString`	`wrap(java.nio.ByteBuffer buffer)`	Wraps the given bytes into a `ByteString`.
`(package private) abstract void`	`writeTo(ByteOutput byteOutput)`	Writes this `ByteString` to the provided `ByteOutput`.
`abstract void`	`writeTo(java.io.OutputStream out)`	Writes a copy of the contents of this byte string to the specified output stream argument.
`(package private) void`	`writeTo(java.io.OutputStream out, int sourceOffset, int numberToWrite)`	Writes a specified part of this byte string to an output stream.
`(package private) abstract void`	`writeToInternal(java.io.OutputStream out, int sourceOffset, int numberToWrite)`	Internal version of `writeTo(OutputStream,int,int)` that assumes all error checking has already been done.
`(package private) abstract void`	`writeToReverse(ByteOutput byteOutput)`	This method behaves exactly the same as `writeTo(ByteOutput)` unless the `ByteString` is a rope.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Field Detail
  - serialVersionUID
```
private static final long serialVersionUID
```
    See Also:
    
    Constant Field Values
  - CONCATENATE_BY_COPY_SIZE
```
static final int CONCATENATE_BY_COPY_SIZE
```
    When two strings to be concatenated have a combined length shorter than this, we just copy their bytes on concat(ByteString). The trade-off is copy size versus the overhead of creating tree nodes in RopeByteString.
    
    See Also:
    
    Constant Field Values
  - MIN_READ_FROM_CHUNK_SIZE
```
static final int MIN_READ_FROM_CHUNK_SIZE
```
    When copying an InputStream into a ByteString with .readFrom(), the chunks in the underlying rope start at 256 bytes, but double each iteration up to 8192 bytes.
    
    See Also:
    
    Constant Field Values
  - MAX_READ_FROM_CHUNK_SIZE
```
static final int MAX_READ_FROM_CHUNK_SIZE
```
    See Also:
    
    Constant Field Values
  - EMPTY
```
public static final ByteString EMPTY
```
    Empty ByteString.
  - byteArrayCopier
```
private static final ByteString.ByteArrayCopier byteArrayCopier
```
  - hash
```
private int hash
```
    Cached hash value. Intentionally accessed via a data race, which is safe because of the Java Memory Model's "no out-of-thin-air values" guarantees for ints. A value of 0 implies that the hash has not been set.
  - UNSIGNED_BYTE_MASK
```
private static final int UNSIGNED_BYTE_MASK
```
    See Also:
    
    Constant Field Values
  - UNSIGNED_LEXICOGRAPHICAL_COMPARATOR
```
private static final java.util.Comparator<ByteString> UNSIGNED_LEXICOGRAPHICAL_COMPARATOR
```
    Compares two ByteStrings lexicographically, treating their contents as unsigned byte 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.
- Constructor Detail
  - ByteString
```
ByteString()
```
- Method Detail
  - byteAt
```
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 ByteString.ByteIterator returned by iterator(), and call substring(int, int) first if necessary.
    
    Parameters:
    
    index - index of byte
    
    Returns:
    
    the value
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - index < 0 or index >= size
  - internalByteAt
```
abstract byte internalByteAt(int index)
```
    Gets the byte at the given index, assumes bounds checking has already been performed.
    
    Parameters:
    
    index - index of byte
    
    Returns:
    
    the value
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - index < 0 or index >= size
  - 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 ByteString.ByteIterator.nextByte().
    
    Specified by:
    
    iterator in interface java.lang.Iterable<java.lang.Byte>
    
    Returns:
    
    the iterator
  - size
```
public abstract int size()
```
    Gets the number of bytes.
    
    Returns:
    
    size in bytes
  - isEmpty
```
public final boolean isEmpty()
```
    Returns true if the size is 0, false otherwise.
    
    Returns:
    
    true if this is zero bytes long
  - empty
```
public static final ByteString empty()
```
    Returns an empty ByteString of size 0.
  - toInt
```
private static int toInt(byte value)
```
    Returns the value of the given byte as an integer, interpreting the byte as an unsigned value. That is, returns value + 256 if value is negative; value itself otherwise.
    Note: This code was copied from UnsignedBytes.toInt(byte), as Guava libraries cannot be used in the com.google.protobuf package.
  - hexDigit
```
private static int hexDigit(char c)
```
    Returns the numeric value of the given character in hex, or -1 if invalid.
  - extractHexDigit
```
private static int extractHexDigit(java.lang.String hexString,
                                   int index)
```
    Returns the numeric value of the given character at index in hexString.
    
    Throws:
    
    java.lang.NumberFormatException - if the hexString character is invalid.
  - unsignedLexicographicalComparator
```
public static java.util.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
  - substring
```
public final ByteString substring(int beginIndex)
```
    Return the substring from beginIndex, inclusive, to the end of the string.
    
    Parameters:
    
    beginIndex - start at this index
    
    Returns:
    
    substring sharing underlying data
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if beginIndex < 0 or beginIndex > size().
  - substring
```
public abstract ByteString substring(int beginIndex,
                                     int endIndex)
```
    Return the substring from beginIndex, inclusive, to endIndex, exclusive.
    
    Parameters:
    
    beginIndex - start at this index
    
    endIndex - the last character is the one before this index
    
    Returns:
    
    substring sharing underlying data
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if beginIndex < 0, endIndex > size(), or beginIndex > endIndex.
  - startsWith
```
public final boolean startsWith(ByteString prefix)
```
    Tests if this bytestring starts with the specified prefix. Similar to String.startsWith(String)
    
    Parameters:
    
    prefix - the prefix.
    
    Returns:
    
    true if the byte sequence represented by the argument is a prefix of the byte sequence represented by this string; false otherwise.
  - endsWith
```
public final boolean endsWith(ByteString suffix)
```
    Tests if this bytestring ends with the specified suffix. Similar to String.endsWith(String)
    
    Parameters:
    
    suffix - the suffix.
    
    Returns:
    
    true if the byte sequence represented by the argument is a suffix of the byte sequence represented by this string; false otherwise.
  - fromHex
```
public static ByteString fromHex(@CompileTimeConstant
                                 java.lang.String hexString)
```
    Returns a ByteString from a hexadecimal String.
    
    Parameters:
    
    hexString - String of hexadecimal digits to create ByteString from.
    
    Throws:
    
    java.lang.NumberFormatException - if the hexString does not contain a parsable hex String.
  - copyFrom
```
public static ByteString copyFrom(byte[] bytes,
                                  int offset,
                                  int size)
```
    Copies the given bytes into a ByteString.
    
    Parameters:
    
    bytes - source array
    
    offset - offset in source array
    
    size - number of bytes to copy
    
    Returns:
    
    new ByteString
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if offset or size are out of bounds
  - copyFrom
```
public static ByteString copyFrom(byte[] bytes)
```
    Copies the given bytes into a ByteString.
    
    Parameters:
    
    bytes - to copy
    
    Returns:
    
    new ByteString
  - wrap
```
static ByteString wrap(java.nio.ByteBuffer buffer)
```
    Wraps the given bytes into a ByteString. Intended for internal usage within the library.
  - nioByteString
```
static ByteString nioByteString(java.nio.ByteBuffer buffer)
```
  - wrap
```
static ByteString wrap(byte[] bytes)
```
    Wraps the given bytes into a ByteString. Intended for internal usage within the library to force a classload of ByteString before LiteralByteString.
  - wrap
```
static ByteString wrap(byte[] bytes,
                       int offset,
                       int length)
```
    Wraps the given bytes into a ByteString. Intended for internal usage within the library to force a classload of ByteString before BoundedByteString and LiteralByteString.
  - copyFrom
```
public static ByteString copyFrom(java.nio.ByteBuffer bytes,
                                  int size)
```
    Copies the next size bytes from a java.nio.ByteBuffer into a ByteString.
    
    Parameters:
    
    bytes - source buffer
    
    size - number of bytes to copy
    
    Returns:
    
    new ByteString
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if size > bytes.remaining()
  - copyFrom
```
public static ByteString copyFrom(java.nio.ByteBuffer bytes)
```
    Copies the remaining bytes from a java.nio.ByteBuffer into a ByteString.
    
    Parameters:
    
    bytes - sourceBuffer
    
    Returns:
    
    new ByteString
  - copyFrom
```
public static ByteString copyFrom(java.lang.String text,
                                  java.lang.String charsetName)
                           throws java.io.UnsupportedEncodingException
```
    Encodes text into a sequence of bytes using the named charset and returns the result as a ByteString.
    
    Parameters:
    
    text - source string
    
    charsetName - encoding to use
    
    Returns:
    
    new ByteString
    
    Throws:
    
    java.io.UnsupportedEncodingException - if the encoding isn't found
  - copyFrom
```
public static ByteString copyFrom(java.lang.String text,
                                  java.nio.charset.Charset charset)
```
    Encodes text into a sequence of bytes using the named charset and returns the result as a ByteString.
    
    Parameters:
    
    text - source string
    
    charset - encode using this charset
    
    Returns:
    
    new ByteString
  - copyFromUtf8
```
public static ByteString copyFromUtf8(java.lang.String text)
```
    Encodes text into a sequence of UTF-8 bytes and returns the result as a ByteString.
    
    Parameters:
    
    text - source string
    
    Returns:
    
    new ByteString
  - readFrom
```
public static ByteString readFrom(java.io.InputStream streamToDrain)
                           throws java.io.IOException
```
    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.
    
    Parameters:
    
    streamToDrain - The source stream, which is read completely but not closed.
    
    Returns:
    
    A new ByteString which is made up of chunks of various sizes, depending on the behavior of the underlying stream.
    
    Throws:
    
    java.io.IOException - if there is a problem reading the underlying stream
    
    java.lang.IllegalArgumentException - if the stream supplies more than Integer.MAX_VALUE bytes
  - readFrom
```
public static ByteString readFrom(java.io.InputStream streamToDrain,
                                  int chunkSize)
                           throws java.io.IOException
```
    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:
    
    streamToDrain - The source stream, which is read completely but not closed.
    
    chunkSize - The size of the chunks in which to read the stream.
    
    Returns:
    
    A new ByteString which is made up of chunks of the given size.
    
    Throws:
    
    java.io.IOException - if there is a problem reading the underlying stream
    
    java.lang.IllegalArgumentException - if the stream supplies more than Integer.MAX_VALUE bytes
  - readFrom
```
public static ByteString readFrom(java.io.InputStream streamToDrain,
                                  int minChunkSize,
                                  int maxChunkSize)
                           throws java.io.IOException
```
    Helper method that takes the chunk size range as a parameter.
    
    Parameters:
    
    streamToDrain - the source stream, which is read completely but not closed
    
    minChunkSize - the minimum size of the chunks in which to read the stream
    
    maxChunkSize - the maximum size of the chunks in which to read the stream
    
    Returns:
    
    a new ByteString which is made up of chunks within the given size range
    
    Throws:
    
    java.io.IOException - if there is a problem reading the underlying stream
    
    java.lang.IllegalArgumentException - if the stream supplies more than Integer.MAX_VALUE bytes
  - readChunk
```
private static ByteString readChunk(java.io.InputStream in,
                                    int chunkSize)
                             throws java.io.IOException
```
    Blocks until a chunk of the given size can be made from the stream, or EOF is reached. Calls read() repeatedly in case the given stream implementation doesn't completely fill the given buffer in one read() call.
    
    Returns:
    
    A chunk of the desired size, or else a chunk as large as was available when end of stream was reached. Returns null if the given stream had no more data in it.
    
    Throws:
    
    java.io.IOException
  - concat
```
public final ByteString concat(ByteString other)
```
    Concatenate the given ByteString to this one. Short concatenations, of total size smaller than CONCATENATE_BY_COPY_SIZE, are produced by copying the underlying bytes (as per Rope.java, BAP95 . In general, the concatenate involves no copying.
    
    Parameters:
    
    other - string to concatenate
    
    Returns:
    
    a new ByteString instance
    
    Throws:
    
    java.lang.IllegalArgumentException - if the combined size of the two byte strings exceeds Integer.MAX_VALUE
  - copyFrom
```
public static ByteString copyFrom(java.lang.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.
    
    Parameters:
    
    byteStrings - strings to be concatenated
    
    Returns:
    
    new ByteString
    
    Throws:
    
    java.lang.IllegalArgumentException - if the combined size of the byte strings exceeds Integer.MAX_VALUE
  - balancedConcat
```
private static ByteString balancedConcat(java.util.Iterator<ByteString> iterator,
                                         int length)
```
  - copyTo
```
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:
    
    target - buffer to copy into
    
    offset - in the target buffer
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if the offset is negative or too large
  - copyTo
```
@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:
    
    target - buffer to copy into
    
    sourceOffset - offset within these bytes
    
    targetOffset - offset within the target buffer
    
    numberToCopy - number of bytes to copy
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if an offset or size is negative or too large
  - copyToInternal
```
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.
  - copyTo
```
public abstract void copyTo(java.nio.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)
    
    Parameters:
    
    target - ByteBuffer to copy into.
    
    Throws:
    
    java.nio.ReadOnlyBufferException - if the target is read-only
    
    java.nio.BufferOverflowException - if the target's remaining() space is not large enough to hold the data.
  - toByteArray
```
public final byte[] toByteArray()
```
    Copies bytes to a byte[].
    
    Returns:
    
    copied bytes
  - writeTo
```
public abstract void writeTo(java.io.OutputStream out)
                      throws java.io.IOException
```
    Writes a copy of the contents of this byte string to the specified output stream argument.
    
    Parameters:
    
    out - the output stream to which to write the data.
    
    Throws:
    
    java.io.IOException - if an I/O error occurs.
  - writeTo
```
final void writeTo(java.io.OutputStream out,
                   int sourceOffset,
                   int numberToWrite)
            throws java.io.IOException
```
    Writes a specified part of this byte string to an output stream.
    
    Parameters:
    
    out - the output stream to which to write the data.
    
    sourceOffset - offset within these bytes
    
    numberToWrite - number of bytes to write
    
    Throws:
    
    java.io.IOException - if an I/O error occurs.
    
    java.lang.IndexOutOfBoundsException - if an offset or size is negative or too large
  - writeToInternal
```
abstract void writeToInternal(java.io.OutputStream out,
                              int sourceOffset,
                              int numberToWrite)
                       throws java.io.IOException
```
    Internal version of writeTo(OutputStream,int,int) that assumes all error checking has already been done.
    
    Throws:
    
    java.io.IOException
  - writeTo
```
abstract void writeTo(ByteOutput byteOutput)
               throws java.io.IOException
```
    Writes this ByteString to the provided ByteOutput. Calling this method may result in multiple operations on the target ByteOutput.
    This method may expose internal backing buffers of the ByteString to the ByteOutput in order to avoid additional copying overhead. It would be possible for a malicious ByteOutput to corrupt the ByteString. Use with caution!
    
    Parameters:
    
    byteOutput - the output target to receive the bytes
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
    
    See Also:
    
    UnsafeByteOperations.unsafeWriteTo(ByteString, ByteOutput)
  - writeToReverse
```
abstract void writeToReverse(ByteOutput byteOutput)
                      throws java.io.IOException
```
    This method behaves exactly the same as writeTo(ByteOutput) unless the ByteString is a rope. For ropes, the leaf nodes are written in reverse order to the byteOutput.
    
    Parameters:
    
    byteOutput - the output target to receive the bytes
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
    
    See Also:
    
    UnsafeByteOperations#unsafeWriteToReverse(ByteString, ByteOutput)
  - asReadOnlyByteBuffer
```
public abstract java.nio.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:
    
    wrapped bytes
  - asReadOnlyByteBufferList
```
public abstract java.util.List<java.nio.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:
    
    a list of wrapped bytes
  - toString
```
public final java.lang.String toString(java.lang.String charsetName)
                                throws java.io.UnsupportedEncodingException
```
    Constructs a new String by decoding the bytes using the specified charset.
    
    Parameters:
    
    charsetName - encode using this charset
    
    Returns:
    
    new string
    
    Throws:
    
    java.io.UnsupportedEncodingException - if charset isn't recognized
  - toString
```
public final java.lang.String toString(java.nio.charset.Charset charset)
```
    Constructs a new String by decoding the bytes using the specified charset. Returns the same empty String if empty.
    
    Parameters:
    
    charset - encode using this charset
    
    Returns:
    
    new string
  - toStringInternal
```
protected abstract java.lang.String toStringInternal(java.nio.charset.Charset charset)
```
    Constructs a new String by decoding the bytes using the specified charset.
    
    Parameters:
    
    charset - encode using this charset
    
    Returns:
    
    new string
  - toStringUtf8
```
public final java.lang.String toStringUtf8()
```
    Constructs a new String by decoding the bytes as UTF-8.
    
    Returns:
    
    new string using UTF-8 encoding
  - 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:
    
    whether the bytes in this ByteString are a well-formed UTF-8 byte sequence
  - partialIsValidUtf8
```
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:
    
    state - 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 - offset of the first byte to check
    
    length - number of bytes to check
    
    Returns:
    
    -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.
  - equals
```
public abstract boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public final int hashCode()
```
    Compute the hashCode using the traditional algorithm from ByteString.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    hashCode value
  - newInput
```
public abstract java.io.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:
    
    an input stream that returns the bytes of this byte string.
  - 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:
    
    stream based on wrapped data
  - newOutput
```
public static ByteString.Output newOutput(int initialCapacity)
```
    Creates a new ByteString.Output with the given initial capacity. Call ByteString.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.
    
    Parameters:
    
    initialCapacity - estimate of number of bytes to be written
    
    Returns:
    
    OutputStream for building a ByteString
  - newOutput
```
public static ByteString.Output newOutput()
```
    Creates a new ByteString.Output. Call ByteString.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:
    
    OutputStream for building a ByteString
  - newCodedBuilder
```
static ByteString.CodedBuilder newCodedBuilder(int size)
```
    Constructs a new ByteString builder, which allows you to efficiently construct a ByteString by writing to a CodedOutputStream. Using this is much more efficient than calling newOutput() and wrapping that in a CodedOutputStream.
    This is package-private because it's a somewhat confusing interface. Users can call MessageLite.toByteString() instead of calling this directly.
    
    Parameters:
    
    size - The target byte size of the ByteString. You must write exactly this many bytes before building the result.
    
    Returns:
    
    the builder
  - 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:
    
    tree depth or zero
  - 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:
    
    true if the tree is flat enough
  - peekCachedHashCode
```
protected final int peekCachedHashCode()
```
    Return the cached hash code if available.
    
    Returns:
    
    value of cached hash code or 0 if not computed yet
  - partialHash
```
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:
    
    h - starting hash value
    
    offset - offset into this value to start looking at data values
    
    length - number of data values to include in the hash computation
    
    Returns:
    
    ending hash value
  - checkIndex
```
static void checkIndex(int index,
                       int size)
```
    Checks that the given index falls within the specified array size.
    
    Parameters:
    
    index - the index position to be tested
    
    size - the length of the array
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if the index does not fall within the array.
  - checkRange
```
@CanIgnoreReturnValue
static int checkRange(int startIndex,
                      int endIndex,
                      int size)
```
    Checks that the given range falls within the bounds of an array
    
    Parameters:
    
    startIndex - the start index of the range (inclusive)
    
    endIndex - the end index of the range (exclusive)
    
    size - the size of the array.
    
    Returns:
    
    the length of the range.
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - some or all of the range falls outside of the array.
  - toString
```
public final java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - truncateAndEscapeForDisplay
```
private java.lang.String truncateAndEscapeForDisplay()
```

Class ByteString

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Field Detail

serialVersionUID

CONCATENATE_BY_COPY_SIZE

MIN_READ_FROM_CHUNK_SIZE

MAX_READ_FROM_CHUNK_SIZE

EMPTY

byteArrayCopier

hash

UNSIGNED_BYTE_MASK

UNSIGNED_LEXICOGRAPHICAL_COMPARATOR

Constructor Detail

ByteString

Method Detail

byteAt

internalByteAt

iterator

size

isEmpty

empty

toInt

hexDigit

extractHexDigit

unsignedLexicographicalComparator

substring

substring

startsWith

endsWith

fromHex

copyFrom

copyFrom

wrap

nioByteString

wrap

wrap

copyFrom

copyFrom

copyFrom

copyFrom

copyFromUtf8

readFrom

readFrom

readFrom

readChunk

concat

copyFrom

balancedConcat

copyTo

copyTo

copyToInternal

copyTo

toByteArray

writeTo

writeTo

writeToInternal

writeTo

writeToReverse

asReadOnlyByteBuffer

asReadOnlyByteBufferList

toString

toString

toStringInternal

toStringUtf8

isValidUtf8

partialIsValidUtf8

equals

hashCode

newInput

newCodedInput

newOutput

newOutput

newCodedBuilder

getTreeDepth

isBalanced