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 classprivate static final classImplementation ofByteArrayCopierwhich usesArrays.copyOfRange(T[], int, int).private static final classThis class is used to represent the substring of aByteStringover a single byte array.private static interfaceAn interface to efficiently copybyte[].static interfaceThis interface extendsIterator<Byte>, so that we can return an unboxedbyte.(package private) static final classSeenewCodedBuilder(int).(package private) static classBase class for leafByteStrings (i.e.private static classThis class implements aByteStringbacked by a single array of bytes, contiguous in memory.static final classOutputs to aByteStringinstance.private static final classImplementation ofByteArrayCopierwhich usesSystem.arraycopy(java.lang.Object, int, java.lang.Object, int, int). -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final ByteString.ByteArrayCopier(package private) static final intWhen two strings to be concatenated have a combined length shorter than this, we just copy their bytes onconcat(ByteString).static final ByteStringEmptyByteString.private intCached hash value.(package private) static final int(package private) static final intWhen 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 longprivate static final intprivate static final Comparator<ByteString>Compares twoByteStrings lexicographically, treating their contents as unsigned byte values between 0 and 255 (inclusive). -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract ByteBufferConstructs a read-onlyjava.nio.ByteBufferwhose content is equal to the contents of this byte string.abstract List<ByteBuffer>Constructs a list of read-onlyjava.nio.ByteBufferobjects such that the concatenation of their contents is equal to the contents of this byte string.private static ByteStringbalancedConcat(Iterator<ByteString> iterator, int length) abstract bytebyteAt(int index) Gets the byte at the given index.(package private) static voidcheckIndex(int index, int size) Checks that the given index falls within the specified array size.(package private) static intcheckRange(int startIndex, int endIndex, int size) Checks that the given range falls within the bounds of an arrayfinal ByteStringconcat(ByteString other) Concatenate the givenByteStringto this one.static ByteStringcopyFrom(byte[] bytes) Copies the given bytes into aByteString.static ByteStringcopyFrom(byte[] bytes, int offset, int size) Copies the given bytes into aByteString.static ByteStringcopyFrom(Iterable<ByteString> byteStrings) Concatenates all byte strings in the iterable and returns the result.static ByteStringEncodestextinto a sequence of bytes using the named charset and returns the result as aByteString.static ByteStringEncodestextinto a sequence of bytes using the named charset and returns the result as aByteString.static ByteStringcopyFrom(ByteBuffer bytes) Copies the remaining bytes from ajava.nio.ByteBufferinto aByteString.static ByteStringcopyFrom(ByteBuffer bytes, int size) Copies the nextsizebytes from ajava.nio.ByteBufferinto aByteString.static ByteStringcopyFromUtf8(String text) Encodestextinto a sequence of UTF-8 bytes and returns the result as aByteString.voidcopyTo(byte[] target, int offset) Copies bytes into a buffer at the given offset.final voidcopyTo(byte[] target, int sourceOffset, int targetOffset, int numberToCopy) Deprecated.abstract voidcopyTo(ByteBuffer target) Copies bytes into a ByteBuffer.protected abstract voidcopyToInternal(byte[] target, int sourceOffset, int targetOffset, int numberToCopy) Internal (package private) implementation ofcopyTo(byte[],int,int,int).static final ByteStringempty()Returns an emptyByteStringof size0.final booleanendsWith(ByteString suffix) Tests if this bytestring ends with the specified suffix.abstract booleanprivate static intextractHexDigit(String hexString, int index) Returns the numeric value of the given character at index in hexString.static ByteStringReturns aByteStringfrom a hexadecimal String.protected abstract intReturn the depth of the tree representing thisByteString, if any, whose root is this node.final inthashCode()Compute the hashCode using the traditional algorithm fromByteString.private static inthexDigit(char c) Returns the numeric value of the given character in hex, or -1 if invalid.(package private) abstract byteinternalByteAt(int index) Gets the byte at the given index, assumes bounds checking has already been performed.protected abstract booleanReturntrueif this ByteString is literal (a leaf node) or a flat-enough tree in the sense ofRopeByteString.final booleanisEmpty()Returnstrueif the size is0,falseotherwise.abstract booleanTells whether thisByteStringrepresents 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.ByteIteratorover the bytes in the ByteString.(package private) static ByteString.CodedBuildernewCodedBuilder(int size) Constructs a newByteStringbuilder, which allows you to efficiently construct aByteStringby writing to aCodedOutputStream.abstract CodedInputStreamCreates aCodedInputStreamwhich can be used to read the bytes.abstract InputStreamnewInput()Creates anInputStreamwhich can be used to read the bytes.static ByteString.OutputCreates a newByteString.Output.static ByteString.OutputnewOutput(int initialCapacity) Creates a newByteString.Outputwith the given initial capacity.protected abstract intpartialHash(int h, int offset, int length) Compute the hash across the value bytes starting with the given hash, and return the result.protected abstract intpartialIsValidUtf8(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 intReturn the cached hash code if available.private static ByteStringreadChunk(InputStream in, int chunkSize) Blocks until a chunk of the given size can be made from the stream, or EOF is reached.static ByteStringreadFrom(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 ByteStringreadFrom(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 ByteStringreadFrom(InputStream streamToDrain, int minChunkSize, int maxChunkSize) Helper method that takes the chunk size range as a parameter.abstract intsize()Gets the number of bytes.final booleanstartsWith(ByteString prefix) Tests if this bytestring starts with the specified prefix.final ByteStringsubstring(int beginIndex) Return the substring frombeginIndex, inclusive, to the end of the string.abstract ByteStringsubstring(int beginIndex, int endIndex) Return the substring frombeginIndex, inclusive, toendIndex, exclusive.final byte[]Copies bytes to abyte[].private static inttoInt(byte value) Returns the value of the given byte as an integer, interpreting the byte as an unsigned value.final StringtoString()final StringConstructs a newStringby decoding the bytes using the specified charset.final StringConstructs a newStringby decoding the bytes using the specified charset.protected abstract StringtoStringInternal(Charset charset) Constructs a newStringby decoding the bytes using the specified charset.final StringConstructs a newStringby decoding the bytes as UTF-8.private Stringstatic Comparator<ByteString>Returns aComparatorwhich comparesByteString-s lexicographically as sequences of unsigned bytes (i.e.(package private) static ByteStringwrap(byte[] bytes) Wraps the given bytes into aByteString.(package private) static ByteStringwrap(byte[] bytes, int offset, int length) Wraps the given bytes into aByteString.(package private) static ByteStringwrap(ByteBuffer buffer) Wraps the given bytes into aByteString.(package private) abstract voidwriteTo(ByteOutput byteOutput) Writes thisByteStringto the providedByteOutput.abstract voidwriteTo(OutputStream out) Writes a copy of the contents of this byte string to the specified output stream argument.(package private) final voidwriteTo(OutputStream out, int sourceOffset, int numberToWrite) Writes a specified part of this byte string to an output stream.(package private) abstract voidwriteToInternal(OutputStream out, int sourceOffset, int numberToWrite) Internal version ofwriteTo(OutputStream,int,int)that assumes all error checking has already been done.(package private) abstract voidwriteToReverse(ByteOutput byteOutput) This method behaves exactly the same aswriteTo(ByteOutput)unless theByteStringis a rope.Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, waitMethods 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 twoByteStrings lexicographically, treating their contents as unsigned byte values between 0 and 255 (inclusive).For example,
(byte) -1is considered to be greater than(byte) 1because 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.ByteIteratorreturned 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.ByteIteratorover 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()Returnstrueif the size is0,falseotherwise.- Returns:
- true if this is zero bytes long
-
empty
Returns an emptyByteStringof 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 + 256ifvalueis negative;valueitself otherwise.Note: This code was copied from
UnsignedBytes.toInt(byte), as Guava libraries cannot be used in thecom.google.protobufpackage. -
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 aComparatorwhich comparesByteString-s lexicographically as sequences of unsigned bytes (i.e. values between 0 and 255, inclusive).For example,
(byte) -1is considered to be greater than(byte) 1because 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 < 0orbeginIndex > 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:
trueif the byte sequence represented by the argument is a prefix of the byte sequence represented by this string;falseotherwise.
-
endsWith
Tests if this bytestring ends with the specified suffix. Similar toString.endsWith(String)- Parameters:
suffix- the suffix.- Returns:
trueif the byte sequence represented by the argument is a suffix of the byte sequence represented by this string;falseotherwise.
-
fromHex
Returns aByteStringfrom a hexadecimal String.- Parameters:
hexString- String of hexadecimal digits to createByteStringfrom.- 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- ifoffsetorsizeare 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. -
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 nextsizebytes from ajava.nio.ByteBufferinto 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.ByteBufferinto aByteString.- Parameters:
bytes- sourceBuffer- Returns:
- new
ByteString
-
copyFrom
public static ByteString copyFrom(String text, String charsetName) throws UnsupportedEncodingException Encodestextinto 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
Encodestextinto 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
Encodestextinto 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
ByteStringis 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
ByteStringwhich 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
ByteStringis 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
ByteStringwhich 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
ByteStringwhich 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 givenByteStringto 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
ByteStringinstance - 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
ByteStringis not necessarily a unique object. If the list is empty, the returned object is the singleton emptyByteString. If the list has only one element, thatByteStringwill 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 thetargetis 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 thisByteStringto the providedByteOutput. Calling this method may result in multiple operations on the targetByteOutput.This method may expose internal backing buffers of the
ByteStringto theByteOutputin order to avoid additional copying overhead. It would be possible for a maliciousByteOutputto 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 theByteStringis 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:
-
UnsafeByteOperations#unsafeWriteToReverse(ByteString, ByteOutput)
-
asReadOnlyByteBuffer
Constructs a read-onlyjava.nio.ByteBufferwhose 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.ByteBufferobjects 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 newStringby 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 newStringby 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 newStringby decoding the bytes using the specified charset.- Parameters:
charset- encode using this charset- Returns:
- new string
-
toStringUtf8
Constructs a newStringby decoding the bytes as UTF-8.- Returns:
- new string using UTF-8 encoding
-
isValidUtf8
public abstract boolean isValidUtf8()Tells whether thisByteStringrepresents 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
truewhenever:Arrays.equals(byteString.toByteArray(), new String(byteString.toByteArray(), "UTF-8").getBytes("UTF-8"))This method returns
falsefor "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
ByteStringare 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 multipleByteStringsegments.- 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:
-1if the partial byte sequence is definitely malformed,0if 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 anInputStreamwhich can be used to read the bytes.The
InputStreamreturned 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
InputStreammight not be thread safe.- Returns:
- an input stream that returns the bytes of this byte string.
-
newCodedInput
Creates aCodedInputStreamwhich can be used to read the bytes. Using this is often more efficient than creating aCodedInputStreamthat wraps the result ofnewInput().- Returns:
- stream based on wrapped data
-
newOutput
Creates a newByteString.Outputwith the given initial capacity. CallByteString.Output.toByteString()to create theByteStringinstance.A
ByteString.Outputoffers the same functionality as aByteArrayOutputStream, except that it returns aByteStringrather than abytearray.- Parameters:
initialCapacity- estimate of number of bytes to be written- Returns:
OutputStreamfor building aByteString
-
newOutput
Creates a newByteString.Output. CallByteString.Output.toByteString()to create theByteStringinstance.A
ByteString.Outputoffers the same functionality as aByteArrayOutputStream, except that it returns aByteStringrather than abyte array.- Returns:
OutputStreamfor building aByteString
-
newCodedBuilder
Constructs a newByteStringbuilder, which allows you to efficiently construct aByteStringby 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()Returntrueif 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)