# 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](https://docs.oracle.com/javase/8/docs/api/java/lang/String.html), [ByteBuffer](https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html), [InputStream](https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html), [OutputStream](https://docs.oracle.com/javase/8/docs/api/java/io/OutputStream.html). Also provides a
conversion to [CodedInputStream](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.CodedInputStream).

Like [String](https://docs.oracle.com/javase/8/docs/api/java/lang/String.html), the contents of a [ByteString](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html) \> ByteString

## Implements

[Iterable\<Byte\>](https://docs.oracle.com/javase/8/docs/api/java/lang/Iterable<java/lang/Byte>.html), [Serializable](https://docs.oracle.com/javase/8/docs/api/java/io/Serializable.html)

## Inherited Members

[Object.clone()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#clone--) [Object.equals(Object)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#equals-java.lang.Object-) [Object.finalize()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#finalize--) [Object.getClass()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#getClass--) [Object.hashCode()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#hashCode--) [Object.notify()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notify--) [Object.notifyAll()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notifyAll--) [Object.toString()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#toString--) [Object.wait()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait--) [Object.wait(long)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-) [Object.wait(long,int)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-int-)

## Static Fields

### EMPTY

    public static final ByteString EMPTY

Empty `ByteString`.

| **Field Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString` |   |

## Static Methods

### copyFrom(byte\[\] bytes)

    public static ByteString copyFrom(byte[] bytes)

Copies the given bytes into a `ByteString`.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `bytes` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html[]` to copy |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html[]` source array |
| `offset` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` offset in source array |
| `size` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` number of bytes to copy |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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` | `https://docs.oracle.com/javase/8/docs/api/java/lang/Iterable.html<https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString>` strings to be concatenated |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` source string |
| `charsetName` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` encoding to use |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString` | new `ByteString` |

| **Exceptions** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/io/UnsupportedEncodingException.html` | 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` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` source string |
| `charset` | `https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html` encode using this charset |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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` | `https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html` sourceBuffer |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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` | `https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html` source buffer |
| `size` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` number of bytes to copy |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` source string |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString` | new `ByteString` |

### newOutput()

    public static ByteString.Output newOutput()

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

A [ByteString.Output](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString.Output) offers the same functionality as a ByteArrayOutputStream, except that it returns a [ByteString](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString) rather than a `byte
array`.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString.Output) offers the same functionality as a ByteArrayOutputStream, except that it returns a [ByteString](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString) rather than a `byte`
array.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `initialCapacity` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` estimate of number of bytes to be written |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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` | `https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html` The source stream, which is read completely but not closed. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString` | A new `ByteString` which is made up of chunks of various sizes, depending on the behavior of the underlying stream. |

| **Exceptions** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/io/IOException.html` | 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` | `https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html` The source stream, which is read completely but not closed. |
| `chunkSize` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` The size of the chunks in which to read the stream. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString` | A new `ByteString` which is made up of chunks of the given size. |

| **Exceptions** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/io/IOException.html` | 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` | `https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html` the source stream, which is read completely but not closed |
| `minChunkSize` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` the minimum size of the chunks in which to read the stream |
| `maxChunkSize` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` the maximum size of the chunks in which to read the stream |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString` | a new `ByteString` which is made up of chunks within the given size range |

| **Exceptions** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/io/IOException.html` | if there is a problem reading the underlying stream |

### unsignedLexicographicalComparator()

    public static Comparator<ByteString> unsignedLexicographicalComparator()

Returns a [Comparator](https://docs.oracle.com/javase/8/docs/api/java/util/Comparator.html) which compares [ByteString](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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** |
| `https://docs.oracle.com/javase/8/docs/api/java/util/Comparator.html<https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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** |
| `https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html` | 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** |
| `https://docs.oracle.com/javase/8/docs/api/java/util/List.html<https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html>` | 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()](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString#com_google_protobuf_ByteString_iterator__), and call [#substring(int, int)](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString#com_google_protobuf_ByteString_substring_int_int_) first if necessary.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `index` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` index of byte |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | 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](http://www.cs.ubc.ca/local/reading/proceedings/spe91-95/spe/vol25/issue12/spe986.pdf). In general, the concatenate involves no copying.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `other` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString` string to concatenate |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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)](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString#com_google_protobuf_ByteString_substring_int_int_). Example: `byteString.substring(start, end).copyTo(target, offset)`

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `target` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html[]` buffer to copy into |
| `offset` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` 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` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html[]` buffer to copy into |
| `sourceOffset` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` offset within these bytes |
| `targetOffset` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` offset within the target buffer |
| `numberToCopy` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` 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)](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString#com_google_protobuf_ByteString_substring_int_int_). Example: `byteString.substring(start, end).copyTo(target)`

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `target` | `https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html` 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)](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString#com_google_protobuf_ByteString_copyTo_byte___int_int_int_). It assumes
that all error checking has already been performed and that `numberToCopy > 0`.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `target` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html[]` |
| `sourceOffset` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |
| `targetOffset` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |
| `numberToCopy` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |

### 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` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString` the suffix. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | `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` | `https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |   |

**Overrides** [Object.equals(Object)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#equals-java.lang.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** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | tree depth or zero |

### hashCode()

    public final int hashCode()

Compute the hashCode using the traditional algorithm from [ByteString](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString).

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | hashCode value |

**Overrides** [Object.hashCode()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#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** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | true if the tree is flat enough |

### isEmpty()

    public final boolean isEmpty()

Returns `true` if the size is `0`, `false` otherwise.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | 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** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | whether the bytes in this `ByteString` are a well-formed UTF-8 byte sequence |

### iterator()

    public ByteString.ByteIterator iterator()

Return a [ByteString.ByteIterator](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString.ByteIterator` | the iterator |

### newCodedInput()

    public abstract CodedInputStream newCodedInput()

Creates a [CodedInputStream](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.CodedInputStream) which can be used to read the bytes. Using this is often
more efficient than creating a [CodedInputStream](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.CodedInputStream) that wraps the result of [#newInput()](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString#com_google_protobuf_ByteString_newInput__).

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.CodedInputStream` | stream based on wrapped data |

### newInput()

    public abstract InputStream newInput()

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

The [InputStream](https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html) 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](https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html) might **not** be thread safe.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html` | 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` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` starting hash value |
| `offset` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` offset into this value to start looking at data values |
| `length` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` number of data values to include in the hash computation |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | 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` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` 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` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` offset of the first byte to check |
| `length` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` number of bytes to check |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | `-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** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | value of cached hash code or 0 if not computed yet |

### size()

    public abstract int size()

Gets the number of bytes.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | 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` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString` the prefix. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | `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` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` start at this index |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.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` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` start at this index |
| `endIndex` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` the last character is the one before this index |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.ByteString` | substring sharing underlying data |

### toByteArray()

    public final byte[] toByteArray()

Copies bytes to a `byte[]`.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html[]` | copied bytes |

### toString()

    public final String toString()

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` |   |

**Overrides** [Object.toString()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#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` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` encode using this charset |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` | new string |

| **Exceptions** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/io/UnsupportedEncodingException.html` | 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` | `https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html` encode using this charset |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` | 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` | `https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html` encode using this charset |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` | new string |

### toStringUtf8()

    public final String toStringUtf8()

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

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` | 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` | `https://docs.oracle.com/javase/8/docs/api/java/io/OutputStream.html` the output stream to which to write the data. |

| **Exceptions** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/io/IOException.html` | if an I/O error occurs. |