Class ByteString
- java.lang.Object
-
- com.google.protobuf.ByteString
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Iterable<java.lang.Byte>
- Direct Known Subclasses:
ByteString.LeafByteString
,RopeByteString
@CheckReturnValue public abstract class ByteString extends java.lang.Object implements java.lang.Iterable<java.lang.Byte>, java.io.Serializable
Immutable sequence of bytes. Provides conversions to and frombyte[]
,String
,ByteBuffer
,InputStream
,OutputStream
. Also provides a conversion toCodedInputStream
.Like
String
, the contents of aByteString
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:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
ByteString.AbstractByteIterator
private static class
ByteString.ArraysByteArrayCopier
Implementation ofByteArrayCopier
which usesArrays.copyOfRange(T[], int, int)
.private static class
ByteString.BoundedByteString
This class is used to represent the substring of aByteString
over a single byte array.private static interface
ByteString.ByteArrayCopier
An interface to efficiently copybyte[]
.static interface
ByteString.ByteIterator
This interface extendsIterator<Byte>
, so that we can return an unboxedbyte
.(package private) static class
ByteString.CodedBuilder
SeenewCodedBuilder(int)
.(package private) static class
ByteString.LeafByteString
Base class for leafByteString
s (i.e.private static class
ByteString.LiteralByteString
This class implements aByteString
backed by a single array of bytes, contiguous in memory.static class
ByteString.Output
Outputs to aByteString
instance.private static class
ByteString.SystemByteArrayCopier
Implementation ofByteArrayCopier
which usesSystem.arraycopy(java.lang.Object, int, java.lang.Object, int, int)
.
-
Field Summary
Fields Modifier and Type Field 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 onconcat(ByteString)
.static ByteString
EMPTY
EmptyByteString
.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.private static int
UNSIGNED_BYTE_MASK
private static java.util.Comparator<ByteString>
UNSIGNED_LEXICOGRAPHICAL_COMPARATOR
Compares twoByteString
s lexicographically, treating their contents as unsigned byte values between 0 and 255 (inclusive).
-
Constructor Summary
Constructors Constructor Description ByteString()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description abstract java.nio.ByteBuffer
asReadOnlyByteBuffer()
Constructs a read-onlyjava.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-onlyjava.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 arrayByteString
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(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)
Encodestext
into a sequence of bytes using the named charset and returns the result as aByteString
.static ByteString
copyFrom(java.lang.String text, java.nio.charset.Charset charset)
Encodestext
into a sequence of bytes using the named charset and returns the result as aByteString
.static ByteString
copyFrom(java.nio.ByteBuffer bytes)
Copies the remaining bytes from ajava.nio.ByteBuffer
into aByteString
.static ByteString
copyFrom(java.nio.ByteBuffer bytes, int size)
Copies the nextsize
bytes from ajava.nio.ByteBuffer
into aByteString
.static ByteString
copyFromUtf8(java.lang.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.void
copyTo(byte[] target, int sourceOffset, int targetOffset, int numberToCopy)
Deprecated.Instead, callbyteString.substring(sourceOffset, sourceOffset + numberToCopy).copyTo(target, targetOffset)
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 ofcopyTo(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 thisByteString
, if any, whose root is this node.int
hashCode()
Compute the hashCode using the traditional algorithm fromByteString
.(package private) abstract byte
internalByteAt(int index)
Gets the byte at the given index, assumes bounds checking has already been performed.protected abstract boolean
isBalanced()
Returntrue
if this ByteString is literal (a leaf node) or a flat-enough tree in the sense ofRopeByteString
.boolean
isEmpty()
Returnstrue
if the size is0
,false
otherwise.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.ByteString.ByteIterator
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
newCodedInput()
Creates aCodedInputStream
which can be used to read the bytes.abstract java.io.InputStream
newInput()
Creates anInputStream
which can be used to read the bytes.static ByteString.Output
newOutput()
Creates a newByteString.Output
.static ByteString.Output
newOutput(int initialCapacity)
Creates a newByteString.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 aByteString
, 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 aByteString
, 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)
Helper method that takes the chunk size range as a parameter.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 frombeginIndex
, inclusive, to the end of the string.abstract ByteString
substring(int beginIndex, int endIndex)
Return the substring frombeginIndex
, inclusive, toendIndex
, exclusive.byte[]
toByteArray()
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.java.lang.String
toString()
java.lang.String
toString(java.lang.String charsetName)
Constructs a newString
by decoding the bytes using the specified charset.java.lang.String
toString(java.nio.charset.Charset charset)
Constructs a newString
by decoding the bytes using the specified charset.protected abstract java.lang.String
toStringInternal(java.nio.charset.Charset charset)
Constructs a newString
by decoding the bytes using the specified charset.java.lang.String
toStringUtf8()
Constructs a newString
by decoding the bytes as UTF-8.private java.lang.String
truncateAndEscapeForDisplay()
static java.util.Comparator<ByteString>
unsignedLexicographicalComparator()
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(java.nio.ByteBuffer buffer)
Wraps the given bytes into aByteString
.(package private) abstract void
writeTo(ByteOutput byteOutput)
Writes thisByteString
to the providedByteOutput
.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 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.
-
-
-
Field Detail
-
CONCATENATE_BY_COPY_SIZE
static final int CONCATENATE_BY_COPY_SIZE
When 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:
- Constant Field Values
-
MIN_READ_FROM_CHUNK_SIZE
static final 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.- See Also:
- Constant Field Values
-
MAX_READ_FROM_CHUNK_SIZE
static final int MAX_READ_FROM_CHUNK_SIZE
- See Also:
- Constant Field Values
-
EMPTY
public static final ByteString EMPTY
EmptyByteString
.
-
byteArrayCopier
private static final ByteString.ByteArrayCopier byteArrayCopier
-
hash
private int hash
Cached 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:
- Constant Field Values
-
UNSIGNED_LEXICOGRAPHICAL_COMPARATOR
private static final java.util.Comparator<ByteString> 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
.
-
-
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 theByteString.ByteIterator
returned byiterator()
, and callsubstring(int, int)
first if necessary.- Parameters:
index
- index of byte- Returns:
- the value
- Throws:
java.lang.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:
java.lang.IndexOutOfBoundsException
-index < 0 or index >= size
-
iterator
public ByteString.ByteIterator iterator()
Return aByteString.ByteIterator
over the bytes in the ByteString. To avoid auto-boxing, you may get the iterator manually and callByteString.ByteIterator.nextByte()
.- Specified by:
iterator
in interfacejava.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()
Returnstrue
if the size is0
,false
otherwise.- Returns:
- true if this is zero bytes long
-
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
UnsignedBytes.toInt(byte)
, as Guava libraries cannot be used in thecom.google.protobuf
package.
-
unsignedLexicographicalComparator
public static java.util.Comparator<ByteString> 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
public final ByteString substring(int beginIndex)
Return the substring frombeginIndex
, inclusive, to the end of the string.- Parameters:
beginIndex
- start at this index- Returns:
- substring sharing underlying data
- Throws:
java.lang.IndexOutOfBoundsException
- ifbeginIndex < 0
orbeginIndex > size()
.
-
substring
public abstract ByteString substring(int beginIndex, int endIndex)
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:
java.lang.IndexOutOfBoundsException
- ifbeginIndex < 0
,endIndex > size()
, orbeginIndex > endIndex
.
-
startsWith
public final boolean startsWith(ByteString prefix)
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
public final boolean endsWith(ByteString suffix)
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.
-
copyFrom
public static ByteString copyFrom(byte[] bytes, int offset, int size)
Copies the given bytes into aByteString
.- Parameters:
bytes
- source arrayoffset
- offset in source arraysize
- number of bytes to copy- Returns:
- new
ByteString
- Throws:
java.lang.IndexOutOfBoundsException
- ifoffset
orsize
are out of bounds
-
copyFrom
public static ByteString copyFrom(byte[] bytes)
Copies the given bytes into aByteString
.- Parameters:
bytes
- to copy- Returns:
- new
ByteString
-
wrap
static ByteString wrap(java.nio.ByteBuffer buffer)
Wraps the given bytes into aByteString
. Intended for internal only usage.
-
wrap
static ByteString wrap(byte[] bytes)
Wraps the given bytes into aByteString
. Intended for internal only usage to force a classload of ByteString before LiteralByteString.
-
wrap
static ByteString wrap(byte[] bytes, int offset, int length)
Wraps the given bytes into aByteString
. Intended for internal only usage to force a classload of ByteString before BoundedByteString and LiteralByteString.
-
copyFrom
public static ByteString copyFrom(java.nio.ByteBuffer bytes, int size)
Copies the nextsize
bytes from ajava.nio.ByteBuffer
into aByteString
.- Parameters:
bytes
- source buffersize
- number of bytes to copy- Returns:
- new
ByteString
- Throws:
java.lang.IndexOutOfBoundsException
- ifsize > bytes.remaining()
-
copyFrom
public static ByteString copyFrom(java.nio.ByteBuffer bytes)
Copies the remaining bytes from ajava.nio.ByteBuffer
into aByteString
.- Parameters:
bytes
- sourceBuffer- Returns:
- new
ByteString
-
copyFrom
public static ByteString copyFrom(java.lang.String text, java.lang.String charsetName) throws java.io.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:
java.io.UnsupportedEncodingException
- if the encoding isn't found
-
copyFrom
public static ByteString copyFrom(java.lang.String text, java.nio.charset.Charset charset)
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
public static ByteString copyFromUtf8(java.lang.String text)
Encodestext
into a sequence of UTF-8 bytes and returns the result as aByteString
.- 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 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:
java.io.IOException
- if there is a problem reading the underlying streamjava.lang.IllegalArgumentException
- if the stream supplies more than Integer.MAX_VALUE bytes
-
readFrom
public static ByteString readFrom(java.io.InputStream streamToDrain, int chunkSize) throws java.io.IOException
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:
java.io.IOException
- if there is a problem reading the underlying streamjava.lang.IllegalArgumentException
- if the stream supplies more than Integer.MAX_VALUE bytes
-
readFrom
public static ByteString readFrom(java.io.InputStream streamToDrain, int minChunkSize, int maxChunkSize) throws java.io.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:
java.io.IOException
- if there is a problem reading the underlying streamjava.lang.IllegalArgumentException
- if the stream supplies more than Integer.MAX_VALUE bytes
-
readChunk
private static ByteString readChunk(java.io.InputStream in, int chunkSize) throws java.io.IOException
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:
java.io.IOException
-
concat
public final ByteString concat(ByteString other)
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:
java.lang.IllegalArgumentException
- if the combined size of the two byte strings exceeds Integer.MAX_VALUE
-
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 emptyByteString
. If the list has only one element, thatByteString
will be returned without copying.- Parameters:
byteStrings
- strings to be concatenated- Returns:
- new
ByteString
- Throws:
java.lang.IllegalArgumentException
- if the combined size of the byte strings exceeds Integer.MAX_VALUE
-
balancedConcat
private static ByteString balancedConcat(java.util.Iterator<ByteString> iterator, int length)
-
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:
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, 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:
java.lang.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
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 thetarget
is read-onlyjava.nio.BufferOverflowException
- 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
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.
-
writeTo
final void writeTo(java.io.OutputStream out, int sourceOffset, int numberToWrite) throws java.io.IOException
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:
java.io.IOException
- if an I/O error occurs.java.lang.IndexOutOfBoundsException
- if an offset or size is negative or too large
-
writeToInternal
abstract void writeToInternal(java.io.OutputStream out, int sourceOffset, int numberToWrite) throws java.io.IOException
Internal version ofwriteTo(OutputStream,int,int)
that assumes all error checking has already been done.- Throws:
java.io.IOException
-
writeTo
abstract void writeTo(ByteOutput byteOutput) throws java.io.IOException
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:
java.io.IOException
- if an I/O error occurs- See Also:
UnsafeByteOperations.unsafeWriteTo(ByteString, ByteOutput)
-
writeToReverse
abstract void writeToReverse(ByteOutput byteOutput) throws java.io.IOException
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:
java.io.IOException
- if an I/O error occurs- See Also:
UnsafeByteOperations#unsafeWriteToReverse(ByteString, ByteOutput)
-
asReadOnlyByteBuffer
public abstract java.nio.ByteBuffer 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
public abstract java.util.List<java.nio.ByteBuffer> 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
public final java.lang.String toString(java.lang.String charsetName) throws java.io.UnsupportedEncodingException
Constructs a newString
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 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
protected abstract java.lang.String toStringInternal(java.nio.charset.Charset charset)
Constructs a newString
by decoding the bytes using the specified charset.- Parameters:
charset
- encode using this charset- Returns:
- new string
-
toStringUtf8
public final java.lang.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
public abstract boolean equals(java.lang.Object o)
- Overrides:
equals
in classjava.lang.Object
-
hashCode
public final int hashCode()
Compute the hashCode using the traditional algorithm fromByteString
.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- hashCode value
-
newInput
public abstract java.io.InputStream 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
public abstract CodedInputStream 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
public static ByteString.Output newOutput(int initialCapacity)
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
public static ByteString.Output 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
static ByteString.CodedBuilder newCodedBuilder(int size)
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:
java.lang.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:
java.lang.IndexOutOfBoundsException
- some or all of the range falls outside of the array.
-
toString
public final java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
truncateAndEscapeForDisplay
private java.lang.String truncateAndEscapeForDisplay()
-
-