ktor-io/io.ktor.utils.io/readUTF8LineTo

readUTF8LineTo

suspend fun ByteReadChannel.~~readUTF8LineTo~~(out: Appendable, max: Int = Int.MAX_VALUE): Boolean(source)

Deprecated

Use readLineStrictTo or readLineTo instead. See deprecation notes for more details.

Reads a UTF-8-encoded line and appends its decoded characters to out. It recognizes CR, LF, and CRLF as line delimiters.

Important: This function consumes the bytes that form the line content from the channel and appends their decoded characters to out even if it fails to complete.

Deprecation

This function is deprecated. Use readLineStrictTo or readLineTo instead.

Use readLineStrictTo when:

You need to limit the line length and throw TooLongLineException when the limit is exceeded.
You expect every line to end with an explicit line delimiter. EOFException will be thrown if the channel is exhausted after reading line content but before a line delimiter is found.

Use readLineTo when:

You do not need to limit line length.
An explicit line delimiter at the end of the channel is not mandatory.

Compared to readUTF8LineTo, the new functions differ in the following ways:

They recognize LF and CRLF as line delimiters by default, which provides better performance. To keep current behavior and recognize all line delimiters (CR, LF, and CRLF), specify LineEnding.Lenient.
They return the number of bytes read for the line content, or -1 if the channel is exhausted before a line can be read, instead of returning Boolean.
readLineStrictTo accepts Long instead of Int as a limit parameter.

The direct equivalent of readUTF8LineTo would be:

// Before
val success = channel.readUTF8LineTo(out, max = 1024)

// After
val success = try {
    channel.readLineStrictTo(out, limit = 1024, lineEnding = LineEnding.Lenient) >= 0
} catch (_: EOFException) {
    true
}

However, we recommend using the default line-ending behavior (LineEnding.Default) and do not ignore unexpected end-of-input:

val success = channel.readLineStrictTo(out, limit = 1024) >= 0

Report a problem

Return

true if a line was read, including an empty line terminated by a line delimiter; false if the channel was exhausted before a line could be read

Parameters

out

the destination to append the decoded line to; the line delimiter is not appended

max

the maximum number of bytes in the UTF-8-encoded line, excluding the line delimiter. Defaults to Int.MAX_VALUE.

Throws

TooLongLineException

if the line exceeds max

suspend fun ByteReadChannel.~~readUTF8LineTo~~(out: Appendable, max: Int = Int.MAX_VALUE, lineEnding: LineEndingMode = LineEndingMode.Any): Boolean(source)