public abstract class ByteString
extends java.lang.Object
implements java.lang.Iterable<java.lang.Byte>, java.io.Serializable
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.
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.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.lang.String charset)
Constructs a new
String by decoding the bytes using the specified charset. |
protected abstract java.lang.String |
toStringInternal(java.lang.String 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 >= 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
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 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
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
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.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 charset) throws java.io.UnsupportedEncodingException
String
by decoding the bytes using the specified charset. Returns the same empty String
if empty.charset
- encode using this charsetjava.io.UnsupportedEncodingException
protected abstract java.lang.String toStringInternal(java.lang.String charset) throws java.io.UnsupportedEncodingException
String
by decoding the bytes using the specified charset.charset
- encode using this charsetjava.io.UnsupportedEncodingException
public 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
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 computationpublic final java.lang.String toString()
toString
in class java.lang.Object