Interface BufferedSource
-
- All Superinterfaces:
java.lang.AutoCloseable
,java.nio.channels.Channel
,java.io.Closeable
,java.nio.channels.ReadableByteChannel
,Source
- All Known Implementing Classes:
Buffer
public interface BufferedSource extends Source, java.nio.channels.ReadableByteChannel
A source that keeps a buffer internally so that callers can do small reads without a performance penalty. It also allows clients to read ahead, buffering as much as necessary before consuming input.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description Buffer
buffer()
Deprecated.use getBuffer() instead.boolean
exhausted()
Returns true if there are no more bytes in this source.Buffer
getBuffer()
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
.java.io.InputStream
inputStream()
Returns an input stream that reads from this source.BufferedSource
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
readAll(Sink sink)
Removes all bytes from this and appends them tosink
.byte
readByte()
Removes a byte from this source and returns it.byte[]
readByteArray()
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.ByteString
readByteString()
Removes all bytes bytes from this and returns them as a byte string.ByteString
readByteString(long byteCount)
RemovesbyteCount
bytes from this and returns them as a byte string.long
readDecimalLong()
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
readFully(Buffer sink, long byteCount)
Removes exactlybyteCount
bytes from this and appends them tosink
.long
readHexadecimalUnsignedLong()
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
readIntLe()
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
readLongLe()
Removes eight bytes from this source and returns a little-endian long.short
readShort()
Removes two bytes from this source and returns a big-endian short.short
readShortLe()
Removes two bytes from this source and returns a little-endian short.java.lang.String
readString(long byteCount, java.nio.charset.Charset charset)
RemovesbyteCount
bytes from this, decodes them ascharset
, and returns the string.java.lang.String
readString(java.nio.charset.Charset charset)
Removes all bytes from this, decodes them ascharset
, and returns the string.java.lang.String
readUtf8()
Removes all bytes from this, decodes them as UTF-8, and returns the string.java.lang.String
readUtf8(long byteCount)
RemovesbyteCount
bytes from this, decodes them as UTF-8, and returns the string.int
readUtf8CodePoint()
Removes and returns a single UTF-8 code point, reading between 1 and 4 bytes as necessary.java.lang.String
readUtf8Line()
Removes and returns characters up to but not including the next line break.java.lang.String
readUtf8LineStrict()
Removes and returns characters up to but not including the next line break.java.lang.String
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
select(Options options)
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.
-
-
-
Method Detail
-
buffer
@Deprecated Buffer buffer()
Deprecated.use getBuffer() instead.Returns this source's internal buffer.
-
getBuffer
Buffer getBuffer()
This source's internal buffer.
-
exhausted
boolean exhausted() throws java.io.IOException
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:
java.io.IOException
-
require
void require(long byteCount) throws java.io.IOException
Returns when the buffer contains at leastbyteCount
bytes. Throws anEOFException
if the source is exhausted before the required bytes can be read.- Throws:
java.io.IOException
-
request
boolean request(long byteCount) throws java.io.IOException
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:
java.io.IOException
-
readByte
byte readByte() throws java.io.IOException
Removes a byte from this source and returns it.- Throws:
java.io.IOException
-
readShort
short readShort() throws java.io.IOException
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:
java.io.IOException
-
readShortLe
short readShortLe() throws java.io.IOException
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:
java.io.IOException
-
readInt
int readInt() throws java.io.IOException
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:
java.io.IOException
-
readIntLe
int readIntLe() throws java.io.IOException
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:
java.io.IOException
-
readLong
long readLong() throws java.io.IOException
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:
java.io.IOException
-
readLongLe
long readLongLe() throws java.io.IOException
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:
java.io.IOException
-
readDecimalLong
long readDecimalLong() throws java.io.IOException
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:
java.lang.NumberFormatException
- if the found digits do not fit into along
or a decimal number was not present.java.io.IOException
-
readHexadecimalUnsignedLong
long readHexadecimalUnsignedLong() throws java.io.IOException
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:
java.lang.NumberFormatException
- if the found hexadecimal does not fit into along
or hexadecimal was not found.java.io.IOException
-
skip
void skip(long byteCount) throws java.io.IOException
Reads and discardsbyteCount
bytes from this source. Throws anEOFException
if the source is exhausted before the requested bytes can be skipped.- Throws:
java.io.IOException
-
readByteString
ByteString readByteString() throws java.io.IOException
Removes all bytes bytes from this and returns them as a byte string.- Throws:
java.io.IOException
-
readByteString
ByteString readByteString(long byteCount) throws java.io.IOException
RemovesbyteCount
bytes from this and returns them as a byte string.- Throws:
java.io.IOException
-
select
int select(Options options) throws java.io.IOException
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:
java.io.IOException
-
readByteArray
byte[] readByteArray() throws java.io.IOException
Removes all bytes from this and returns them as a byte array.- Throws:
java.io.IOException
-
readByteArray
byte[] readByteArray(long byteCount) throws java.io.IOException
RemovesbyteCount
bytes from this and returns them as a byte array.- Throws:
java.io.IOException
-
read
int read(byte[] sink) throws java.io.IOException
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:
java.io.IOException
-
readFully
void readFully(byte[] sink) throws java.io.IOException
Removes exactlysink.length
bytes from this and copies them intosink
. Throws anEOFException
if the requested number of bytes cannot be read.- Throws:
java.io.IOException
-
read
int read(byte[] sink, int offset, int byteCount) throws java.io.IOException
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:
java.io.IOException
-
readFully
void readFully(Buffer sink, long byteCount) throws java.io.IOException
Removes exactlybyteCount
bytes from this and appends them tosink
. Throws anEOFException
if the requested number of bytes cannot be read.- Throws:
java.io.IOException
-
readAll
long readAll(Sink sink) throws java.io.IOException
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:
java.io.IOException
-
readUtf8
java.lang.String readUtf8() throws java.io.IOException
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:
java.io.IOException
-
readUtf8
java.lang.String readUtf8(long byteCount) throws java.io.IOException
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:
java.io.IOException
-
readUtf8Line
@Nullable java.lang.String readUtf8Line() throws java.io.IOException
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:
java.io.IOException
-
readUtf8LineStrict
java.lang.String readUtf8LineStrict() throws java.io.IOException
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:
java.io.IOException
-
readUtf8LineStrict
java.lang.String readUtf8LineStrict(long limit) throws java.io.IOException
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:
java.io.IOException
-
readUtf8CodePoint
int readUtf8CodePoint() throws java.io.IOException
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:
java.io.IOException
-
readString
java.lang.String readString(java.nio.charset.Charset charset) throws java.io.IOException
Removes all bytes from this, decodes them ascharset
, and returns the string.- Throws:
java.io.IOException
-
readString
java.lang.String readString(long byteCount, java.nio.charset.Charset charset) throws java.io.IOException
RemovesbyteCount
bytes from this, decodes them ascharset
, and returns the string.- Throws:
java.io.IOException
-
indexOf
long indexOf(byte b) throws java.io.IOException
Equivalent toindexOf(b, 0)
.- Throws:
java.io.IOException
-
indexOf
long indexOf(byte b, long fromIndex) throws java.io.IOException
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:
java.io.IOException
-
indexOf
long indexOf(byte b, long fromIndex, long toIndex) throws java.io.IOException
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:
java.io.IOException
-
indexOf
long indexOf(ByteString bytes) throws java.io.IOException
Equivalent toindexOf(bytes, 0)
.- Throws:
java.io.IOException
-
indexOf
long indexOf(ByteString bytes, long fromIndex) throws java.io.IOException
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:
java.io.IOException
-
indexOfElement
long indexOfElement(ByteString targetBytes) throws java.io.IOException
Equivalent toindexOfElement(targetBytes, 0)
.- Throws:
java.io.IOException
-
indexOfElement
long indexOfElement(ByteString targetBytes, long fromIndex) throws java.io.IOException
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:
java.io.IOException
-
rangeEquals
boolean rangeEquals(long offset, ByteString bytes) throws java.io.IOException
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:
java.io.IOException
-
rangeEquals
boolean rangeEquals(long offset, ByteString bytes, int bytesOffset, int byteCount) throws java.io.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:
java.io.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
java.io.InputStream inputStream()
Returns an input stream that reads from this source.
-
-