Source

sealed interface Source : RawSource(source)

A source that facilitates typed data reads and keeps a buffer internally so that callers can read chunks of data without requesting it from a downstream on every call.

Source is the main kotlinx-io interface to read data in client's code, any RawSource could be converted into Source using RawSource.buffered.

Depending on the kind of downstream and the number of bytes read, buffering may improve the performance by hiding the latency of small reads.

The buffer is refilled on reads as necessary, but it is also possible to ensure it contains enough data using require or request. Sink also allows skipping unneeded prefix of data using skip and provides look ahead into incoming data, buffering as much as necessary, using peek.

Source's read* methods have different guarantees of how much data will be consumed from the source and what to expect in case of error.

Read methods' behavior and naming conventions

Unless stated otherwise, all read methods consume the exact number of bytes requested (or the number of bytes required to represent a value of a requested type). If a source contains fewer bytes than requested, these methods will throw an exception.

Methods reading up to requested number of bytes are named as readAtMost in contrast to methods reading exact number of bytes, which don't have AtMost suffix in their names. If a source contains fewer bytes than requested, these methods will not treat it as en error and will return gracefully.

Methods returning a value as a result are named read<Type>, like readInt or readByte. These methods don't consume source's content in case of an error.

Methods reading data into a consumer supplied as one of its arguments are named read*To, like readTo or readAtMostTo. These methods consume a source even when an error occurs.

Methods moving all data from a source to some other sink are named transferTo, like transferTo.

It is recommended to follow the same naming convention for Source extensions.

Thread-safety guarantees

Until stated otherwise, Source implementations are not thread safe. If a Source needs to be accessed from multiple threads, an additional synchronization is required.

Inheritors

Properties

Link copied to clipboard

This source's internal buffer. It contains data fetched from the downstream, but not yet consumed by the upstream.

Functions

Link copied to clipboard

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

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
abstract override fun close()

Closes this source and releases the resources held by this source. It is an error to read a closed source. It is safe to close a source more than once.

Link copied to clipboard
abstract fun exhausted(): Boolean

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

Link copied to clipboard
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 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
abstract 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
abstract 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.

abstract fun readAtMostTo(sink: ByteArray, startIndex: Int = 0, endIndex: Int = sink.size): 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

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

Link copied to clipboard
abstract 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
abstract 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
abstract 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
abstract 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 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
abstract 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.

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
abstract 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
abstract 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
abstract fun skip(byteCount: Long)

Reads and discards byteCount bytes from this source.

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
abstract 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.