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 |
---|---|
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. |
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) . |
Modifier and Type | Field and 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.
|
Constructor and Description |
---|
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. |
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.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. |
(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. |
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) |
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. |
(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. |
static final int CONCATENATE_BY_COPY_SIZE
concat(ByteString)
.
The trade-off is copy size versus the overhead of creating tree nodes
in RopeByteString
.static final int MIN_READ_FROM_CHUNK_SIZE
static final int MAX_READ_FROM_CHUNK_SIZE
public static final ByteString EMPTY
ByteString
.private static final ByteString.ByteArrayCopier byteArrayCopier
private int hash
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 >= size
public 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 copyByteString
public static ByteString copyFrom(byte[] bytes)
ByteString
.bytes
- to copyByteString
static ByteString wrap(java.nio.ByteBuffer buffer)
ByteString
. Intended for internal only usage.static ByteString wrap(byte[] bytes)
ByteString
. Intended for internal only
usage to force a classload of ByteString before LiteralByteString.static ByteString wrap(byte[] bytes, int offset, int length)
ByteString
. Intended for internal only
usage to force a classload of ByteString before BoundedByteString and
LiteralByteString.public 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 copyByteString
public static ByteString copyFrom(java.nio.ByteBuffer bytes)
java.nio.ByteBuffer
into
a ByteString
.bytes
- sourceBufferByteString
public 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 useByteString
java.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 charsetByteString
public static ByteString copyFromUtf8(java.lang.String text)
text
into a sequence of UTF-8 bytes and returns the
result as a ByteString
.text
- source stringByteString
public 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.IOException
private static ByteString readChunk(java.io.InputStream in, int chunkSize) throws java.io.IOException
java.io.IOException
public 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 concatenatedByteString
private static ByteString balancedConcat(java.util.Iterator<ByteString> iterator, int length)
public 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.final void writeTo(java.io.OutputStream out, int sourceOffset, int numberToWrite) throws java.io.IOException
out
- the output stream to which to write the data.sourceOffset
- offset within these bytesnumberToWrite
- number of bytes to writejava.io.IOException
- if an I/O error occurs.java.lang.IndexOutOfBoundsException
- if an offset or size is negative or too largeabstract void writeToInternal(java.io.OutputStream out, int sourceOffset, int numberToWrite) throws java.io.IOException
writeTo(OutputStream,int,int)
that assumes
all error checking has already been done.java.io.IOException
abstract void writeTo(ByteOutput byteOutput) throws java.io.IOException
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!
byteOutput
- the output target to receive the bytesjava.io.IOException
- if an I/O error occursUnsafeByteOperations.unsafeWriteTo(ByteString, ByteOutput)
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.Object
public final int hashCode()
ByteString
.hashCode
in class java.lang.Object
public 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 ByteString
public 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 ByteString
static ByteString.CodedBuilder newCodedBuilder(int size)
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.
size
- The target byte size of the ByteString
. You must write
exactly this many bytes before building the result.protected 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 computationstatic void checkIndex(int index, int size)
index
- the index position to be testedsize
- the length of the arrayjava.lang.IndexOutOfBoundsException
- if the index does not fall within the array.static int checkRange(int startIndex, int endIndex, int size)
startIndex
- the start index of the range (inclusive)endIndex
- the end index of the range (exclusive)size
- the size of the array.java.lang.IndexOutOfBoundsException
- some or all of the range falls outside of the array.public final java.lang.String toString()
toString
in class java.lang.Object