diff --git a/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Decoder.kt b/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Decoder.kt index 0f1f54b..98536ea 100644 --- a/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Decoder.kt +++ b/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Decoder.kt @@ -77,8 +77,8 @@ public sealed class Decoder(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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(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 diff --git a/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Encoder.kt b/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Encoder.kt index 59eaa58..7e5e903 100644 --- a/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Encoder.kt +++ b/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Encoder.kt @@ -84,8 +84,8 @@ public sealed class Encoder(config: C): Decoder(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(config: C): Decoder(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(config: C): Decoder(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(config: C): Decoder(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(config: C): Decoder(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(config: C): Decoder(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, diff --git a/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/EncoderDecoder.kt b/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/EncoderDecoder.kt index 46fe6c5..2ae86d6 100644 --- a/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/EncoderDecoder.kt +++ b/library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/EncoderDecoder.kt @@ -546,7 +546,7 @@ public abstract class EncoderDecoder(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(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]. *