decodeBuffered

Decode a CharSequence using a buffer of maximum size DEFAULT_BUFFER_SIZE.

The decoding operation will allocate a single buffer, streaming decoded bytes to it and flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the DEFAULT_BUFFER_SIZE, then a buffer of that size will be allocated and action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than DEFAULT_BUFFER_SIZE, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val n = "Some long string"
        .decodeBuffered(UTF8, false, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
"SGVsbG8gV29ybGQh"
    .decodeBuffered(Base64.Default, false, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws

Decode len number of characters from the sequence, starting at index offset, using a buffer of maximum size DEFAULT_BUFFER_SIZE.

The decoding operation will allocate a single buffer, streaming decoded bytes to it and flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the DEFAULT_BUFFER_SIZE, then a buffer of that size will be allocated and action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than DEFAULT_BUFFER_SIZE, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val n = "Some long string"
        .decodeBuffered(UTF8, false, 2, 4, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
"SGVsbG8gV29ybGQh"
    .decodeBuffered(Base64.Default, false, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws

Decode a CharSequence using a buffer of maximum size maxBufSize.

The decoding operation will allocate a single buffer, streaming decoded bytes to it and flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the maxBufSize, then a buffer of that size will be allocated and action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than maxBufSize, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val n = "Some string"
        .decodeBuffered(UTF8, false, 1024, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
"SGVsbG8gV29ybGQh"
    .decodeBuffered(Base64.Default, false, 1024, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws

Decode len number of characters from the sequence, starting at index offset, using a buffer of maximum size maxBufSize.

The decoding operation will allocate a single buffer, streaming decoded bytes to it and flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the maxBufSize, then a buffer of that size will be allocated and action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than maxBufSize, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val n = "Some string"
        .decodeBuffered(UTF8, false, 2, 6, 1024, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
"SGVsbG8gV29ybGQh"
    .decodeBuffered(Base64.Default, false, 1024, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws

Decode a CharSequence using the provided pre-allocated, reusable, buf array.

The decoding operation will stream decoded bytes to the provided buf, flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the buf size, then action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than buf size, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

NOTE: If EncoderDecoder.Config.backFillBuffers is true, provided buf array will be back-filled with 0 bytes upon decoding completion.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val buf = ByteArray(DEFAULT_BUFFER_SIZE)
    var n = "Some string"
        .decodeBuffered(UTF8, false, buf, stream::write)
    n += "Some other string"
        .decodeBuffered(UTF8, false, buf, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
val buf = ByteArray(DEFAULT_BUFFER_SIZE)
"SGVsbG8gV29ybGQh"
    .decodeBuffered(Base64.Default, false, buf, d::update)
"SGVsbG8gV29ybGQh"
    .decodeBuffered(Base64.Default, false, buf, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws

Decode len number of characters from the sequence, starting at index offset, using the provided pre-allocated, reusable, buf array.

The decoding operation will stream decoded bytes to the provided buf, flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the buf size, then action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than buf size, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

NOTE: If EncoderDecoder.Config.backFillBuffers is true, provided buf array will be back-filled with 0 bytes upon decoding completion.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val buf = ByteArray(DEFAULT_BUFFER_SIZE)
    var n = "Some string"
        .decodeBuffered(UTF8, false, 1, 2, buf, stream::write)
    n += "Some other string"
        .decodeBuffered(UTF8, false, 2, 5, buf, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
val buf = ByteArray(DEFAULT_BUFFER_SIZE)
"SGVsbG8gV29ybGQh"
    .decodeBuffered(Base64.Default, false, buf, d::update)
"SGVsbG8gV29ybGQh"
    .decodeBuffered(Base64.Default, false, buf, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws

Decode a CharArray using a buffer of maximum size DEFAULT_BUFFER_SIZE.

The decoding operation will allocate a single buffer, streaming decoded bytes to it and flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the DEFAULT_BUFFER_SIZE, then a buffer of that size will be allocated and action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than DEFAULT_BUFFER_SIZE, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val n = "Some long string"
        .toCharArray()
        .decodeBuffered(UTF8, false, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
"SGVsbG8gV29ybGQh"
    .toCharArray()
    .decodeBuffered(Base64.Default, false, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws

Decode len number of characters from the array, starting at index offset, using a buffer of maximum size DEFAULT_BUFFER_SIZE.

The decoding operation will allocate a single buffer, streaming decoded bytes to it and flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the DEFAULT_BUFFER_SIZE, then a buffer of that size will be allocated and action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than DEFAULT_BUFFER_SIZE, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val n = "Some long string"
        .toCharArray()
        .decodeBuffered(UTF8, false, 2, 5, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
"SGVsbG8gV29ybGQh"
    .toCharArray()
    .decodeBuffered(Base64.Default, false, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws

Decode a CharArray using a buffer of maximum size maxBufSize.

The decoding operation will allocate a single buffer, streaming decoded bytes to it and flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the maxBufSize, then a buffer of that size will be allocated and action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than maxBufSize, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val n = "Some string"
        .toCharArray()
        .decodeBuffered(UTF8, false, 1024, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
"SGVsbG8gV29ybGQh"
    .toCharArray()
    .decodeBuffered(Base64.Default, false, 1024, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws

Decode len number of characters from the array, starting at index offset, using a buffer of maximum size maxBufSize.

The decoding operation will allocate a single buffer, streaming decoded bytes to it and flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the maxBufSize, then a buffer of that size will be allocated and action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than maxBufSize, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val n = "Some string"
        .toCharArray()
        .decodeBuffered(UTF8, false, 1, 4, 1024, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
"SGVsbG8gV29ybGQh"
    .toCharArray()
    .decodeBuffered(Base64.Default, false, 1024, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws

Decode a CharArray using the provided pre-allocated, reusable, buf array.

The decoding operation will stream decoded bytes to the provided buf, flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the buf size, then action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than buf size, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

NOTE: If EncoderDecoder.Config.backFillBuffers is true, provided buf array will be back-filled with 0 bytes upon decoding completion.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val buf = ByteArray(DEFAULT_BUFFER_SIZE)
    var n = "Some string"
        .toCharArray()
        .decodeBuffered(UTF8, false, buf, stream::write)
    n += "Some other string"
        .toCharArray()
        .decodeBuffered(UTF8, false, buf, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
val buf = ByteArray(DEFAULT_BUFFER_SIZE)
"SGVsbG8gV29ybGQh"
    .toCharArray()
    .decodeBuffered(Base64.Default, false, buf, d::update)
"SGVsbG8gV29ybGQh"
    .toCharArray()
    .decodeBuffered(Base64.Default, false, buf, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws

Decode len number of characters from the array, starting at index offset, using the provided pre-allocated, reusable, buf array.

The decoding operation will stream decoded bytes to the provided buf, flushing to action when needed. If the pre-calculated size returned by EncoderDecoder.Config.decodeOutMaxSizeOrFail is less than or equal to the buf size, then action is only invoked once (single-shot decoding). In the event that EncoderDecoder.Config.decodeOutMaxSizeOrFail throws its EncodingSizeException due to an overflow (i.e. decoding would exceed Int.MAX_VALUE) while throwOnOverflow is false, or its return value is greater than buf size, then this function will always stream decode to a buffer while flushing to action until the decoding operation has completed.

NOTE: Documented exceptions thrown by this function do not include those for which action may throw.

NOTE: If EncoderDecoder.Config.backFillBuffers is true, provided buf array will be back-filled with 0 bytes upon decoding completion.

e.g. (Using io.matthewnelson.kmp-file:file& module :utf8)

"/path/to/file.txt".toFile().openWrite(excl = null).use { stream ->
    val buf = ByteArray(DEFAULT_BUFFER_SIZE)
    var n = "Some string"
        .toCharArray()
        .decodeBuffered(UTF8, false, 0, 4, buf, stream::write)
    n += "Some other string"
        .toCharArray()
        .decodeBuffered(UTF8, false, 1, 3, buf, stream::write)
    println("Wrote $n UTF-8 bytes to file.txt")
}

e.g. (Using org.kotlincrypto.hash:sha2& module :base64)

val d = SHA256()
val buf = ByteArray(DEFAULT_BUFFER_SIZE)
"SGVsbG8gV29ybGQh"
    .toCharArray()
    .decodeBuffered(Base64.Default, false, buf, d::update)
"SGVsbG8gV29ybGQh"
    .toCharArray()
    .decodeBuffered(Base64.Default, false, buf, d::update)
// ...

NOTE: The Decoder implementation must be compatible with version 2.6.0+ APIs and define a EncoderDecoder.Config.maxDecodeEmit. If the value is -1 (i.e. it has not updated to the new API yet), then this function will fail with an EncodingException. All implementations provided by this library have been updated to meet the API requirement; only EncoderDecoder implementations external to this library that have not updated yet may fail when using them with decodeBuffered and decodeBufferedAsync APIs.

Parameters

See also

Throws