Remove checked EncodingException from encode extension functions (#218)

Author: 05nelsonm

library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Decoder.kt

@@ -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]
      * */
@@ -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) {
@@ -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() {
@@ -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)
@@ -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)
@@ -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)
@@ -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].
          * */
@@ -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].
          * */
@@ -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)
@@ -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].
          * */
@@ -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].
          * */
@@ -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)
@@ -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].
          * */
@@ -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].
          * */
@@ -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)
@@ -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].
          * */
@@ -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].
          * */
@@ -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

library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Encoder.kt

@@ -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]
      * */
@@ -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) {
@@ -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() {
@@ -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)
@@ -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
@@ -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,

library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/EncoderDecoder.kt

@@ -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.
      *
@@ -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].
          *