Skip to content

Remove checked EncodingException from encode extension functions #218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
05nelsonm merged 1 commit into from
Dec 10, 2025
Merged

Remove checked EncodingException from encode extension functions #218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 41 additions & 21 deletions library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Decoder.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* which will call [doFinal] (or [close] if there was an error with
* decoding) for you.
*
* @see [newDecoderFeed]
* @see [use]
* @see [newDecoderFeed]
* @see [EncoderDecoder.Feed]
* @see [EncoderDecoder.Feed.doFinal]
* */
Expand Down Expand Up @@ -106,8 +106,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
/**
* Updates the [Decoder.Feed] with a new character to decode.
*
* @throws [EncodingException] if [isClosed] is true, or if
* there was an error decoding.
* @throws [EncodingException] If [isClosed] is `true`, or if there was an
* error decoding.
* */
@Throws(EncodingException::class)
public fun consume(input: Char) {
Expand Down Expand Up @@ -146,12 +146,13 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
}

/**
* Flushes the buffered input and performs any final decoding
* operations without closing the [Feed].
* Flushes the buffered input and performs final decoding operations without
* closing the [Feed].
*
* @see [EncoderDecoder.Feed.flush]
* @throws [EncodingException] if [isClosed] is true, or if
* there was an error decoding.
*
* @throws [EncodingException] If [isClosed] is `true`, or if there was an
* error decoding.
* */
@Throws(EncodingException::class)
public final override fun flush() {
Expand Down Expand Up @@ -224,7 +225,9 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharSequence.decodeBuffered]
* @see [CharSequence.decodeBufferedAsync]
*
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* @throws [EncodingSizeException] If the decoded output would exceed [Int.MAX_VALUE].
* */
@JvmStatic
@Throws(EncodingException::class)
Expand Down Expand Up @@ -263,7 +266,9 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharArray.decodeBuffered]
* @see [CharArray.decodeBufferedAsync]
*
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* @throws [EncodingSizeException] If the decoded output would exceed [Int.MAX_VALUE].
* */
@JvmStatic
@Throws(EncodingException::class)
Expand Down Expand Up @@ -340,7 +345,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharSequence.decodeToByteArrayOrNull]
* @see [CharSequence.decodeBufferedAsync]
*
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* */
@JvmStatic
@Throws(EncodingException::class)
Expand Down Expand Up @@ -400,7 +406,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharSequence.decodeToByteArrayOrNull]
* @see [CharSequence.decodeBufferedAsync]
*
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* @throws [IllegalArgumentException] If [maxBufSize] is less than or equal to
* [EncoderDecoder.Config.maxDecodeEmit].
* */
Expand Down Expand Up @@ -477,7 +484,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharSequence.decodeToByteArrayOrNull]
* @see [CharSequence.decodeBufferedAsync]
*
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* @throws [IllegalArgumentException] If [buf] size is less than or equal to
* [EncoderDecoder.Config.maxDecodeEmit].
* */
Expand Down Expand Up @@ -545,7 +553,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharSequence.decodeBuffered]
*
* @throws [CancellationException]
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* */
@JvmStatic
@Throws(CancellationException::class, EncodingException::class)
Expand Down Expand Up @@ -607,7 +616,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharSequence.decodeBuffered]
*
* @throws [CancellationException]
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* @throws [IllegalArgumentException] If [maxBufSize] is less than or equal to
* [EncoderDecoder.Config.maxDecodeEmit].
* */
Expand Down Expand Up @@ -686,7 +696,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharSequence.decodeBuffered]
*
* @throws [CancellationException]
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* @throws [IllegalArgumentException] If [buf] size is less than or equal to
* [EncoderDecoder.Config.maxDecodeEmit].
* */
Expand Down Expand Up @@ -755,7 +766,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharArray.decodeToByteArrayOrNull]
* @see [CharArray.decodeBufferedAsync]
*
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* */
@JvmStatic
@Throws(EncodingException::class)
Expand Down Expand Up @@ -817,7 +829,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharArray.decodeToByteArrayOrNull]
* @see [CharArray.decodeBufferedAsync]
*
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* @throws [IllegalArgumentException] If [maxBufSize] is less than or equal to
* [EncoderDecoder.Config.maxDecodeEmit].
* */
Expand Down Expand Up @@ -898,7 +911,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharArray.decodeToByteArrayOrNull]
* @see [CharArray.decodeBufferedAsync]
*
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* @throws [IllegalArgumentException] If [buf] size is less than or equal to
* [EncoderDecoder.Config.maxDecodeEmit].
* */
Expand Down Expand Up @@ -967,7 +981,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharArray.decodeBuffered]
*
* @throws [CancellationException]
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* */
@JvmStatic
@Throws(CancellationException::class, EncodingException::class)
Expand Down Expand Up @@ -1030,7 +1045,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharArray.decodeBuffered]
*
* @throws [CancellationException]
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* @throws [IllegalArgumentException] If [maxBufSize] is less than or equal to
* [EncoderDecoder.Config.maxDecodeEmit].
* */
Expand Down Expand Up @@ -1110,7 +1126,8 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
* @see [CharArray.decodeBuffered]
*
* @throws [CancellationException]
* @throws [EncodingException] If decoding failed.
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* @throws [IllegalArgumentException] If [buf] size is less than or equal to
* [EncoderDecoder.Config.maxDecodeEmit].
* */
Expand All @@ -1130,6 +1147,9 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {

/**
* DEPRECATED since `2.3.0`
* @throws [EncodingException] If decoding failed, such as the [decoder] rejecting
* an invalid character or sequence.
* @throws [EncodingSizeException] If the decoded output would exceed [Int.MAX_VALUE].
* @suppress
* */
@JvmStatic
Expand Down
45 changes: 31 additions & 14 deletions library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Encoder.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,8 @@ public sealed class Encoder<C: EncoderDecoder.Config>(config: C): Decoder<C>(con
* which will call [doFinal] (or [close] if there was an error with
* encoding) for you.
*
* @see [newEncoderFeed]
* @see [use]
* @see [newEncoderFeed]
* @see [EncoderDecoder.Feed]
* @see [EncoderDecoder.Feed.doFinal]
* */
Expand Down Expand Up @@ -116,7 +116,9 @@ public sealed class Encoder<C: EncoderDecoder.Config>(config: C): Decoder<C>(con
/**
* Updates the [Encoder.Feed] with a new byte to encode.
*
* @throws [EncodingException] if [isClosed] is true.
* @throws [EncodingException] If [isClosed] is `true`, or the [Feed] is configured
* to reject something, such as `UTF-8` byte to text transformations rejecting
* invalid byte sequences.
* */
@Throws(EncodingException::class)
public fun consume(input: Byte) {
Expand All @@ -135,7 +137,10 @@ public sealed class Encoder<C: EncoderDecoder.Config>(config: C): Decoder<C>(con
* operations without closing the [Feed].
*
* @see [EncoderDecoder.Feed.flush]
* @throws [EncodingException] if [isClosed] is true.
*
* @throws [EncodingException] If [isClosed] is `true`, or the [Feed] is configured
* to reject something, such as `UTF-8` byte to text transformations rejecting
* invalid byte sequences.
* */
@Throws(EncodingException::class)
public final override fun flush() {
Expand Down Expand Up @@ -199,14 +204,19 @@ public sealed class Encoder<C: EncoderDecoder.Config>(config: C): Decoder<C>(con
public companion object {

/**
* Encodes a [ByteArray] for the provided [encoder] and
* returns the encoded data in the form of a [String].
* Encode a [ByteArray].
*
* @param [encoder] The [Encoder] to use.
*
* @return The [String] of encoded data.
*
* @throws [EncodingSizeException] if the encoded output
* exceeds [Int.MAX_VALUE].
* @see [encodeToCharArray]
*
* @throws [EncodingException] If the [encoder] is configured to reject something,
* such as `UTF-8` byte to text transformations rejecting invalid byte sequences.
* @throws [EncodingSizeException] If the encoded output would exceed [Int.MAX_VALUE].
* */
@JvmStatic
@Throws(EncodingSizeException::class)
public fun ByteArray.encodeToString(encoder: Encoder<*>): String {
return encoder.encodeOutMaxSizeOrFail(size) { maxSize ->
val sb = StringBuilder(maxSize)
Expand All @@ -224,14 +234,19 @@ public sealed class Encoder<C: EncoderDecoder.Config>(config: C): Decoder<C>(con
}

/**
* Encodes a [ByteArray] for the provided [encoder] and
* returns the encoded data in the form of a [CharArray].
* Encode a [ByteArray].
*
* @param [encoder] The [Encoder] to use.
*
* @return The [CharArray] of encoded data.
*
* @see [encodeToString]
*
* @throws [EncodingSizeException] if the encoded output
* exceeds [Int.MAX_VALUE].
* @throws [EncodingException] If the [encoder] is configured to reject something,
* such as `UTF-8` byte to text transformations rejecting invalid byte sequences.
* @throws [EncodingSizeException] If the encoded output exceeds [Int.MAX_VALUE].
* */
@JvmStatic
@Throws(EncodingSizeException::class)
public fun ByteArray.encodeToCharArray(encoder: Encoder<*>): CharArray {
return encoder.encodeOutMaxSizeOrFail(size) block@ { maxSize ->
var i = 0
Expand All @@ -248,10 +263,12 @@ public sealed class Encoder<C: EncoderDecoder.Config>(config: C): Decoder<C>(con

/**
* DEPRECATED since `2.3.0`
* @throws [EncodingException] If the [encoder] is configured to reject something,
* such as `UTF-8` byte to text transformations rejecting invalid byte sequences.
* @throws [EncodingSizeException] if the encoded output exceeds [Int.MAX_VALUE].
* @suppress
* */
@JvmStatic
@Throws(EncodingSizeException::class)
@Deprecated(
message = "Should not utilize. Underlying Char to Byte conversion can produce incorrect results",
level = DeprecationLevel.ERROR,
Expand Down
4 changes: 2 additions & 2 deletions library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/EncoderDecoder.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -546,7 +546,7 @@ public abstract class EncoderDecoder<C: EncoderDecoder.Config>(config: C): Encod
* [Feed]s are meant to be single use disposables for the
* given encoding/decoding operation.
*
* TLDR; [Feed]s only care about [Byte]s and [Char]s, not the medium
* TL;DR [Feed]s only care about [Byte]s and [Char]s, not the medium
* for which they come from or are going to. Use the [use] extension
* function.
*
Expand Down Expand Up @@ -635,7 +635,7 @@ public abstract class EncoderDecoder<C: EncoderDecoder.Config>(config: C): Encod
* will not be considered an error if already closed.
*
* After [close] has been called, any invocation of
* [Decoder.Feed.consume], [Encoder.Feed.consume],
* [Decoder.Feed.consume], [Encoder.Feed.consume], [flush]
* or [doFinal] will be considered an error and throw an
* [EncodingException].
*
Expand Down