Buffer

A collection of bytes in memory.

The buffer can be viewed as an unbound queue whose size grows with the data being written and shrinks with data being consumed. Internally, the buffer consists of data segments, and the buffer's capacity grows and shrinks in units of data segments instead of individual bytes.

The buffer was designed to reduce memory allocations when possible. Instead of copying bytes from one place in memory to another, this class just changes ownership of the underlying data segments.

To reduce allocations and speed up the buffer's extension, it may use data segments pooling.

Buffer implements both Source and Sink and could be used as a source or a sink, but unlike regular sinks and sources its close, flush, emit, hintEmit does not affect buffer's state and exhausted only indicates that a buffer is empty.

Thread-safety guarantees

Buffer does not provide any thread-safety guarantees. If a Buffer needs to be accessed from multiple threads, an additional synchronization is required. Failure to do so will result in possible data corruption, loss, and runtime errors.

Constructors

Link copied to clipboard
constructor()

Properties

Link copied to clipboard
open override val buffer: Buffer

Returns the buffer itself.

Link copied to clipboard
val size: Long

The number of bytes accessible for read from this buffer.

Functions

Link copied to clipboard

Returns a new ByteChannel instance representing this buffer.

Returns WritableByteChannel backed by this sink. Closing the channel will also close the sink.

Returns ReadableByteChannel backed by this source. Closing the source will close the source.

Link copied to clipboard

Returns an input stream that reads from this source. Closing the stream will also close this source.

Link copied to clipboard
fun Source.asNSInputStream(): <Error class: unknown class>

Returns an input stream that reads from this source. Closing the stream will also close this source.

Link copied to clipboard
fun Sink.asNSOutputStream(): <Error class: unknown class>

Returns an output stream that writes to this sink. Closing the stream will also close this sink.

Link copied to clipboard

Returns an output stream that writes to this sink. Closing the stream will also close this sink.

Link copied to clipboard

Returns a new sink that buffers writes to the sink. The returned sink will batch writes to the sink. Use this wherever you write to a sink to get ergonomic and efficient access to data.

Returns a new source that buffers reads from the source. The returned source will perform bulk reads into its in-memory buffer. Use this wherever you read a source to get ergonomic and efficient access to data.

Link copied to clipboard
fun clear()

Discards all bytes in this buffer.

Link copied to clipboard
open override fun close()

This method does not affect the buffer.

Link copied to clipboard
fun copy(): Buffer

Returns a deep copy of this buffer.

Link copied to clipboard
fun copyTo(out: Buffer, startIndex: Long = 0, endIndex: Long = size)

Copies bytes from this buffer's subrange starting at startIndex and ending at endIndex, to out buffer. This method does not consume data from the buffer.

Link copied to clipboard
fun Buffer.copyTo(out: OutputStream, startIndex: Long = 0, endIndex: Long = size)

Copies bytes from this buffer's subrange, starting at startIndex and ending at endIndex, to out. This method does not consume data from the buffer.

Link copied to clipboard
open override fun emit()

This method does not affect the buffer's content as there is no upstream to write data to.

Link copied to clipboard
open override fun exhausted(): Boolean

Returns true if there are no more bytes in this source.

Link copied to clipboard
open override fun flush()

This method does not affect the buffer's content as there is no upstream to write data to.

Link copied to clipboard
operator fun get(position: Long): Byte

Returns the byte at position.

Link copied to clipboard
open override fun hintEmit()

This method does not affect the buffer's content as there is no upstream to write data to.

Link copied to clipboard
fun Buffer.indexOf(byteString: ByteString, startIndex: Long = 0): Long

fun Source.indexOf(byteString: ByteString, startIndex: Long = 0): Long

Returns the index of the first match for byteString in the source at or after startIndex. This expands the source's buffer as necessary until byteString 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.

fun Buffer.indexOf(byte: Byte, startIndex: Long = 0, endIndex: Long = size): Long
fun Source.indexOf(byte: Byte, startIndex: Long = 0, endIndex: Long = Long.MAX_VALUE): Long

Returns an index of byte first occurrence in the range of startIndex to endIndex, or -1 when the range doesn't contain byte.

Link copied to clipboard
open override fun peek(): Source

Returns a new Source that can read data from this source without consuming it. The returned source becomes invalid once this source is next read or closed.

Link copied to clipboard
open override fun readAtMostTo(sink: Buffer, byteCount: Long): Long

Removes at least 1, and up to byteCount bytes from this source and appends them to sink. Returns the number of bytes read, or -1 if this source is exhausted.

open override fun readAtMostTo(sink: ByteArray, startIndex: Int, endIndex: Int): Int

Removes up to endIndex - startIndex bytes from this source, copies them into sink subrange starting at startIndex and ending at endIndex, and returns the number of bytes read, or -1 if this source is exhausted.

Link copied to clipboard

Writes up to ByteBuffer.remaining bytes from this buffer to the sink. Return the number of bytes written.

Reads at most ByteBuffer.remaining bytes from this source into sink and returns the number of bytes read.

Link copied to clipboard
open override fun readByte(): Byte

Removes a byte from this source and returns it.

Link copied to clipboard

Removes all bytes from this source and returns them as a byte array.

Removes byteCount bytes from this source and returns them as a byte array.

Link copied to clipboard

Consumes all bytes from this source and wraps it into a byte string.

Consumes exactly byteCount bytes from this source and wraps it into a byte string.

Link copied to clipboard

Decodes a single code point value from UTF-8 code units, reading between 1 and 4 bytes as necessary.

Link copied to clipboard

Reads a long from this source in signed decimal form (i.e., as a string in base 10 with optional leading -).

Link copied to clipboard

Removes eight bytes from this source and returns a floating point number with type Double composed of it according to the big-endian order.

Link copied to clipboard

Removes eight bytes from this source and returns a floating point number with type Double composed of it according to the little-endian order.

Link copied to clipboard

Removes four bytes from this source and returns a floating point number with type Float composed of it according to the big-endian order.

Link copied to clipboard

Removes four bytes from this source and returns a floating point number with type Float composed of it according to the little-endian order.

Link copied to clipboard

Reads a long form this source in hexadecimal form (i.e., as a string in base 16).

Link copied to clipboard
open override fun readInt(): Int

Removes four bytes from this source and returns an integer composed of it according to the big-endian order.

Link copied to clipboard

Removes four bytes from this source and returns an integer composed of it according to the little-endian order.

Link copied to clipboard

Removes and returns UTF-8 encoded 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.

Link copied to clipboard
fun Source.readLineStrict(limit: Long = Long.MAX_VALUE): String

Removes and returns UTF-8 encoded characters up to but not including the next line break, throwing EOFException if a line break was not encountered. A line break is either "\n" or "\r\n"; these characters are not included in the result.

Link copied to clipboard
open override fun readLong(): Long

Removes eight bytes from this source and returns a long integer composed of it according to the big-endian order.

Link copied to clipboard

Removes eight bytes from this source and returns a long integer composed of it according to the little-endian order.

Link copied to clipboard
open override fun readShort(): Short

Removes two bytes from this source and returns a short integer composed of it according to the big-endian order.

Link copied to clipboard

Removes two bytes from this source and returns a short integer composed of it according to the little-endian order.

Link copied to clipboard

Removes all bytes from this buffer, decodes them as UTF-8, and returns the string.

Removes all bytes from this source, decodes them as UTF-8, and returns the string.

fun Source.readString(byteCount: Long): String

Removes byteCount bytes from this source, decodes them as UTF-8, and returns the string.

Decodes whole content of this stream into a string using charset. Returns empty string if the source is exhausted.

fun Source.readString(byteCount: Long, charset: Charset): String

Decodes byteCount bytes of this stream into a string using charset.

Link copied to clipboard
open override fun readTo(sink: RawSink, byteCount: Long)

Removes exactly byteCount bytes from this source and writes them to sink.

Link copied to clipboard
fun Source.readTo(sink: ByteArray, startIndex: Int = 0, endIndex: Int = sink.size)

Removes exactly endIndex - startIndex bytes from this source and copies them into sink subrange starting at startIndex and ending at endIndex.

fun Buffer.readTo(out: OutputStream, byteCount: Long = size)

Consumes byteCount bytes from this buffer and writes it to out.

Link copied to clipboard

Removes an unsigned byte from this source and returns it.

Link copied to clipboard

Removes four bytes from this source and returns an unsigned integer composed of it according to the big-endian order.

Link copied to clipboard

Removes four bytes from this source and returns an unsigned integer composed of it according to the little-endian order.

Link copied to clipboard

Removes eight bytes from this source and returns an unsigned long integer composed of it according to the big-endian order.

Link copied to clipboard

Removes eight bytes from this source and returns an unsigned long integer composed of it according to the little-endian order.

Link copied to clipboard

Removes two bytes from this source and returns an unsigned short integer composed of it according to the big-endian order.

Link copied to clipboard

Removes two bytes from this source and returns an unsigned short integer composed of it according to the little-endian order.

Link copied to clipboard
open override fun request(byteCount: Long): Boolean

Attempts to fill the buffer with at least byteCount bytes of data from the underlying source and returns a value indicating if the requirement was successfully fulfilled.

Link copied to clipboard
open override fun require(byteCount: Long)

Attempts to fill the buffer with at least byteCount bytes of data from the underlying source and throw EOFException when the source is exhausted before fulfilling the requirement.

Link copied to clipboard
open override fun skip(byteCount: Long)

Discards byteCount bytes from the head of this buffer.

Link copied to clipboard

Creates a byte string containing a copy of all the data from this buffer.

Link copied to clipboard

Return true if the next byte to be consumed from this source is equal to byte. Otherwise, return false as well as when the source is exhausted.

Link copied to clipboard
open override fun toString(): String

Returns a human-readable string that describes the contents of this buffer. For buffers containing few bytes, this is a string like Buffer(size=4 hex=0000ffff). However, if the buffer is too large, a string will contain its size and only a prefix of data, like Buffer(size=1024 hex=01234…). Thus, the string could not be used to compare buffers or verify buffer's content.

Link copied to clipboard
open override fun transferFrom(source: RawSource): Long

Removes all bytes from source and write them to this sink. Returns the number of bytes read which will be 0 if source is exhausted.

Link copied to clipboard

Reads and exhausts bytes from input into this buffer. Stops reading data on input exhaustion.

Reads all data from source into this buffer.

Link copied to clipboard
open override fun transferTo(sink: RawSink): Long

Removes all bytes from this source, writes them to sink, and returns the total number of bytes written to sink.

Link copied to clipboard
open override fun write(source: Buffer, byteCount: Long)

Removes byteCount bytes from source and appends them to this sink.

open override fun write(source: RawSource, byteCount: Long)

Removes byteCount bytes from source and write them to this sink.

open override fun write(source: ByteArray, startIndex: Int, endIndex: Int)

Writes bytes from source array or its subrange to this sink.

Link copied to clipboard
fun Sink.write(byteString: ByteString, startIndex: Int = 0, endIndex: Int = byteString.size)

Writes subsequence of data from byteString starting at startIndex and ending at endIndex into a sink.

fun Sink.write(source: ByteBuffer): Int

Writes data from the source into this sink and returns the number of bytes written.

fun Buffer.write(input: InputStream, byteCount: Long): Buffer

Reads byteCount bytes from input into this buffer. Throws an exception when input is exhausted before reading byteCount bytes.

Link copied to clipboard
open override fun writeByte(byte: Byte)

Writes a byte to this sink.

Link copied to clipboard
fun Sink.writeCodePointValue(codePoint: Int)

Encodes codePoint in UTF-8 and writes it to this sink.

Link copied to clipboard

Writes long to this sink in signed decimal form (i.e., as a string in base 10).

Link copied to clipboard
fun Sink.writeDouble(double: Double)

Writes eight bytes of a bit representation of double, in the big-endian order, to this sink. Bit representation of the double corresponds to the IEEE 754 floating-point "double format" bit layout.

Link copied to clipboard

Writes eight bytes of a bit representation of double, in the little-endian order, to this sink. Bit representation of the double corresponds to the IEEE 754 floating-point "double format" bit layout.

Link copied to clipboard
fun Sink.writeFloat(float: Float)

Writes four bytes of a bit representation of float, in the big-endian order, to this sink. Bit representation of the float corresponds to the IEEE 754 floating-point "single format" bit layout.

Link copied to clipboard
fun Sink.writeFloatLe(float: Float)

Writes four bytes of a bit representation of float, in the little-endian order, to this sink. Bit representation of the float corresponds to the IEEE 754 floating-point "single format" bit layout.

Link copied to clipboard

Writes long to this sink in hexadecimal form (i.e., as a string in base 16).

Link copied to clipboard
open override fun writeInt(int: Int)

Writes four bytes containing int, in the big-endian order, to this sink.

Link copied to clipboard
fun Sink.writeIntLe(int: Int)

Writes four bytes containing int, in the little-endian order, to this sink.

Link copied to clipboard
open override fun writeLong(long: Long)

Writes eight bytes containing long, in the big-endian order, to this sink.

Link copied to clipboard
fun Sink.writeLongLe(long: Long)

Writes eight bytes containing long, in the little-endian order, to this sink.

Link copied to clipboard
open override fun writeShort(short: Short)

Writes two bytes containing short, in the big-endian order, to this sink.

Link copied to clipboard
fun Sink.writeShortLe(short: Short)

Writes two bytes containing short, in the little-endian order, to this sink.

Link copied to clipboard
fun Sink.writeString(chars: CharSequence, startIndex: Int = 0, endIndex: Int = chars.length)

Encodes the characters at startIndex up to endIndex from chars in UTF-8 and writes it to this sink.

fun Sink.writeString(string: String, startIndex: Int = 0, endIndex: Int = string.length)

Encodes the characters at startIndex up to endIndex from string in UTF-8 and writes it to this sink.

fun Sink.writeString(string: String, charset: Charset, startIndex: Int = 0, endIndex: Int = string.length)

Encodes substring of string starting at startIndex and ending at endIndex using charset and writes into this sink.

Link copied to clipboard

Provides direct access to the sink's internal buffer and hints its emit before exit.

Link copied to clipboard
fun Sink.writeUByte(byte: UByte)

Writes am unsigned byte to this sink.

Link copied to clipboard
fun Sink.writeUInt(int: UInt)

Writes four bytes containing int, in the big-endian order, to this sink.

Link copied to clipboard

Writes four bytes containing int, in the little-endian order, to this sink.

Link copied to clipboard
fun Sink.writeULong(long: ULong)

Writes eight bytes containing long, in the big-endian order, to this sink.

Link copied to clipboard

Writes eight bytes containing long, in the little-endian order, to this sink.

Link copied to clipboard
fun Sink.writeUShort(short: UShort)

Writes two bytes containing short, in the big-endian order, to this sink.

Link copied to clipboard

Writes two bytes containing short, in the little-endian order, to this sink.