Skip to main content

qubit_io_text/adapters/
charset_string_decoder.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8// qubit-style: allow coverage-cfg
9
10#[cfg(coverage)]
11use std::cell::Cell;
12#[cfg(coverage)]
13use std::num::NonZeroUsize;
14
15use qubit_codec::CapacityError;
16use qubit_codec::TranscodeDecodeError;
17use qubit_codec::TranscodeStatus;
18use qubit_codec::Transcoder;
19use qubit_codec_text::Charset;
20use qubit_codec_text::CharsetCodec;
21use qubit_codec_text::CharsetDecodeError;
22use qubit_codec_text::CharsetDecodeErrorKind;
23use qubit_codec_text::CharsetDecodePolicy;
24use qubit_codec_text::CharsetDecoder;
25use qubit_codec_text::MalformedAction;
26use qubit_utils::try_reserve_string;
27use qubit_utils::try_reserve_vec;
28
29const CHAR_CHUNK_CAPACITY: usize = 256;
30
31/// Convenience decoder for complete inputs that should become a [`String`].
32///
33/// `CharsetStringDecoder` owns a [`CharsetDecoder`] and adapts the `char`
34/// output expected by the transcode layer into UTF-8 `String` storage.
35/// Lower-level streaming code should use [`CharsetDecoder`] directly; this
36/// type is for closed, in-memory string conversions.
37///
38/// # Type Parameters
39///
40/// - `C`: Charset codec used to decode source units into Unicode scalar values.
41///
42/// # Examples
43///
44/// ```
45/// use qubit_codec_text::Utf8Codec;
46/// use qubit_io_text::CharsetStringDecoder;
47///
48/// let mut decoder = CharsetStringDecoder::new(Utf8Codec);
49/// let decoded = decoder.decode_to_string("中文".as_bytes())?;
50/// assert_eq!("中文", decoded);
51/// # Ok::<(), qubit_codec_text::CharsetDecodeError>(())
52/// ```
53pub struct CharsetStringDecoder<C>
54where
55    C: CharsetCodec,
56{
57    /// Owns the charset codec and decode policy used for each closed input
58    /// conversion.
59    decoder: CharsetDecoder<C>,
60}
61
62impl<C> CharsetStringDecoder<C>
63where
64    C: CharsetCodec,
65{
66    /// Creates a string decoder with the default replacement policy.
67    ///
68    /// # Parameters
69    ///
70    /// - `codec`: Charset codec used to decode input units.
71    ///
72    /// # Returns
73    ///
74    /// Returns a decoder using [`MalformedAction::Replace`].
75    #[must_use]
76    #[inline]
77    pub fn new(codec: C) -> Self {
78        Self::with_policy(codec, CharsetDecodePolicy::default())
79    }
80
81    /// Creates a string decoder with an explicit malformed-input policy.
82    ///
83    /// # Parameters
84    ///
85    /// - `codec`: Charset codec used to decode input units.
86    /// - `policy`: Malformed-input policy used by the decoder.
87    ///
88    /// # Returns
89    ///
90    /// Returns a string decoder configured with `policy`.
91    #[must_use]
92    pub fn with_policy(codec: C, policy: CharsetDecodePolicy) -> Self {
93        Self {
94            decoder: CharsetDecoder::with_policy(codec, policy),
95        }
96    }
97
98    /// Returns the configured malformed-input action.
99    ///
100    /// # Returns
101    ///
102    /// The action used for malformed or incomplete input.
103    #[must_use]
104    #[inline]
105    pub const fn malformed_action(&self) -> MalformedAction {
106        self.decoder.malformed_action()
107    }
108
109    /// Returns the configured replacement character.
110    ///
111    /// # Returns
112    ///
113    /// The character emitted when the configured action replaces input.
114    #[must_use]
115    #[inline]
116    pub const fn replacement(&self) -> char {
117        self.decoder.replacement()
118    }
119
120    /// Returns the wrapped charset decoder.
121    ///
122    /// # Returns
123    ///
124    /// A shared reference to the decoder owned by this adapter.
125    #[must_use]
126    #[inline(always)]
127    pub const fn decoder(&self) -> &CharsetDecoder<C> {
128        &self.decoder
129    }
130
131    /// Returns a mutable reference to the wrapped charset decoder.
132    ///
133    /// # Returns
134    ///
135    /// A mutable reference to the decoder owned by this adapter.
136    #[must_use]
137    #[inline(always)]
138    pub fn decoder_mut(&mut self) -> &mut CharsetDecoder<C> {
139        &mut self.decoder
140    }
141
142    /// Consumes this string decoder and returns the wrapped charset decoder.
143    ///
144    /// # Returns
145    ///
146    /// The decoder previously owned by this adapter.
147    #[must_use]
148    #[inline]
149    pub fn into_decoder(self) -> CharsetDecoder<C> {
150        self.decoder
151    }
152
153    /// Makes the next reserve operation fail in coverage builds.
154    #[doc(hidden)]
155    #[cfg(coverage)]
156    pub fn coverage_fail_next_reserve() {
157        COVERAGE_RESERVE_FAIL_AFTER.with(|state| state.set(0));
158    }
159
160    /// Makes a later reserve operation fail in coverage builds.
161    ///
162    /// # Parameters
163    ///
164    /// - `successful_attempts`: Number of reserve attempts allowed before
165    ///   failure.
166    #[doc(hidden)]
167    #[cfg(coverage)]
168    pub fn coverage_fail_reserve_after(successful_attempts: usize) {
169        COVERAGE_RESERVE_FAIL_AFTER.with(|state| state.set(successful_attempts));
170    }
171
172    /// Shrinks the next character buffer capacity in coverage builds.
173    ///
174    /// # Parameters
175    ///
176    /// - `amount`: Number of character slots removed from the next capacity
177    ///   request.
178    #[doc(hidden)]
179    #[cfg(coverage)]
180    pub fn coverage_shrink_next_char_capacity_by(amount: usize) {
181        COVERAGE_CHAR_CAPACITY_SHRINK_BY.with(|state| state.set(amount));
182    }
183
184    /// Clears coverage-only reserve failure hooks.
185    #[doc(hidden)]
186    #[cfg(coverage)]
187    pub fn coverage_reset_reserve_hooks() {
188        COVERAGE_RESERVE_FAIL_AFTER.with(|state| state.set(usize::MAX));
189        COVERAGE_CHAR_CAPACITY_SHRINK_BY.with(|state| state.set(0));
190        COVERAGE_FORCE_STATUS.with(|state| state.set(0));
191        COVERAGE_FORCE_OUTPUT_COUNT_OVERFLOW.with(|state| state.set(false));
192        COVERAGE_FORCE_RESET_CAPACITY_ERROR.with(|state| state.set(false));
193        COVERAGE_FORCE_FINISH_CAPACITY_ERROR.with(|state| state.set(false));
194    }
195
196    /// Forces the next transcode status in coverage builds.
197    ///
198    /// # Parameters
199    ///
200    /// - `mode`: Status selector consumed by the next transcode operation.
201    #[doc(hidden)]
202    #[cfg(coverage)]
203    pub fn coverage_force_next_status(mode: u8) {
204        COVERAGE_FORCE_STATUS.with(|state| state.set(mode));
205    }
206
207    /// Forces the output character count overflow branch in coverage builds.
208    #[doc(hidden)]
209    #[cfg(coverage)]
210    pub fn coverage_force_output_count_overflow() {
211        COVERAGE_FORCE_OUTPUT_COUNT_OVERFLOW.with(|state| state.set(true));
212    }
213
214    /// Forces reset capacity planning to fail in coverage builds.
215    #[doc(hidden)]
216    #[cfg(coverage)]
217    pub fn coverage_force_reset_capacity_error() {
218        COVERAGE_FORCE_RESET_CAPACITY_ERROR.with(|state| state.set(true));
219    }
220
221    /// Forces finish capacity planning to fail in coverage builds.
222    #[doc(hidden)]
223    #[cfg(coverage)]
224    pub fn coverage_force_finish_capacity_error() {
225        COVERAGE_FORCE_FINISH_CAPACITY_ERROR.with(|state| state.set(true));
226    }
227
228    /// Decodes a complete input slice into an owned [`String`].
229    ///
230    /// # Parameters
231    ///
232    /// - `input`: Complete source units.
233    ///
234    /// # Returns
235    ///
236    /// Returns decoded UTF-8 text.
237    ///
238    /// # Errors
239    ///
240    /// Returns [`CharsetDecodeError`] when decoding fails, output sizing
241    /// overflows, or the configured decode policy rejects malformed or
242    /// incomplete input.
243    pub fn decode_to_string(&mut self, input: &[C::Unit]) -> Result<String, CharsetDecodeError> {
244        let mut output = String::new();
245        self.decode_to_string_into(input, 0, &mut output)?;
246        Ok(output)
247    }
248
249    /// Decodes a complete input slice and appends the decoded text to
250    /// `output`.
251    ///
252    /// This method treats `input[input_index..]` as a closed stream. If the
253    /// underlying decoder requests more input, the tail is reported as
254    /// [`CharsetDecodeErrorKind::IncompleteSequence`].
255    ///
256    /// On success, decoded text is appended to `output`. If this method returns
257    /// `Err`, the destination string retains its original contents. This
258    /// guarantee applies to the destination only; it does not roll back
259    /// decoder state or cover panics. Streaming text-reader operations have
260    /// their own prefix-retention contracts.
261    ///
262    /// # Parameters
263    ///
264    /// - `input`: Complete input slice visible to the decoder.
265    /// - `input_index`: Absolute index where decoding starts.
266    /// - `output`: String receiving decoded text.
267    ///
268    /// # Returns
269    ///
270    /// Returns `()` after appending all decoded text successfully.
271    ///
272    /// # Errors
273    ///
274    /// Returns [`CharsetDecodeError`] when `input_index` is outside `input`,
275    /// decoding fails, or output sizing overflows.
276    pub fn decode_to_string_into(
277        &mut self,
278        input: &[C::Unit],
279        input_index: usize,
280        output: &mut String,
281    ) -> Result<(), CharsetDecodeError> {
282        if input_index > input.len() {
283            return Err(CharsetDecodeError::new(
284                self.decoder.charset(),
285                CharsetDecodeErrorKind::InvalidInputIndex { input_len: input.len() },
286                input_index,
287            ));
288        }
289        let output_len = output.len();
290        let result = self.decode_bounded(input, input_index, output);
291        if result.is_err() {
292            output.truncate(output_len);
293        }
294        result
295    }
296
297    /// Drives one closed decode lifecycle through a bounded character buffer.
298    ///
299    /// # Parameters
300    ///
301    /// - `input`: Complete source-unit slice visible to the decoder.
302    /// - `input_index`: Absolute unit index where decoding starts.
303    /// - `output`: String receiving decoded UTF-8 text.
304    ///
305    /// # Returns
306    ///
307    /// Returns `()` after the closed decode lifecycle completes successfully.
308    ///
309    /// # Errors
310    ///
311    /// Returns [`CharsetDecodeError`] for malformed or incomplete input,
312    /// invalid transcode progress, output-length overflow, or allocation
313    /// failure.
314    fn decode_bounded(
315        &mut self,
316        input: &[C::Unit],
317        input_index: usize,
318        output: &mut String,
319    ) -> Result<(), CharsetDecodeError> {
320        let charset = self.decoder.charset();
321        let reset_capacity = match coverage_capacity_result(self.decoder.max_reset_output_len(), true) {
322            Ok(capacity) => capacity,
323            Err(_) => return Err(output_length_overflow(charset)),
324        };
325        let char_capacity = reset_capacity.max(CHAR_CHUNK_CAPACITY);
326        #[cfg(coverage)]
327        let char_capacity = char_capacity.saturating_sub(coverage_take_char_capacity_shrink());
328        let mut chars = Vec::new();
329        ensure_char_capacity(&mut chars, char_capacity, charset)?;
330        let reset_written = match self.decoder.reset(&mut chars, 0) {
331            Ok(written) => written,
332            Err(error) => return Err(map_decode_error(charset, error)),
333        };
334        append_chars(output, &chars[..reset_written], charset)?;
335        let mut output_char_count = reset_written;
336
337        let mut input_cursor = input_index;
338        loop {
339            let progress = match self.decoder.transcode_eof(input, input_cursor, &mut chars, 0) {
340                Ok(progress) => progress,
341                Err(error) => {
342                    return Err(map_decode_error(charset, error));
343                }
344            };
345            append_chars(output, &chars[..progress.written()], charset)?;
346            let checked_output_char_count = coverage_output_count(output_char_count);
347            let Some(next_output_char_count) = checked_output_char_count.checked_add(progress.written()) else {
348                return Err(output_length_overflow(charset));
349            };
350            output_char_count = next_output_char_count;
351            input_cursor += progress.read();
352            match coverage_status(progress.status()) {
353                TranscodeStatus::Complete => break,
354                TranscodeStatus::NeedInput { required } => {
355                    let available = input.len().saturating_sub(input_cursor);
356                    let kind = CharsetDecodeErrorKind::IncompleteSequence {
357                        required: required.get(),
358                        available,
359                    };
360                    return Err(CharsetDecodeError::new(charset, kind, input_cursor));
361                }
362                TranscodeStatus::NeedOutput { required, .. } => {
363                    if progress.read() == 0 && progress.written() == 0 {
364                        let required = required.get().max(CHAR_CHUNK_CAPACITY);
365                        ensure_char_capacity(&mut chars, required, charset)?;
366                    }
367                }
368            }
369        }
370
371        let finish_capacity = match coverage_capacity_result(self.decoder.max_finish_output_len(), false) {
372            Ok(capacity) => capacity,
373            Err(_) => return Err(output_length_overflow(charset)),
374        };
375        ensure_char_capacity(&mut chars, finish_capacity, charset)?;
376        let finish_written = match self.decoder.finish(&mut chars, 0) {
377            Ok(written) => written,
378            Err(error) => {
379                return Err(map_finish_decode_error(charset, error, output_char_count));
380            }
381        };
382        append_chars(output, &chars[..finish_written], charset)
383    }
384}
385
386/// Ensures that the reusable decoded-character buffer exposes `required` slots.
387///
388/// # Parameters
389///
390/// - `chars`: Reusable character buffer to grow and initialize.
391/// - `required`: Minimum number of character slots required.
392/// - `charset`: Charset attached to any reported error.
393///
394/// # Returns
395///
396/// Returns `()` after the requested character slots are available.
397///
398/// # Errors
399///
400/// Returns [`CharsetDecodeErrorKind::OutputLengthOverflow`] when the allocation
401/// cannot be reserved.
402fn ensure_char_capacity(chars: &mut Vec<char>, required: usize, charset: Charset) -> Result<(), CharsetDecodeError> {
403    if required <= chars.len() {
404        return Ok(());
405    }
406    let additional = required - chars.len();
407    let reserve_failed = try_reserve_vec(chars, additional).is_err();
408    #[cfg(coverage)]
409    let reserve_failed = reserve_failed || coverage_should_fail_reserve();
410    if reserve_failed {
411        return Err(output_length_overflow(charset));
412    }
413    chars.resize(required, '\0');
414    Ok(())
415}
416
417/// Appends one decoded character window to a string.
418///
419/// # Parameters
420///
421/// - `output`: String receiving the decoded characters.
422/// - `chars`: Decoded character window to append.
423/// - `charset`: Charset attached to any reported error.
424///
425/// # Returns
426///
427/// Returns `()` after the characters have been appended.
428///
429/// # Errors
430///
431/// Returns [`CharsetDecodeErrorKind::OutputLengthOverflow`] when the required
432/// UTF-8 storage cannot be reserved.
433fn append_chars(output: &mut String, chars: &[char], charset: Charset) -> Result<(), CharsetDecodeError> {
434    let byte_capacity = required_string_capacity(chars);
435    let reserve_failed = try_reserve_string(output, byte_capacity).is_err();
436    #[cfg(coverage)]
437    let reserve_failed = reserve_failed || coverage_should_fail_reserve();
438    if reserve_failed {
439        return Err(output_length_overflow(charset));
440    }
441    output.extend(chars.iter());
442    Ok(())
443}
444
445/// Converts a transcode-layer decode error into the charset error model.
446///
447/// # Parameters
448///
449/// - `charset`: Charset attached to framework-level failures.
450/// - `error`: Error returned by the transcode layer.
451///
452/// # Returns
453///
454/// Returns the corresponding charset decoding error.
455fn map_decode_error(charset: Charset, error: TranscodeDecodeError<CharsetDecodeError>) -> CharsetDecodeError {
456    CharsetDecodeError::from_transcode_error(charset, error)
457}
458
459/// Preserves finish domain errors and globalizes framework output indices.
460///
461/// # Parameters
462///
463/// - `charset`: Charset attached to framework-level failures.
464/// - `error`: Domain error or framework failure reported while finishing.
465/// - `output_offset`: Character count already appended before finishing.
466///
467/// # Returns
468///
469/// Returns domain errors unchanged. Framework output indices are relative to
470/// the complete output; other framework error indices remain unchanged.
471fn map_finish_decode_error(
472    charset: Charset,
473    error: TranscodeDecodeError<CharsetDecodeError>,
474    output_offset: usize,
475) -> CharsetDecodeError {
476    let failure = match error {
477        TranscodeDecodeError::Failure(failure) => failure,
478        TranscodeDecodeError::Domain(error) => return error.into_source(),
479    };
480    let error = map_decode_error(charset, TranscodeDecodeError::Failure(failure));
481    if matches!(
482        error.kind(),
483        CharsetDecodeErrorKind::InvalidOutputIndex { .. } | CharsetDecodeErrorKind::BufferTooSmall { .. }
484    ) {
485        CharsetDecodeError::new(charset, error.kind(), output_offset.saturating_add(error.index()))
486    } else {
487        error
488    }
489}
490
491#[cfg(coverage)]
492thread_local! {
493    static COVERAGE_RESERVE_FAIL_AFTER: Cell<usize> = const { Cell::new(usize::MAX) };
494    static COVERAGE_CHAR_CAPACITY_SHRINK_BY: Cell<usize> = const { Cell::new(0) };
495    static COVERAGE_FORCE_STATUS: Cell<u8> = const { Cell::new(0) };
496    static COVERAGE_FORCE_OUTPUT_COUNT_OVERFLOW: Cell<bool> = const { Cell::new(false) };
497    static COVERAGE_FORCE_RESET_CAPACITY_ERROR: Cell<bool> = const { Cell::new(false) };
498    static COVERAGE_FORCE_FINISH_CAPACITY_ERROR: Cell<bool> = const { Cell::new(false) };
499}
500
501/// Returns and clears the synthetic char capacity shrink request.
502///
503/// # Returns
504///
505/// The pending number of character slots to remove, or zero when unset.
506#[cfg(coverage)]
507#[must_use]
508fn coverage_take_char_capacity_shrink() -> usize {
509    COVERAGE_CHAR_CAPACITY_SHRINK_BY.with(|state| {
510        let amount = state.get();
511        state.set(0);
512        amount
513    })
514}
515
516/// Reports whether a synthetic reserve failure was requested.
517///
518/// # Returns
519///
520/// `true` once when the configured reserve attempt should fail.
521#[cfg(coverage)]
522fn coverage_should_fail_reserve() -> bool {
523    COVERAGE_RESERVE_FAIL_AFTER.with(|state| {
524        let remaining = state.get();
525        if remaining == usize::MAX {
526            return false;
527        }
528        if remaining == 0 {
529            state.set(usize::MAX);
530            return true;
531        }
532        state.set(remaining - 1);
533        false
534    })
535}
536
537/// Replaces a transcode status with the one-shot coverage override, when set.
538///
539/// # Parameters
540///
541/// - `status`: Transcode status to preserve when no override is pending.
542///
543/// # Returns
544///
545/// The pending synthetic status, or `status` when no override is set.
546#[cfg(coverage)]
547fn coverage_status(status: TranscodeStatus) -> TranscodeStatus {
548    match COVERAGE_FORCE_STATUS.with(|state| state.replace(0)) {
549        1 => TranscodeStatus::NeedInput {
550            required: NonZeroUsize::MIN,
551        },
552        2 => TranscodeStatus::NeedOutput {
553            required: NonZeroUsize::MIN,
554        },
555        _ => status,
556    }
557}
558
559/// Returns the transcode status unchanged in non-coverage builds.
560///
561/// # Parameters
562///
563/// - `status`: Transcode status supplied by the decoder.
564///
565/// # Returns
566///
567/// The unchanged `status` value.
568#[cfg(not(coverage))]
569fn coverage_status(status: TranscodeStatus) -> TranscodeStatus {
570    status
571}
572
573/// Supplies a one-shot overflow value for coverage branch testing.
574///
575/// # Parameters
576///
577/// - `count`: Actual output character count unless an override is pending.
578///
579/// # Returns
580///
581/// The synthetic overflow count when requested, or `count` otherwise.
582#[cfg(coverage)]
583#[must_use]
584fn coverage_output_count(count: usize) -> usize {
585    if COVERAGE_FORCE_OUTPUT_COUNT_OVERFLOW.with(|state| state.replace(false)) {
586        usize::MAX
587    } else {
588        count
589    }
590}
591
592/// Returns the actual output character count in non-coverage builds.
593///
594/// # Parameters
595///
596/// - `count`: Actual output character count to preserve.
597///
598/// # Returns
599///
600/// The unchanged `count` value.
601#[cfg(not(coverage))]
602#[must_use]
603fn coverage_output_count(count: usize) -> usize {
604    count
605}
606
607/// Injects a one-shot capacity error for reset or finish coverage paths.
608///
609/// # Parameters
610///
611/// - `result`: Capacity calculation result unless an override is pending.
612/// - `reset`: Selects the reset hook when true and the finish hook otherwise.
613///
614/// # Returns
615///
616/// The synthetic capacity error when requested, or the original result.
617#[cfg(coverage)]
618fn coverage_capacity_result(result: Result<usize, CapacityError>, reset: bool) -> Result<usize, CapacityError> {
619    let force = if reset {
620        COVERAGE_FORCE_RESET_CAPACITY_ERROR.with(|state| state.replace(false))
621    } else {
622        COVERAGE_FORCE_FINISH_CAPACITY_ERROR.with(|state| state.replace(false))
623    };
624    if force {
625        Err(CapacityError::OutputLengthOverflow)
626    } else {
627        result
628    }
629}
630
631/// Returns the actual capacity result in non-coverage builds.
632///
633/// # Parameters
634///
635/// - `result`: Capacity calculation result to preserve.
636/// - `_reset`: Unused selector retained to match the coverage-build signature.
637///
638/// # Returns
639///
640/// The unchanged capacity calculation result.
641#[cfg(not(coverage))]
642fn coverage_capacity_result(result: Result<usize, CapacityError>, _reset: bool) -> Result<usize, CapacityError> {
643    result
644}
645
646/// Creates an output-length overflow error for `charset`.
647///
648/// # Parameters
649///
650/// - `charset`: Charset whose output length could not be represented.
651///
652/// # Returns
653///
654/// Returns an output-length-overflow error at the sentinel maximum index.
655#[inline]
656fn output_length_overflow(charset: Charset) -> CharsetDecodeError {
657    CharsetDecodeError::new(charset, CharsetDecodeErrorKind::OutputLengthOverflow, usize::MAX)
658}
659
660/// Returns the UTF-8 byte capacity required for a decoded character slice.
661///
662/// # Parameters
663///
664/// - `chars`: Decoded characters that will be appended to a string.
665///
666/// # Returns
667///
668/// Returns the exact number of additional UTF-8 bytes required.
669#[must_use]
670fn required_string_capacity(chars: &[char]) -> usize {
671    let mut capacity = 0;
672    for ch in chars {
673        capacity += ch.len_utf8();
674    }
675    capacity
676}
677
678#[cfg(test)]
679mod tests {
680    use qubit_codec::TranscodeDecodeError;
681    use qubit_codec::TranscodeDomainError;
682    use qubit_codec::TranscodeFailure;
683    use qubit_codec_text::Charset;
684    use qubit_codec_text::CharsetDecodeError;
685    use qubit_codec_text::CharsetDecodeErrorKind;
686
687    use super::map_decode_error;
688    use super::map_finish_decode_error;
689
690    #[test]
691    fn test_charset_string_decoder_maps_framework_and_finish_errors() {
692        let error = map_decode_error(
693            Charset::UTF_8,
694            TranscodeDecodeError::Failure(TranscodeFailure::insufficient_output(3, 2, 1)),
695        );
696        assert_eq!(
697            CharsetDecodeErrorKind::BufferTooSmall {
698                required: 2,
699                available: 1,
700            },
701            error.kind(),
702        );
703        assert_eq!(3, error.index());
704
705        let invalid_output = map_finish_decode_error(
706            Charset::UTF_8,
707            TranscodeDecodeError::Failure(TranscodeFailure::invalid_output_index(3, 2)),
708            7,
709        );
710        assert_eq!(
711            CharsetDecodeErrorKind::InvalidOutputIndex { output_len: 2 },
712            invalid_output.kind()
713        );
714        assert_eq!(10, invalid_output.index());
715
716        let insufficient_output = map_finish_decode_error(
717            Charset::UTF_8,
718            TranscodeDecodeError::Failure(TranscodeFailure::insufficient_output(3, 2, 1)),
719            7,
720        );
721        assert_eq!(
722            CharsetDecodeErrorKind::BufferTooSmall {
723                required: 2,
724                available: 1
725            },
726            insufficient_output.kind()
727        );
728        assert_eq!(10, insufficient_output.index());
729
730        let invalid_input = map_finish_decode_error(
731            Charset::UTF_8,
732            TranscodeDecodeError::Failure(TranscodeFailure::invalid_input_index(3, 2)),
733            7,
734        );
735        assert_eq!(
736            CharsetDecodeErrorKind::InvalidInputIndex { input_len: 2 },
737            invalid_input.kind()
738        );
739        assert_eq!(3, invalid_input.index());
740
741        let unexpected = map_finish_decode_error(
742            Charset::UTF_8,
743            TranscodeDecodeError::Failure(TranscodeFailure::TranscodeBeforeReset),
744            7,
745        );
746        assert_eq!(CharsetDecodeErrorKind::TranscodeBeforeReset, unexpected.kind());
747        assert_eq!(usize::MAX, unexpected.index());
748
749        let unknown = map_finish_decode_error(
750            Charset::UTF_8,
751            TranscodeDecodeError::Failure(TranscodeFailure::trailing_input(1, 1)),
752            7,
753        );
754        assert_eq!(CharsetDecodeErrorKind::UnexpectedTranscodeFailure, unknown.kind());
755        assert_eq!(usize::MAX, unknown.index());
756
757        let overflow = map_finish_decode_error(
758            Charset::UTF_8,
759            TranscodeDecodeError::Failure(TranscodeFailure::output_length_overflow()),
760            7,
761        );
762        assert_eq!(CharsetDecodeErrorKind::OutputLengthOverflow, overflow.kind());
763        assert_eq!(usize::MAX, overflow.index());
764
765        let domain_error = CharsetDecodeError::new(Charset::ASCII, CharsetDecodeErrorKind::malformed(0xff), 7)
766            .with_consumed(core::num::NonZeroUsize::new(2).expect("two is non-zero"));
767        let error = map_finish_decode_error(
768            Charset::UTF_8,
769            TranscodeDecodeError::Domain(TranscodeDomainError::finish(domain_error)),
770            300,
771        );
772        assert_eq!(domain_error, error);
773        assert_eq!(Some(0xff), error.kind().value());
774
775        let overflow =
776            CharsetDecodeError::new(Charset::UTF_8, CharsetDecodeErrorKind::OutputLengthOverflow, usize::MAX);
777        let error = map_finish_decode_error(
778            Charset::UTF_8,
779            TranscodeDecodeError::Domain(TranscodeDomainError::finish(overflow)),
780            7,
781        );
782        assert_eq!(overflow, error);
783    }
784}