public abstract class ByteString
extends java.lang.Object
implements java.lang.Iterable<java.lang.Byte>, java.io.Serializable
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.
| Modifier and Type | Class and Description |
|---|---|
static interface |
ByteString.ByteIterator
This interface extends
Iterator<Byte>, so that we can return an
unboxed byte. |
static class |
ByteString.Output
Outputs to a
ByteString instance. |
| Modifier and Type | Field and Description |
|---|---|
static ByteString |
EMPTY
Empty
ByteString. |
| Modifier and Type | Method and 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. |
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(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 |
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.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.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 |
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)
Copies bytes into a buffer.
|
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). |
boolean |
endsWith(ByteString suffix)
Tests if this bytestring ends with the specified suffix.
|
abstract boolean |
equals(java.lang.Object o) |
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. |
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. |
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. |
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.
|
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) |
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[]. |
java.lang.String |
toString() |
java.lang.String |
toString(java.nio.charset.Charset charset)
Constructs a new
String by decoding the bytes using the
specified charset. |
java.lang.String |
toString(java.lang.String charsetName)
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. |
abstract void |
writeTo(java.io.OutputStream out)
Writes a copy of the contents of this byte string to the specified output stream argument.
|
public static final ByteString EMPTY
ByteString.public abstract byte byteAt(int index)
ByteString.ByteIterator returned by iterator(), and call substring(int, int) first if necessary.index - index of bytejava.lang.IndexOutOfBoundsException - index < 0 or index >= sizepublic final ByteString.ByteIterator iterator()
ByteString.ByteIterator over the bytes in the ByteString.
To avoid auto-boxing, you may get the iterator manually and call
ByteString.ByteIterator.nextByte().iterator in interface java.lang.Iterable<java.lang.Byte>public abstract int size()
public final boolean isEmpty()
true if the size is 0, false otherwise.public final ByteString substring(int beginIndex)
beginIndex, inclusive, to the end of the
string.beginIndex - start at this indexjava.lang.IndexOutOfBoundsException - if beginIndex < 0 or
beginIndex > size().public abstract ByteString substring(int beginIndex, int endIndex)
beginIndex, inclusive, to endIndex, exclusive.beginIndex - start at this indexendIndex - the last character is the one before this indexjava.lang.IndexOutOfBoundsException - if beginIndex < 0,
endIndex > size(), or beginIndex > endIndex.public final boolean startsWith(ByteString prefix)
String.startsWith(String)prefix - the prefix.true if the byte sequence represented by the
argument is a prefix of the byte sequence represented by
this string; false otherwise.public final boolean endsWith(ByteString suffix)
String.endsWith(String)suffix - the suffix.true if the byte sequence represented by the
argument is a suffix of the byte sequence represented by
this string; false otherwise.public static ByteString copyFrom(byte[] bytes, int offset, int size)
ByteString.bytes - source arrayoffset - offset in source arraysize - number of bytes to copyByteStringpublic static ByteString copyFrom(byte[] bytes)
ByteString.bytes - to copyByteStringpublic static ByteString copyFrom(java.nio.ByteBuffer bytes, int size)
size bytes from a java.nio.ByteBuffer into
a ByteString.bytes - source buffersize - number of bytes to copyByteStringpublic static ByteString copyFrom(java.nio.ByteBuffer bytes)
java.nio.ByteBuffer into
a ByteString.bytes - sourceBufferByteStringpublic static ByteString copyFrom(java.lang.String text, java.lang.String charsetName) throws java.io.UnsupportedEncodingException
text into a sequence of bytes using the named charset
and returns the result as a ByteString.text - source stringcharsetName - encoding to useByteStringjava.io.UnsupportedEncodingException - if the encoding isn't foundpublic static ByteString copyFrom(java.lang.String text, java.nio.charset.Charset charset)
text into a sequence of bytes using the named charset
and returns the result as a ByteString.text - source stringcharset - encode using this charsetByteStringpublic static ByteString copyFromUtf8(java.lang.String text)
text into a sequence of UTF-8 bytes and returns the
result as a ByteString.text - source stringByteStringpublic static ByteString readFrom(java.io.InputStream streamToDrain) throws java.io.IOException
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.
streamToDrain - The source stream, which is read completely
but not closed.ByteString which is made up of chunks of
various sizes, depending on the behavior of the underlying
stream.java.io.IOException - IOException is thrown if there is a problem
reading the underlying stream.public static ByteString readFrom(java.io.InputStream streamToDrain, int chunkSize) throws java.io.IOException
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.
streamToDrain - The source stream, which is read completely
but not closed.chunkSize - The size of the chunks in which to read the
stream.ByteString which is made up of chunks of
the given size.java.io.IOException - IOException is thrown if there is a problem
reading the underlying stream.public static ByteString readFrom(java.io.InputStream streamToDrain, int minChunkSize, int maxChunkSize) throws java.io.IOException
java.io.IOExceptionpublic final ByteString concat(ByteString other)
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.other - string to concatenateByteString instancepublic static ByteString copyFrom(java.lang.Iterable<ByteString> byteStrings)
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.
byteStrings - strings to be concatenatedByteStringpublic void copyTo(byte[] target,
int offset)
target - buffer to copy intooffset - in the target bufferjava.lang.IndexOutOfBoundsException - if the offset is negative or too largepublic final void copyTo(byte[] target,
int sourceOffset,
int targetOffset,
int numberToCopy)
target - buffer to copy intosourceOffset - offset within these bytestargetOffset - offset within the target buffernumberToCopy - number of bytes to copyjava.lang.IndexOutOfBoundsException - if an offset or size is negative or too
largeprotected abstract void copyToInternal(byte[] target,
int sourceOffset,
int targetOffset,
int numberToCopy)
copyTo(byte[],int,int,int).
It assumes that all error checking has already been performed and that
numberToCopy > 0.public abstract void copyTo(java.nio.ByteBuffer target)
target - ByteBuffer to copy into.java.nio.ReadOnlyBufferException - if the target is read-onlyjava.nio.BufferOverflowException - if the target's
remaining() space is not large enough to hold the data.public final byte[] toByteArray()
byte[].public abstract void writeTo(java.io.OutputStream out)
throws java.io.IOException
out - the output stream to which to write the data.java.io.IOException - if an I/O error occurs.public abstract java.nio.ByteBuffer asReadOnlyByteBuffer()
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.public abstract java.util.List<java.nio.ByteBuffer> asReadOnlyByteBufferList()
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.
public final java.lang.String toString(java.lang.String charsetName)
throws java.io.UnsupportedEncodingException
String by decoding the bytes using the
specified charset.charsetName - encode using this charsetjava.io.UnsupportedEncodingException - if charset isn't recognizedpublic final java.lang.String toString(java.nio.charset.Charset charset)
String by decoding the bytes using the
specified charset. Returns the same empty String if empty.charset - encode using this charsetprotected abstract java.lang.String toStringInternal(java.nio.charset.Charset charset)
String by decoding the bytes using the
specified charset.charset - encode using this charsetpublic final java.lang.String toStringUtf8()
String by decoding the bytes as UTF-8.public abstract boolean isValidUtf8()
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.
ByteString are a
well-formed UTF-8 byte sequenceprotected abstract int partialIsValidUtf8(int state,
int offset,
int length)
ByteString segments.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 bytesoffset - offset of the first byte to checklength - number of bytes to check-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.public abstract boolean equals(java.lang.Object o)
equals in class java.lang.Objectpublic final int hashCode()
ByteString.hashCode in class java.lang.Objectpublic abstract java.io.InputStream newInput()
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.
public abstract CodedInputStream newCodedInput()
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().public static ByteString.Output newOutput(int initialCapacity)
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.
initialCapacity - estimate of number of bytes to be writtenOutputStream for building a ByteStringpublic static ByteString.Output newOutput()
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.
OutputStream for building a ByteStringprotected abstract int getTreeDepth()
ByteString, if any,
whose root is this node. If this is a leaf node, return 0.protected abstract boolean isBalanced()
true if this ByteString is literal (a leaf node) or a
flat-enough tree in the sense of RopeByteString.protected final int peekCachedHashCode()
protected abstract int partialHash(int h,
int offset,
int length)
h - starting hash valueoffset - offset into this value to start looking at data valueslength - number of data values to include in the hash computationpublic final java.lang.String toString()
toString in class java.lang.Object