Class ByteString
- All Implemented Interfaces:
Serializable
,Iterable<Byte>
- Direct Known Subclasses:
ByteString.LeafByteString
,RopeByteString
byte[]
, String
, ByteBuffer
, InputStream
, OutputStream
. Also provides a
conversion to CodedInputStream
.
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.
Substring is supported by sharing the reference to the immutable underlying bytes.
Concatenation is likewise supported without copying (long strings) by building a tree of pieces
in RopeByteString
.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static class
private static final class
Implementation ofByteArrayCopier
which usesArrays.copyOfRange(T[], int, int)
.private static final class
This class is used to represent the substring of aByteString
over a single byte array.private static interface
An interface to efficiently copybyte[]
.static interface
This interface extendsIterator<Byte>
, so that we can return an unboxedbyte
.(package private) static final class
SeenewCodedBuilder(int)
.(package private) static class
Base class for leafByteString
s (i.e.private static class
This class implements aByteString
backed by a single array of bytes, contiguous in memory.private static final class
AByteString
that wraps around aByteBuffer
.static final class
Outputs to aByteString
instance.private static final class
Implementation ofByteArrayCopier
which usesSystem.arraycopy(java.lang.Object, int, java.lang.Object, int, int)
. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final ByteString.ByteArrayCopier
(package private) static final int
When two strings to be concatenated have a combined length shorter than this, we just copy their bytes onconcat(ByteString)
.static final ByteString
EmptyByteString
.private int
Cached hash value.(package private) static final int
(package private) static final int
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.private static final long
private static final int
private static final Comparator
<ByteString> Compares twoByteString
s lexicographically, treating their contents as unsigned byte values between 0 and 255 (inclusive). -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract ByteBuffer
Constructs a read-onlyjava.nio.ByteBuffer
whose content is equal to the contents of this byte string.abstract List
<ByteBuffer> Constructs a list of read-onlyjava.nio.ByteBuffer
objects such that the concatenation of their contents is equal to the contents of this byte string.private static ByteString
balancedConcat
(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 arrayfinal ByteString
concat
(ByteString other) Concatenate the givenByteString
to this one.static ByteString
copyFrom
(byte[] bytes) Copies the given bytes into aByteString
.static ByteString
copyFrom
(byte[] bytes, int offset, int size) Copies the given bytes into aByteString
.static ByteString
copyFrom
(Iterable<ByteString> byteStrings) Concatenates all byte strings in the iterable and returns the result.static ByteString
Encodestext
into a sequence of bytes using the named charset and returns the result as aByteString
.static ByteString
Encodestext
into a sequence of bytes using the named charset and returns the result as aByteString
.static ByteString
copyFrom
(ByteBuffer bytes) Copies the remaining bytes from ajava.nio.ByteBuffer
into aByteString
.static ByteString
copyFrom
(ByteBuffer bytes, int size) Copies the nextsize
bytes from ajava.nio.ByteBuffer
into aByteString
.static ByteString
copyFromUtf8
(String text) Encodestext
into a sequence of UTF-8 bytes and returns the result as aByteString
.void
copyTo
(byte[] target, int offset) Copies bytes into a buffer at the given offset.final void
copyTo
(byte[] target, int sourceOffset, int targetOffset, int numberToCopy) Deprecated.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 ofcopyTo(byte[],int,int,int)
.static final ByteString
empty()
Returns an emptyByteString
of size0
.final boolean
endsWith
(ByteString suffix) Tests if this bytestring ends with the specified suffix.abstract boolean
private static int
extractHexDigit
(String hexString, int index) Returns the numeric value of the given character at index in hexString.static ByteString
Returns aByteString
from a hexadecimal String.protected abstract int
Return the depth of the tree representing thisByteString
, if any, whose root is this node.final int
hashCode()
Compute the hashCode using the traditional algorithm fromByteString
.private static int
hexDigit
(char c) Returns the numeric value of the given character in hex, or -1 if invalid.(package private) abstract byte
internalByteAt
(int index) Gets the byte at the given index, assumes bounds checking has already been performed.protected abstract boolean
Returntrue
if this ByteString is literal (a leaf node) or a flat-enough tree in the sense ofRopeByteString
.final boolean
isEmpty()
Returnstrue
if the size is0
,false
otherwise.abstract boolean
Tells whether thisByteString
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.iterator()
Return aByteString.ByteIterator
over the bytes in the ByteString.(package private) static ByteString.CodedBuilder
newCodedBuilder
(int size) Constructs a newByteString
builder, which allows you to efficiently construct aByteString
by writing to aCodedOutputStream
.abstract CodedInputStream
Creates aCodedInputStream
which can be used to read the bytes.abstract InputStream
newInput()
Creates anInputStream
which can be used to read the bytes.static ByteString.Output
Creates a newByteString.Output
.static ByteString.Output
newOutput
(int initialCapacity) Creates a newByteString.Output
with the given initial capacity.(package private) static ByteString
nioByteString
(ByteBuffer buffer) 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 final int
Return the cached hash code if available.private static ByteString
readChunk
(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
(InputStream streamToDrain) Completely reads the given stream's bytes into aByteString
, 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 aByteString
, blocking if necessary until all bytes are read through to the end of the stream.static ByteString
readFrom
(InputStream streamToDrain, int minChunkSize, int maxChunkSize) Helper method that takes the chunk size range as a parameter.abstract int
size()
Gets the number of bytes.final boolean
startsWith
(ByteString prefix) Tests if this bytestring starts with the specified prefix.final ByteString
substring
(int beginIndex) Return the substring frombeginIndex
, inclusive, to the end of the string.abstract ByteString
substring
(int beginIndex, int endIndex) Return the substring frombeginIndex
, inclusive, toendIndex
, exclusive.final byte[]
Copies bytes to abyte[]
.private static int
toInt
(byte value) Returns the value of the given byte as an integer, interpreting the byte as an unsigned value.final String
toString()
final String
Constructs a newString
by decoding the bytes using the specified charset.final String
Constructs a newString
by decoding the bytes using the specified charset.protected abstract String
toStringInternal
(Charset charset) Constructs a newString
by decoding the bytes using the specified charset.final String
Constructs a newString
by decoding the bytes as UTF-8.private String
static Comparator
<ByteString> Returns aComparator
which comparesByteString
-s lexicographically as sequences of unsigned bytes (i.e.(package private) static ByteString
wrap
(byte[] bytes) Wraps the given bytes into aByteString
.(package private) static ByteString
wrap
(byte[] bytes, int offset, int length) Wraps the given bytes into aByteString
.(package private) static ByteString
wrap
(ByteBuffer buffer) Wraps the given bytes into aByteString
.(package private) abstract void
writeTo
(ByteOutput byteOutput) Writes thisByteString
to the providedByteOutput
.abstract void
writeTo
(OutputStream out) Writes a copy of the contents of this byte string to the specified output stream argument.(package private) final void
writeTo
(OutputStream out, int sourceOffset, int numberToWrite) Writes a specified part of this byte string to an output stream.(package private) abstract void
writeToInternal
(OutputStream out, int sourceOffset, int numberToWrite) Internal version ofwriteTo(OutputStream,int,int)
that assumes all error checking has already been done.(package private) abstract void
writeToReverse
(ByteOutput byteOutput) This method behaves exactly the same aswriteTo(ByteOutput)
unless theByteString
is a rope.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
-
serialVersionUID
private static final long serialVersionUID- See Also:
-
CONCATENATE_BY_COPY_SIZE
static final int CONCATENATE_BY_COPY_SIZEWhen two strings to be concatenated have a combined length shorter than this, we just copy their bytes onconcat(ByteString)
. The trade-off is copy size versus the overhead of creating tree nodes inRopeByteString
.- See Also:
-
MIN_READ_FROM_CHUNK_SIZE
static final int MIN_READ_FROM_CHUNK_SIZEWhen 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.- See Also:
-
MAX_READ_FROM_CHUNK_SIZE
static final int MAX_READ_FROM_CHUNK_SIZE- See Also:
-
EMPTY
EmptyByteString
. -
byteArrayCopier
-
hash
private int hashCached hash value. Intentionally accessed via a data race, which is safe because of the Java Memory Model's "no out-of-thin-air values" guarantees for ints. A value of 0 implies that the hash has not been set. -
UNSIGNED_BYTE_MASK
private static final int UNSIGNED_BYTE_MASK- See Also:
-
UNSIGNED_LEXICOGRAPHICAL_COMPARATOR
Compares twoByteString
s lexicographically, treating their contents as unsigned byte 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
.
-
-
Constructor Details
-
ByteString
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 theByteString.ByteIterator
returned byiterator()
, and callsubstring(int, int)
first if necessary.- Parameters:
index
- index of byte- Returns:
- the value
- Throws:
IndexOutOfBoundsException
-index < 0 or index >= size
-
internalByteAt
abstract byte internalByteAt(int index) Gets the byte at the given index, assumes bounds checking has already been performed.- Parameters:
index
- index of byte- Returns:
- the value
- Throws:
IndexOutOfBoundsException
-index < 0 or index >= size
-
iterator
Return aByteString.ByteIterator
over the bytes in the ByteString. To avoid auto-boxing, you may get the iterator manually and callByteString.ByteIterator.nextByte()
. -
size
public abstract int size()Gets the number of bytes.- Returns:
- size in bytes
-
isEmpty
public final boolean isEmpty()Returnstrue
if the size is0
,false
otherwise.- Returns:
- true if this is zero bytes long
-
empty
Returns an emptyByteString
of size0
. -
toInt
private static int toInt(byte value) Returns the value of the given byte as an integer, interpreting the byte as an unsigned value. That is, returnsvalue + 256
ifvalue
is negative;value
itself otherwise.Note: This code was copied from
invalid reference
com.google.common.primitives.UnsignedBytes#toInt
com.google.protobuf
package. -
hexDigit
private static int hexDigit(char c) Returns the numeric value of the given character in hex, or -1 if invalid. -
extractHexDigit
Returns the numeric value of the given character at index in hexString.- Throws:
NumberFormatException
- if the hexString character is invalid.
-
unsignedLexicographicalComparator
Returns aComparator
which comparesByteString
-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
Return the substring frombeginIndex
, inclusive, to the end of the string.- Parameters:
beginIndex
- start at this index- Returns:
- substring sharing underlying data
- Throws:
IndexOutOfBoundsException
- ifbeginIndex < 0
orbeginIndex > size()
.
-
substring
Return the substring frombeginIndex
, inclusive, toendIndex
, exclusive.- Parameters:
beginIndex
- start at this indexendIndex
- the last character is the one before this index- Returns:
- substring sharing underlying data
- Throws:
IndexOutOfBoundsException
- ifbeginIndex < 0
,endIndex > size()
, orbeginIndex > endIndex
.
-
startsWith
Tests if this bytestring starts with the specified prefix. Similar toString.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
Tests if this bytestring ends with the specified suffix. Similar toString.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.
-
fromHex
Returns aByteString
from a hexadecimal String.- Parameters:
hexString
- String of hexadecimal digits to createByteString
from.- Throws:
NumberFormatException
- if the hexString does not contain a parsable hex String.
-
copyFrom
Copies the given bytes into aByteString
.- Parameters:
bytes
- source arrayoffset
- offset in source arraysize
- number of bytes to copy- Returns:
- new
ByteString
- Throws:
IndexOutOfBoundsException
- ifoffset
orsize
are out of bounds
-
copyFrom
Copies the given bytes into aByteString
.- Parameters:
bytes
- to copy- Returns:
- new
ByteString
-
wrap
Wraps the given bytes into aByteString
. Intended for internal usage within the library. -
nioByteString
-
wrap
Wraps the given bytes into aByteString
. Intended for internal usage within the library to force a classload of ByteString before LiteralByteString. -
wrap
Wraps the given bytes into aByteString
. Intended for internal usage within the library to force a classload of ByteString before BoundedByteString and LiteralByteString. -
copyFrom
Copies the nextsize
bytes from ajava.nio.ByteBuffer
into aByteString
.- Parameters:
bytes
- source buffersize
- number of bytes to copy- Returns:
- new
ByteString
- Throws:
IndexOutOfBoundsException
- ifsize > bytes.remaining()
-
copyFrom
Copies the remaining bytes from ajava.nio.ByteBuffer
into aByteString
.- Parameters:
bytes
- sourceBuffer- Returns:
- new
ByteString
-
copyFrom
public static ByteString copyFrom(String text, String charsetName) throws UnsupportedEncodingException Encodestext
into a sequence of bytes using the named charset and returns the result as aByteString
.- Parameters:
text
- source stringcharsetName
- encoding to use- Returns:
- new
ByteString
- Throws:
UnsupportedEncodingException
- if the encoding isn't found
-
copyFrom
Encodestext
into a sequence of bytes using the named charset and returns the result as aByteString
.- Parameters:
text
- source stringcharset
- encode using this charset- Returns:
- new
ByteString
-
copyFromUtf8
Encodestext
into a sequence of UTF-8 bytes and returns the result as aByteString
.- Parameters:
text
- source string- Returns:
- new
ByteString
-
readFrom
Completely reads the given stream's bytes into aByteString
, 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:
IOException
- if there is a problem reading the underlying streamIllegalArgumentException
- if the stream supplies more than Integer.MAX_VALUE bytes
-
readFrom
Completely reads the given stream's bytes into aByteString
, 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:
IOException
- if there is a problem reading the underlying streamIllegalArgumentException
- if the stream supplies more than Integer.MAX_VALUE bytes
-
readFrom
public static ByteString readFrom(InputStream streamToDrain, int minChunkSize, int maxChunkSize) throws IOException Helper method that takes the chunk size range as a parameter.- Parameters:
streamToDrain
- the source stream, which is read completely but not closedminChunkSize
- the minimum size of the chunks in which to read the streammaxChunkSize
- the maximum size of the chunks in which to read the stream- Returns:
- a new
ByteString
which is made up of chunks within the given size range - Throws:
IOException
- if there is a problem reading the underlying streamIllegalArgumentException
- if the stream supplies more than Integer.MAX_VALUE bytes
-
readChunk
Blocks until a chunk of the given size can be made from the stream, or EOF is reached. Calls read() repeatedly in case the given stream implementation doesn't completely fill the given buffer in one read() call.- Returns:
- A chunk of the desired size, or else a chunk as large as was available when end of stream was reached. Returns null if the given stream had no more data in it.
- Throws:
IOException
-
concat
Concatenate the givenByteString
to this one. Short concatenations, of total size smaller thanCONCATENATE_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 - Throws:
IllegalArgumentException
- if the combined size of the two byte strings exceeds Integer.MAX_VALUE
-
copyFrom
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 emptyByteString
. If the list has only one element, thatByteString
will be returned without copying.- Parameters:
byteStrings
- strings to be concatenated- Returns:
- new
ByteString
- Throws:
IllegalArgumentException
- if the combined size of the byte strings exceeds Integer.MAX_VALUE
-
balancedConcat
-
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 intooffset
- in the target buffer- Throws:
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, callbyteString.substring(sourceOffset, sourceOffset + numberToCopy).copyTo(target, targetOffset)
Copies bytes into a buffer.- Parameters:
target
- buffer to copy intosourceOffset
- offset within these bytestargetOffset
- offset within the target buffernumberToCopy
- 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 ofcopyTo(byte[],int,int,int)
. It assumes that all error checking has already been performed and thatnumberToCopy > 0
. -
copyTo
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:
ReadOnlyBufferException
- if thetarget
is read-onlyBufferOverflowException
- if thetarget
's remaining() space is not large enough to hold the data.
-
toByteArray
public final byte[] toByteArray()Copies bytes to abyte[]
.- Returns:
- copied bytes
-
writeTo
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:
IOException
- if an I/O error occurs.
-
writeTo
Writes a specified part of this byte string to an output stream.- Parameters:
out
- the output stream to which to write the data.sourceOffset
- offset within these bytesnumberToWrite
- number of bytes to write- Throws:
IOException
- if an I/O error occurs.IndexOutOfBoundsException
- if an offset or size is negative or too large
-
writeToInternal
abstract void writeToInternal(OutputStream out, int sourceOffset, int numberToWrite) throws IOException Internal version ofwriteTo(OutputStream,int,int)
that assumes all error checking has already been done.- Throws:
IOException
-
writeTo
Writes thisByteString
to the providedByteOutput
. Calling this method may result in multiple operations on the targetByteOutput
.This method may expose internal backing buffers of the
ByteString
to theByteOutput
in order to avoid additional copying overhead. It would be possible for a maliciousByteOutput
to corrupt theByteString
. Use with caution!- Parameters:
byteOutput
- the output target to receive the bytes- Throws:
IOException
- if an I/O error occurs- See Also:
-
writeToReverse
This method behaves exactly the same aswriteTo(ByteOutput)
unless theByteString
is a rope. For ropes, the leaf nodes are written in reverse order to thebyteOutput
.- Parameters:
byteOutput
- the output target to receive the bytes- Throws:
IOException
- if an I/O error occurs- See Also:
-
asReadOnlyByteBuffer
Constructs a read-onlyjava.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
Constructs a list of read-onlyjava.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
Constructs a newString
by decoding the bytes using the specified charset.- Parameters:
charsetName
- encode using this charset- Returns:
- new string
- Throws:
UnsupportedEncodingException
- if charset isn't recognized
-
toString
Constructs a newString
by decoding the bytes using the specified charset. Returns the same empty String if empty.- Parameters:
charset
- encode using this charset- Returns:
- new string
-
toStringInternal
Constructs a newString
by decoding the bytes using the specified charset.- Parameters:
charset
- encode using this charset- Returns:
- new string
-
toStringUtf8
Constructs a newString
by decoding the bytes as UTF-8.- Returns:
- new string using UTF-8 encoding
-
isValidUtf8
public abstract boolean isValidUtf8()Tells whether thisByteString
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 multipleByteString
segments.- Parameters:
state
- either0
(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- 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
-
hashCode
public final int hashCode()Compute the hashCode using the traditional algorithm fromByteString
. -
newInput
Creates anInputStream
which can be used to read the bytes.The
InputStream
returned by this method is guaranteed to be completely non-blocking. The methodInputStream.available()
returns the number of bytes remaining in the stream. The methodsInputStream.read(byte[])
,InputStream.read(byte[],int,int)
andInputStream.skip(long)
will read/skip as many bytes as are available. The methodInputStream.markSupported()
returnstrue
.The methods in the returned
InputStream
might not be thread safe.- Returns:
- an input stream that returns the bytes of this byte string.
-
newCodedInput
Creates aCodedInputStream
which can be used to read the bytes. Using this is often more efficient than creating aCodedInputStream
that wraps the result ofnewInput()
.- Returns:
- stream based on wrapped data
-
newOutput
Creates a newByteString.Output
with the given initial capacity. CallByteString.Output.toByteString()
to create theByteString
instance.A
ByteString.Output
offers the same functionality as aByteArrayOutputStream
, except that it returns aByteString
rather than abyte
array.- Parameters:
initialCapacity
- estimate of number of bytes to be written- Returns:
OutputStream
for building aByteString
-
newOutput
Creates a newByteString.Output
. CallByteString.Output.toByteString()
to create theByteString
instance.A
ByteString.Output
offers the same functionality as aByteArrayOutputStream
, except that it returns aByteString
rather than abyte array
.- Returns:
OutputStream
for building aByteString
-
newCodedBuilder
Constructs a newByteString
builder, which allows you to efficiently construct aByteString
by writing to aCodedOutputStream
. Using this is much more efficient than callingnewOutput()
and wrapping that in aCodedOutputStream
.This is package-private because it's a somewhat confusing interface. Users can call
MessageLite.toByteString()
instead of calling this directly.- Parameters:
size
- The target byte size of theByteString
. You must write exactly this many bytes before building the result.- Returns:
- the builder
-
getTreeDepth
protected abstract int getTreeDepth()Return the depth of the tree representing thisByteString
, 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()Returntrue
if this ByteString is literal (a leaf node) or a flat-enough tree in the sense ofRopeByteString
.- Returns:
- true if the tree is flat enough
-
peekCachedHashCode
protected final 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 valueoffset
- offset into this value to start looking at data valueslength
- number of data values to include in the hash computation- Returns:
- ending hash value
-
checkIndex
static void checkIndex(int index, int size) Checks that the given index falls within the specified array size.- Parameters:
index
- the index position to be testedsize
- the length of the array- Throws:
IndexOutOfBoundsException
- if the index does not fall within the array.
-
checkRange
static int checkRange(int startIndex, int endIndex, int size) Checks that the given range falls within the bounds of an array- Parameters:
startIndex
- the start index of the range (inclusive)endIndex
- the end index of the range (exclusive)size
- the size of the array.- Returns:
- the length of the range.
- Throws:
IndexOutOfBoundsException
- some or all of the range falls outside of the array.
-
toString
-
truncateAndEscapeForDisplay
-
byteString.substring(sourceOffset, sourceOffset + numberToCopy).copyTo(target, targetOffset)