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
Functions
Returns ReadableByteChannel backed by this source. Closing the source will close the source.
Returns an input stream that reads from this source. Closing the stream will also close this source.
Returns an input stream that reads from this source. Closing the stream will also close this source.
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.
Returns an index of byte first occurrence in the range of startIndex to endIndex, or -1 when the range doesn't contain byte.
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.
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.
Reads at most ByteBuffer.remaining bytes from this source into sink and returns the number of bytes read.
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.
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.
Decodes a single code point value from UTF-8 code units, reading between 1 and 4 bytes as necessary.
Reads a long from this source in signed decimal form (i.e., as a string in base 10 with optional leading -).
Removes eight bytes from this source and returns a floating point number with type Double composed of it according to the big-endian order.
Removes eight bytes from this source and returns a floating point number with type Double composed of it according to the little-endian order.
Removes four bytes from this source and returns a floating point number with type Float composed of it according to the little-endian order.
Reads a long form this source in hexadecimal form (i.e., as a string in base 16).
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.
Removes eight bytes from this source and returns a long integer composed of it according to the little-endian order.
Removes two bytes from this source and returns a short integer composed of it according to the little-endian order.
Removes all bytes from this source, decodes them as UTF-8, and returns the string.
Removes byteCount bytes from this source, decodes them as UTF-8, and returns the string.
Removes four bytes from this source and returns an unsigned integer composed of it according to the little-endian order.
Removes eight bytes from this source and returns an unsigned long integer composed of it according to the little-endian order.
Removes two bytes from this source and returns an unsigned short integer composed of it according to the big-endian order.
Removes two bytes from this source and returns an unsigned short integer composed of it according to the little-endian order.
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.
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.