Interface BufferedSource
- All Superinterfaces:
AutoCloseable
,Channel
,Closeable
,ReadableByteChannel
,Source
- All Known Implementing Classes:
Buffer
-
Method Summary
Modifier and TypeMethodDescriptionbuffer()
Deprecated.use getBuffer() instead.boolean
Returns true if there are no more bytes in this source.This source's internal buffer.long
indexOf
(byte b) Equivalent toindexOf(b, 0)
.long
indexOf
(byte b, long fromIndex) Returns the index of the firstb
in the buffer at or afterfromIndex
.long
indexOf
(byte b, long fromIndex, long toIndex) Returns the index ofb
if it is found in the range offromIndex
inclusive totoIndex
exclusive.long
indexOf
(ByteString bytes) Equivalent toindexOf(bytes, 0)
.long
indexOf
(ByteString bytes, long fromIndex) Returns the index of the first match forbytes
in the buffer at or afterfromIndex
.long
indexOfElement
(ByteString targetBytes) Equivalent toindexOfElement(targetBytes, 0)
.long
indexOfElement
(ByteString targetBytes, long fromIndex) Returns the first index in this buffer that is at or afterfromIndex
and that contains any of the bytes intargetBytes
.Returns an input stream that reads from this source.peek()
Returns a newBufferedSource
that can read data from thisBufferedSource
without consuming it.boolean
rangeEquals
(long offset, ByteString bytes) Returns true if the bytes atoffset
in this source equalbytes
.boolean
rangeEquals
(long offset, ByteString bytes, int bytesOffset, int byteCount) Returns true ifbyteCount
bytes atoffset
in this source equalbytes
atbytesOffset
.int
read
(byte[] sink) Removes up tosink.length
bytes from this and copies them intosink
.int
read
(byte[] sink, int offset, int byteCount) Removes up tobyteCount
bytes from this and copies them intosink
atoffset
.long
Removes all bytes from this and appends them tosink
.byte
readByte()
Removes a byte from this source and returns it.byte[]
Removes all bytes from this and returns them as a byte array.byte[]
readByteArray
(long byteCount) RemovesbyteCount
bytes from this and returns them as a byte array.Removes all bytes bytes from this and returns them as a byte string.readByteString
(long byteCount) RemovesbyteCount
bytes from this and returns them as a byte string.long
Reads a long from this source in signed decimal form (i.e., as a string in base 10 with optional leading '-').void
readFully
(byte[] sink) Removes exactlysink.length
bytes from this and copies them intosink
.void
Removes exactlybyteCount
bytes from this and appends them tosink
.long
Reads a long form this source in hexadecimal form (i.e., as a string in base 16).int
readInt()
Removes four bytes from this source and returns a big-endian int.int
Removes four bytes from this source and returns a little-endian int.long
readLong()
Removes eight bytes from this source and returns a big-endian long.long
Removes eight bytes from this source and returns a little-endian long.short
Removes two bytes from this source and returns a big-endian short.short
Removes two bytes from this source and returns a little-endian short.readString
(long byteCount, Charset charset) RemovesbyteCount
bytes from this, decodes them ascharset
, and returns the string.readString
(Charset charset) Removes all bytes from this, decodes them ascharset
, and returns the string.readUtf8()
Removes all bytes from this, decodes them as UTF-8, and returns the string.readUtf8
(long byteCount) RemovesbyteCount
bytes from this, decodes them as UTF-8, and returns the string.int
Removes and returns a single UTF-8 code point, reading between 1 and 4 bytes as necessary.Removes and returns characters up to but not including the next line break.Removes and returns characters up to but not including the next line break.readUtf8LineStrict
(long limit) LikereadUtf8LineStrict()
, except this allows the caller to specify the longest allowed match.boolean
request
(long byteCount) Returns true when the buffer contains at leastbyteCount
bytes, expanding it as necessary.void
require
(long byteCount) Returns when the buffer contains at leastbyteCount
bytes.int
Finds the first string inoptions
that is a prefix of this buffer, consumes it from this buffer, and returns its index.void
skip
(long byteCount) Reads and discardsbyteCount
bytes from this source.Methods inherited from interface java.nio.channels.ReadableByteChannel
read
-
Method Details
-
buffer
Deprecated.use getBuffer() instead.Returns this source's internal buffer. -
getBuffer
Buffer getBuffer()This source's internal buffer. -
exhausted
Returns true if there are no more bytes in this source. This will block until there are bytes to read or the source is definitely exhausted.- Throws:
IOException
-
require
Returns when the buffer contains at leastbyteCount
bytes. Throws anEOFException
if the source is exhausted before the required bytes can be read.- Throws:
IOException
-
request
Returns true when the buffer contains at leastbyteCount
bytes, expanding it as necessary. Returns false if the source is exhausted before the requested bytes can be read.- Throws:
IOException
-
readByte
Removes a byte from this source and returns it.- Throws:
IOException
-
readShort
Removes two bytes from this source and returns a big-endian short.Buffer buffer = new Buffer() .writeByte(0x7f) .writeByte(0xff) .writeByte(0x00) .writeByte(0x0f); assertEquals(4, buffer.size()); assertEquals(32767, buffer.readShort()); assertEquals(2, buffer.size()); assertEquals(15, buffer.readShort()); assertEquals(0, buffer.size());
- Throws:
IOException
-
readShortLe
Removes two bytes from this source and returns a little-endian short.Buffer buffer = new Buffer() .writeByte(0xff) .writeByte(0x7f) .writeByte(0x0f) .writeByte(0x00); assertEquals(4, buffer.size()); assertEquals(32767, buffer.readShortLe()); assertEquals(2, buffer.size()); assertEquals(15, buffer.readShortLe()); assertEquals(0, buffer.size());
- Throws:
IOException
-
readInt
Removes four bytes from this source and returns a big-endian int.Buffer buffer = new Buffer() .writeByte(0x7f) .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00) .writeByte(0x0f); assertEquals(8, buffer.size()); assertEquals(2147483647, buffer.readInt()); assertEquals(4, buffer.size()); assertEquals(15, buffer.readInt()); assertEquals(0, buffer.size());
- Throws:
IOException
-
readIntLe
Removes four bytes from this source and returns a little-endian int.Buffer buffer = new Buffer() .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0x7f) .writeByte(0x0f) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00); assertEquals(8, buffer.size()); assertEquals(2147483647, buffer.readIntLe()); assertEquals(4, buffer.size()); assertEquals(15, buffer.readIntLe()); assertEquals(0, buffer.size());
- Throws:
IOException
-
readLong
Removes eight bytes from this source and returns a big-endian long.Buffer buffer = new Buffer() .writeByte(0x7f) .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00) .writeByte(0x0f); assertEquals(16, buffer.size()); assertEquals(9223372036854775807L, buffer.readLong()); assertEquals(8, buffer.size()); assertEquals(15, buffer.readLong()); assertEquals(0, buffer.size());
- Throws:
IOException
-
readLongLe
Removes eight bytes from this source and returns a little-endian long.Buffer buffer = new Buffer() .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0xff) .writeByte(0x7f) .writeByte(0x0f) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00) .writeByte(0x00); assertEquals(16, buffer.size()); assertEquals(9223372036854775807L, buffer.readLongLe()); assertEquals(8, buffer.size()); assertEquals(15, buffer.readLongLe()); assertEquals(0, buffer.size());
- Throws:
IOException
-
readDecimalLong
Reads a long from this source in signed decimal form (i.e., as a string in base 10 with optional leading '-'). This will iterate until a non-digit character is found.Buffer buffer = new Buffer() .writeUtf8("8675309 -123 00001"); assertEquals(8675309L, buffer.readDecimalLong()); assertEquals(' ', buffer.readByte()); assertEquals(-123L, buffer.readDecimalLong()); assertEquals(' ', buffer.readByte()); assertEquals(1L, buffer.readDecimalLong());
- Throws:
NumberFormatException
- if the found digits do not fit into along
or a decimal number was not present.IOException
-
readHexadecimalUnsignedLong
Reads a long form this source in hexadecimal form (i.e., as a string in base 16). This will iterate until a non-hexadecimal character is found.Buffer buffer = new Buffer() .writeUtf8("ffff CAFEBABE 10"); assertEquals(65535L, buffer.readHexadecimalUnsignedLong()); assertEquals(' ', buffer.readByte()); assertEquals(0xcafebabeL, buffer.readHexadecimalUnsignedLong()); assertEquals(' ', buffer.readByte()); assertEquals(0x10L, buffer.readHexadecimalUnsignedLong());
- Throws:
NumberFormatException
- if the found hexadecimal does not fit into along
or hexadecimal was not found.IOException
-
skip
Reads and discardsbyteCount
bytes from this source. Throws anEOFException
if the source is exhausted before the requested bytes can be skipped.- Throws:
IOException
-
readByteString
Removes all bytes bytes from this and returns them as a byte string.- Throws:
IOException
-
readByteString
RemovesbyteCount
bytes from this and returns them as a byte string.- Throws:
IOException
-
select
Finds the first string inoptions
that is a prefix of this buffer, consumes it from this buffer, and returns its index. If no byte string inoptions
is a prefix of this buffer this returns -1 and no bytes are consumed.This can be used as an alternative to
readByteString()
or evenreadUtf8()
if the set of expected values is known in advance.Options FIELDS = Options.of( ByteString.encodeUtf8("depth="), ByteString.encodeUtf8("height="), ByteString.encodeUtf8("width=")); Buffer buffer = new Buffer() .writeUtf8("width=640\n") .writeUtf8("height=480\n"); assertEquals(2, buffer.select(FIELDS)); assertEquals(640, buffer.readDecimalLong()); assertEquals('\n', buffer.readByte()); assertEquals(1, buffer.select(FIELDS)); assertEquals(480, buffer.readDecimalLong()); assertEquals('\n', buffer.readByte());
- Throws:
IOException
-
readByteArray
Removes all bytes from this and returns them as a byte array.- Throws:
IOException
-
readByteArray
RemovesbyteCount
bytes from this and returns them as a byte array.- Throws:
IOException
-
read
Removes up tosink.length
bytes from this and copies them intosink
. Returns the number of bytes read, or -1 if this source is exhausted.- Throws:
IOException
-
readFully
Removes exactlysink.length
bytes from this and copies them intosink
. Throws anEOFException
if the requested number of bytes cannot be read.- Throws:
IOException
-
read
Removes up tobyteCount
bytes from this and copies them intosink
atoffset
. Returns the number of bytes read, or -1 if this source is exhausted.- Throws:
IOException
-
readFully
Removes exactlybyteCount
bytes from this and appends them tosink
. Throws anEOFException
if the requested number of bytes cannot be read.- Throws:
IOException
-
readAll
Removes all bytes from this and appends them tosink
. Returns the total number of bytes written tosink
which will be 0 if this is exhausted.- Throws:
IOException
-
readUtf8
Removes all bytes from this, decodes them as UTF-8, and returns the string. Returns the empty string if this source is empty.Buffer buffer = new Buffer() .writeUtf8("Uh uh uh!") .writeByte(' ') .writeUtf8("You didn't say the magic word!"); assertEquals("Uh uh uh! You didn't say the magic word!", buffer.readUtf8()); assertEquals(0, buffer.size()); assertEquals("", buffer.readUtf8()); assertEquals(0, buffer.size());
- Throws:
IOException
-
readUtf8
RemovesbyteCount
bytes from this, decodes them as UTF-8, and returns the string.Buffer buffer = new Buffer() .writeUtf8("Uh uh uh!") .writeByte(' ') .writeUtf8("You didn't say the magic word!"); assertEquals(40, buffer.size()); assertEquals("Uh uh uh! You ", buffer.readUtf8(14)); assertEquals(26, buffer.size()); assertEquals("didn't say the", buffer.readUtf8(14)); assertEquals(12, buffer.size()); assertEquals(" magic word!", buffer.readUtf8(12)); assertEquals(0, buffer.size());
- Throws:
IOException
-
readUtf8Line
Removes and returns characters up to but not including the next line break. A line break is either"\n"
or"\r\n"
; these characters are not included in the result.Buffer buffer = new Buffer() .writeUtf8("I'm a hacker!\n") .writeUtf8("That's what I said: you're a nerd.\n") .writeUtf8("I prefer to be called a hacker!\n"); assertEquals(81, buffer.size()); assertEquals("I'm a hacker!", buffer.readUtf8Line()); assertEquals(67, buffer.size()); assertEquals("That's what I said: you're a nerd.", buffer.readUtf8Line()); assertEquals(32, buffer.size()); assertEquals("I prefer to be called a hacker!", buffer.readUtf8Line()); assertEquals(0, buffer.size()); assertEquals(null, buffer.readUtf8Line()); assertEquals(0, buffer.size());
On the end of the stream this method returns null, just like
BufferedReader
. If the source doesn't end with a line break then an implicit line break is assumed. Null is returned once the source is exhausted. Use this for human-generated data, where a trailing line break is optional.- Throws:
IOException
-
readUtf8LineStrict
Removes and returns characters up to but not including the next line break. A line break is either"\n"
or"\r\n"
; these characters are not included in the result.On the end of the stream this method throws. Every call must consume either '\r\n' or '\n'. If these characters are absent in the stream, an
EOFException
is thrown. Use this for machine-generated data where a missing line break implies truncated input.- Throws:
IOException
-
readUtf8LineStrict
LikereadUtf8LineStrict()
, except this allows the caller to specify the longest allowed match. Use this to protect against streams that may not include"\n"
or"\r\n"
.The returned string will have at most
limit
UTF-8 bytes, and the maximum number of bytes scanned islimit + 2
. Iflimit == 0
this will always throw anEOFException
because no bytes will be scanned.This method is safe. No bytes are discarded if the match fails, and the caller is free to try another match:
Buffer buffer = new Buffer(); buffer.writeUtf8("12345\r\n"); // This will throw! There must be \r\n or \n at the limit or before it. buffer.readUtf8LineStrict(4); // No bytes have been consumed so the caller can retry. assertEquals("12345", buffer.readUtf8LineStrict(5));
- Throws:
IOException
-
readUtf8CodePoint
Removes and returns a single UTF-8 code point, reading between 1 and 4 bytes as necessary.If this source is exhausted before a complete code point can be read, this throws an
EOFException
and consumes no input.If this source doesn't start with a properly-encoded UTF-8 code point, this method will remove 1 or more non-UTF-8 bytes and return the replacement character (
U+FFFD
). This covers encoding problems (the input is not properly-encoded UTF-8), characters out of range (beyond the 0x10ffff limit of Unicode), code points for UTF-16 surrogates (U+d800..U+dfff) and overlong encodings (such as0xc080
for the NUL character in modified UTF-8).- Throws:
IOException
-
readString
Removes all bytes from this, decodes them ascharset
, and returns the string.- Throws:
IOException
-
readString
RemovesbyteCount
bytes from this, decodes them ascharset
, and returns the string.- Throws:
IOException
-
indexOf
Equivalent toindexOf(b, 0)
.- Throws:
IOException
-
indexOf
Returns the index of the firstb
in the buffer at or afterfromIndex
. This expands the buffer as necessary untilb
is found. This reads an unbounded number of bytes into the buffer. Returns -1 if the stream is exhausted before the requested byte is found.Buffer buffer = new Buffer(); buffer.writeUtf8("Don't move! He can't see us if we don't move."); byte m = 'm'; assertEquals(6, buffer.indexOf(m)); assertEquals(40, buffer.indexOf(m, 12));
- Throws:
IOException
-
indexOf
Returns the index ofb
if it is found in the range offromIndex
inclusive totoIndex
exclusive. Ifb
isn't found, or iffromIndex == toIndex
, then -1 is returned.The scan terminates at either
toIndex
or the end of the buffer, whichever comes first. The maximum number of bytes scanned istoIndex-fromIndex
.- Throws:
IOException
-
indexOf
Equivalent toindexOf(bytes, 0)
.- Throws:
IOException
-
indexOf
Returns the index of the first match forbytes
in the buffer at or afterfromIndex
. This expands the buffer as necessary untilbytes
is found. This reads an unbounded number of bytes into the buffer. Returns -1 if the stream is exhausted before the requested bytes are found.ByteString MOVE = ByteString.encodeUtf8("move"); Buffer buffer = new Buffer(); buffer.writeUtf8("Don't move! He can't see us if we don't move."); assertEquals(6, buffer.indexOf(MOVE)); assertEquals(40, buffer.indexOf(MOVE, 12));
- Throws:
IOException
-
indexOfElement
Equivalent toindexOfElement(targetBytes, 0)
.- Throws:
IOException
-
indexOfElement
Returns the first index in this buffer that is at or afterfromIndex
and that contains any of the bytes intargetBytes
. This expands the buffer as necessary until a target byte is found. This reads an unbounded number of bytes into the buffer. Returns -1 if the stream is exhausted before the requested byte is found.ByteString ANY_VOWEL = ByteString.encodeUtf8("AEOIUaeoiu"); Buffer buffer = new Buffer(); buffer.writeUtf8("Dr. Alan Grant"); assertEquals(4, buffer.indexOfElement(ANY_VOWEL)); // 'A' in 'Alan'. assertEquals(11, buffer.indexOfElement(ANY_VOWEL, 9)); // 'a' in 'Grant'.
- Throws:
IOException
-
rangeEquals
Returns true if the bytes atoffset
in this source equalbytes
. This expands the buffer as necessary until a byte does not match, all bytes are matched, or if the stream is exhausted before enough bytes could determine a match.ByteString simonSays = ByteString.encodeUtf8("Simon says:"); Buffer standOnOneLeg = new Buffer().writeUtf8("Simon says: Stand on one leg."); assertTrue(standOnOneLeg.rangeEquals(0, simonSays)); Buffer payMeMoney = new Buffer().writeUtf8("Pay me $1,000,000."); assertFalse(payMeMoney.rangeEquals(0, simonSays));
- Throws:
IOException
-
rangeEquals
boolean rangeEquals(long offset, ByteString bytes, int bytesOffset, int byteCount) throws IOException Returns true ifbyteCount
bytes atoffset
in this source equalbytes
atbytesOffset
. This expands the buffer as necessary until a byte does not match, all bytes are matched, or if the stream is exhausted before enough bytes could determine a match.- Throws:
IOException
-
peek
BufferedSource peek()Returns a newBufferedSource
that can read data from thisBufferedSource
without consuming it. The returned source becomes invalid once this source is next read or closed. For example, we can usepeek()
to lookahead and read the same data multiple times.Buffer buffer = new Buffer(); buffer.writeUtf8("abcdefghi"); buffer.readUtf8(3) // returns "abc", buffer contains "defghi" BufferedSource peek = buffer.peek(); peek.readUtf8(3); // returns "def", buffer contains "defghi" peek.readUtf8(3); // returns "ghi", buffer contains "defghi" buffer.readUtf8(3); // returns "def", buffer contains "ghi"
-
inputStream
InputStream inputStream()Returns an input stream that reads from this source.
-