Field Detail

• EMPTY

  public static final ByteString EMPTY

  Empty 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

• 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

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

• 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

• 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 - IOException is thrown if there is a problem reading the underlying stream.

• 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 - IOException is thrown if there is a problem reading the underlying stream.

• readFrom

  public static ByteString readFrom(java.io.InputStream streamToDrain, int minChunkSize, int maxChunkSize) throws java.io.IOException

  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

• 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

• 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

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

• 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

• 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

• 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

• toString

  public final java.lang.String toString()

  Overrides:

  toString in class java.lang.Object