Package com.google.protobuf

Class ByteString

java.lang.Object
com.google.protobuf.ByteString
All Implemented Interfaces:
Iterable<Byte>
public abstract class ByteString extends Object implements Iterable<Byte>
Immutable sequence of bytes. Substring is supported by sharing the reference to the immutable underlying bytes, as with String. Concatenation is likewise supported without copying (long strings) by building a tree of pieces in RopeByteString.

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.

Author:
crazybob@google.com Bob Lee, kenton@google.com Kenton Varda, carlanton@google.com Carl Haverl, martinrb@google.com Martin Buchholz

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    ByteString.ByteIterator
    This interface extends Iterator<Byte>, so that we can return an unboxed byte.
    static final class 
    ByteString.Output
    Outputs to a ByteString instance.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final ByteString
    EMPTY
    Empty ByteString.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract ByteBuffer
    asReadOnlyByteBuffer()
    Constructs a read-only java.nio.ByteBuffer whose content is equal to the contents of this byte string.
    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.
    abstract byte
    byteAt(int index)
    Gets the byte at the given index.
    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(Iterable<ByteString> byteStrings)
    Concatenates all byte strings in the iterable and returns the result.
    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.
    static ByteString
    copyFrom(ByteBuffer bytes)
    Copies the remaining bytes from a java.nio.ByteBuffer into a ByteString.
    static ByteString
    copyFrom(ByteBuffer bytes, int size)
    Copies the next size bytes from a java.nio.ByteBuffer into a ByteString.
    static ByteString
    copyFromUtf8(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)
    Copies bytes into a buffer.
    abstract void
    copyTo(ByteBuffer target)
    Copies bytes into a ByteBuffer.
    protected abstract void
    copyToInternal(byte[] target, int sourceOffset, int targetOffset, int numberToCopy)
    Internal (package private) implementation of
    boolean
    endsWith(ByteString suffix)
    Tests if this bytestring ends with the specified suffix.
    abstract boolean
    equals(Object o)
     
    protected abstract int
    getTreeDepth()
    Return the depth of the tree representing this ByteString, if any, whose root is this node.
    abstract int
    hashCode()
    Return a non-zero hashCode depending only on the sequence of bytes in this ByteString.
    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.
    abstract ByteString.ByteIterator
    iterator()
    Return a ByteString.ByteIterator over the bytes in the ByteString.
    abstract CodedInputStream
    newCodedInput()
    Creates a CodedInputStream which can be used to read the bytes.
    abstract 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.
    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 abstract int
    peekCachedHashCode()
    Return the cached hash code if available.
    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.
    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.
    static ByteString
    readFrom(InputStream streamToDrain, int minChunkSize, int maxChunkSize)
     
    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[].
    String
    toString()
     
    abstract String
    toString(String charsetName)
    Constructs a new String by decoding the bytes using the specified charset.
    String
    toStringUtf8()
    Constructs a new String by decoding the bytes as UTF-8.
    abstract void
    writeTo(OutputStream out)
    Writes the complete contents of this byte string to the specified output stream argument.

    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 Details

    • EMPTY

      public static final ByteString EMPTY
      Empty ByteString.

  • Method Details

    • 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:
      ArrayIndexOutOfBoundsException - index is < 0 or >= size

    • iterator

      public abstract 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 Iterable<Byte>
      Returns:
      the iterator

    • size

      public abstract int size()
      Gets the number of bytes.
      Returns:
      size in bytes

    • isEmpty

      public boolean isEmpty()
      Returns true if the size is 0, false otherwise.
      Returns:
      true if this is zero bytes long

    • substring

      public 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:
      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:
      IndexOutOfBoundsException - if beginIndex < 0, endIndex > size(), or beginIndex > endIndex.

    • startsWith

      public 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 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.

    • 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

    • copyFrom

      public static ByteString copyFrom(byte[] bytes)
      Copies the given bytes into a ByteString.
      Parameters:
      bytes - to copy
      Returns:
      new ByteString

    • copyFrom

      public static ByteString copyFrom(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

    • copyFrom

      public static ByteString copyFrom(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(String text, String charsetName) throws 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:
      UnsupportedEncodingException - if the encoding isn't found

    • copyFromUtf8

      public static ByteString copyFromUtf8(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(InputStream streamToDrain) throws 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. If the caller knows the precise length of the stream and wishes to avoid all unnecessary copies and allocations, consider using the two-argument version of this method, below.
      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:
      IOException - IOException is thrown if there is a problem reading the underlying stream.

    • readFrom

      public static ByteString readFrom(InputStream streamToDrain, int chunkSize) throws 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. In particular, if the chunkSize is precisely the same as the length of the stream, unnecessary allocations and copies will be avoided. Otherwise, the chunks will be of the given size, except for the last chunk, which will be resized (via a reallocation and copy) to contain the remainder of the stream.
      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:
      IOException - IOException is thrown if there is a problem reading the underlying stream.

    • readFrom

      public static ByteString readFrom(InputStream streamToDrain, int minChunkSize, int maxChunkSize) throws IOException
      Throws:
      IOException

    • concat

      public 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

    • copyFrom

      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.

      Parameters:
      byteStrings - strings to be concatenated
      Returns:
      new ByteString

    • copyTo

      public void copyTo(byte[] target, int offset)
      Copies bytes into a buffer at the given offset.
      Parameters:
      target - buffer to copy into
      offset - in the target buffer
      Throws:
      IndexOutOfBoundsException - if the offset is negative or too large

    • copyTo

      public void copyTo(byte[] target, int sourceOffset, int targetOffset, int numberToCopy)
      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:
      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

      public abstract void copyTo(ByteBuffer target)
      Copies bytes into a ByteBuffer.
      Parameters:
      target - ByteBuffer to copy into.
      Throws:
      ReadOnlyBufferException - if the target is read-only
      BufferOverflowException - if the target's remaining() space is not large enough to hold the data.

    • toByteArray

      public byte[] toByteArray()
      Copies bytes to a byte[].
      Returns:
      copied bytes

    • writeTo

      public abstract void writeTo(OutputStream out) throws IOException
      Writes the complete contents of this byte string to the specified output stream argument.
      Parameters:
      out - the output stream to which to write the data.
      Throws:
      IOException - if an I/O error occurs.

    • 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:
      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:
      a list of wrapped bytes

    • toString

      public abstract String toString(String charsetName) throws UnsupportedEncodingException
      Constructs a new String by decoding the bytes using the specified charset.
      Parameters:
      charsetName - encode using this charset
      Returns:
      new string
      Throws:
      UnsupportedEncodingException - if charset isn't recognized

    • toStringUtf8

      public 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(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public abstract int hashCode()
      Return a non-zero hashCode depending only on the sequence of bytes in this ByteString.
      Overrides:
      hashCode in class Object
      Returns:
      hashCode value for this object

    • 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 {@link InputStream#read(byte[]), InputStream.read(byte[],int,int) and InputStream.skip(long) will read/skip as many bytes as are available.

      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

    • 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 abstract 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

    • toString

      public String toString()
      Overrides:
      toString in class Object