Skip to main content

qubit_io_text/adapters/
charset_string_encoder.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
13use qubit_codec::CapacityError;
14use qubit_codec::TranscodeEncodeError;
15use qubit_codec::TranscodeStatus;
16use qubit_codec::Transcoder;
17use qubit_codec_text::Charset;
18use qubit_codec_text::CharsetCodec;
19use qubit_codec_text::CharsetEncodeError;
20use qubit_codec_text::CharsetEncodeErrorKind;
21use qubit_codec_text::CharsetEncodePolicy;
22use qubit_codec_text::CharsetEncoder;
23use qubit_codec_text::UnmappableAction;
24use qubit_utils::try_reserve_vec;
25
26const CHAR_CHUNK_CAPACITY: usize = 256;
27
28/// Convenience encoder for complete Rust strings.
29///
30/// `CharsetStringEncoder` owns a [`CharsetEncoder`] and adapts `&str` input to
31/// the `char` slices expected by the transcode layer. Lower-level streaming
32/// code should use [`CharsetEncoder`] directly; this type is for closed,
33/// in-memory string conversions.
34///
35/// # Type Parameters
36///
37/// - `C`: Charset codec used to encode Unicode scalar values into target units.
38///
39/// # Examples
40///
41/// ```
42/// use qubit_codec_text::Utf8Codec;
43/// use qubit_io_text::CharsetStringEncoder;
44///
45/// let mut encoder = CharsetStringEncoder::new(Utf8Codec);
46/// let encoded = encoder.encode_str("中文")?;
47/// assert_eq!("中文".as_bytes(), encoded.as_slice());
48/// # Ok::<(), qubit_codec_text::CharsetEncodeError>(())
49/// ```
50pub struct CharsetStringEncoder<C>
51where
52    C: CharsetCodec,
53{
54    /// Streaming encoder that performs the underlying charset conversion.
55    encoder: CharsetEncoder<C>,
56}
57
58impl<C> CharsetStringEncoder<C>
59where
60    C: CharsetCodec,
61{
62    /// Creates a string encoder with the charset default replacement policy.
63    ///
64    /// # Parameters
65    ///
66    /// - `codec`: Charset codec used to encode output units.
67    ///
68    /// # Returns
69    ///
70    /// Returns a string encoder using [`UnmappableAction::Replace`].
71    ///
72    /// # Panics
73    ///
74    /// Panics with the same conditions as [`CharsetEncoder::new`]: replacement
75    /// mode requires either the default replacement character or the fallback
76    /// `?` to be encodable by `codec`.
77    #[must_use]
78    #[inline]
79    pub fn new(codec: C) -> Self {
80        Self {
81            encoder: CharsetEncoder::new(codec),
82        }
83    }
84
85    /// Creates a string encoder with an explicit unmappable-input policy.
86    ///
87    /// # Parameters
88    ///
89    /// - `codec`: Charset codec used to encode output units.
90    /// - `policy`: Unmappable-input policy used by the encoder.
91    ///
92    /// # Returns
93    ///
94    /// Returns a string encoder configured with `policy`.
95    ///
96    /// # Errors
97    ///
98    /// Returns [`CharsetEncodeError`] when `policy` uses replacement and the
99    /// replacement character cannot be encoded by `codec`.
100    pub fn with_policy(codec: C, policy: CharsetEncodePolicy) -> Result<Self, CharsetEncodeError> {
101        Ok(Self {
102            encoder: CharsetEncoder::with_policy(codec, policy)?,
103        })
104    }
105
106    /// Returns the configured unmappable-character action.
107    #[must_use]
108    #[inline]
109    pub const fn unmappable_action(&self) -> UnmappableAction {
110        self.encoder.unmappable_action()
111    }
112
113    /// Returns the configured replacement character.
114    #[must_use]
115    #[inline]
116    pub const fn replacement(&self) -> char {
117        self.encoder.replacement()
118    }
119
120    /// Returns the wrapped charset encoder.
121    #[must_use]
122    #[inline(always)]
123    pub const fn encoder(&self) -> &CharsetEncoder<C> {
124        &self.encoder
125    }
126
127    /// Returns a mutable reference to the wrapped charset encoder.
128    #[must_use]
129    #[inline(always)]
130    pub fn encoder_mut(&mut self) -> &mut CharsetEncoder<C> {
131        &mut self.encoder
132    }
133
134    /// Consumes this string encoder and returns the wrapped charset encoder.
135    #[must_use]
136    #[inline]
137    pub fn into_encoder(self) -> CharsetEncoder<C> {
138        self.encoder
139    }
140
141    /// Makes the next reserve operation fail in coverage builds.
142    ///
143    /// # Parameters
144    ///
145    /// This function takes no parameters.
146    #[doc(hidden)]
147    #[cfg(coverage)]
148    pub fn coverage_fail_next_reserve() {
149        COVERAGE_RESERVE_FAIL_AFTER.with(|state| state.set(0));
150    }
151
152    /// Makes a later reserve operation fail in coverage builds.
153    ///
154    /// # Parameters
155    ///
156    /// - `successful_attempts`: Number of reserve attempts allowed before
157    ///   failure.
158    #[doc(hidden)]
159    #[cfg(coverage)]
160    pub fn coverage_fail_reserve_after(successful_attempts: usize) {
161        COVERAGE_RESERVE_FAIL_AFTER.with(|state| state.set(successful_attempts));
162    }
163
164    /// Makes the next capacity-bound operation fail in coverage builds.
165    ///
166    /// # Parameters
167    ///
168    /// This function takes no parameters.
169    #[doc(hidden)]
170    #[cfg(coverage)]
171    pub fn coverage_fail_next_capacity_bound() {
172        COVERAGE_CAPACITY_FAIL_AFTER.with(|state| state.set(0));
173    }
174
175    /// Makes a later capacity-bound operation fail in coverage builds.
176    ///
177    /// # Parameters
178    ///
179    /// - `successful_attempts`: Number of capacity-bound checks allowed before
180    ///   failure.
181    #[doc(hidden)]
182    #[cfg(coverage)]
183    pub fn coverage_fail_capacity_bound_after(successful_attempts: usize) {
184        COVERAGE_CAPACITY_FAIL_AFTER.with(|state| state.set(successful_attempts));
185    }
186
187    /// Clears coverage-only reserve failure hooks.
188    ///
189    /// # Parameters
190    ///
191    /// This function takes no parameters.
192    #[doc(hidden)]
193    #[cfg(coverage)]
194    pub fn coverage_reset_reserve_hooks() {
195        COVERAGE_RESERVE_FAIL_AFTER.with(|state| state.set(usize::MAX));
196        COVERAGE_CAPACITY_FAIL_AFTER.with(|state| state.set(usize::MAX));
197    }
198
199    /// Encodes a complete string into an owned output buffer.
200    ///
201    /// # Parameters
202    ///
203    /// - `input`: UTF-8 string whose Unicode scalar values are encoded.
204    ///
205    /// # Returns
206    ///
207    /// Returns an owned buffer containing the encoded units.
208    ///
209    /// # Errors
210    ///
211    /// Returns [`CharsetEncodeError`] when sizing or reserving the output, or
212    /// when encoder reset, transcoding, or finalization fails.
213    pub fn encode_str(&mut self, input: &str) -> Result<Vec<C::Unit>, CharsetEncodeError>
214    where
215        C::Unit: Default,
216    {
217        let charset = self.encoder.charset();
218        let mut output = Vec::new();
219        let reset_capacity = map_capacity_bound(self.encoder.max_reset_output_len(), charset)?;
220        ensure_owned_capacity(&mut output, 0, reset_capacity, charset)?;
221        let mut output_cursor = match self.encoder.reset(&mut output, 0) {
222            Ok(written) => written,
223            Err(error) => return Err(map_encode_error(charset, error)),
224        };
225
226        let mut chars = input.chars();
227        let mut input_offset = 0;
228        let mut chunk = ['\0'; CHAR_CHUNK_CAPACITY];
229        loop {
230            let chunk_len = fill_char_chunk(&mut chars, &mut chunk);
231            if chunk_len == 0 {
232                break;
233            }
234            let required = map_capacity_bound(self.encoder.max_transcode_output_len(chunk_len), charset)?;
235            ensure_owned_capacity(&mut output, output_cursor, required, charset)?;
236            let progress = match self
237                .encoder
238                .transcode(&chunk[..chunk_len], 0, &mut output, output_cursor)
239            {
240                Ok(progress) => progress,
241                Err(error) => {
242                    return Err(map_chunk_encode_error(charset, error, input_offset));
243                }
244            };
245            output_cursor += progress.written();
246            // The pre-sized output uses the encoder's maximum bound, and the
247            // transcode engine validates complete consumption.
248            input_offset += progress.read();
249        }
250
251        let finish_capacity = map_capacity_bound(self.encoder.max_finish_output_len(), charset)?;
252        ensure_owned_capacity(&mut output, output_cursor, finish_capacity, charset)?;
253        output_cursor += match self.encoder.finish(&mut output, output_cursor) {
254            Ok(written) => written,
255            Err(error) => return Err(map_encode_error(charset, error)),
256        };
257        output.truncate(output_cursor);
258        Ok(output)
259    }
260
261    /// Encodes a complete string into an existing output slice.
262    ///
263    /// The encoded stream starts at `output_index`, and the return value is the
264    /// number of target units written from that index.
265    ///
266    /// # Parameters
267    ///
268    /// - `input`: UTF-8 string whose Unicode scalar values are encoded.
269    /// - `output`: Complete output slice visible to the encoder.
270    /// - `output_index`: Absolute index where the encoded stream starts.
271    ///
272    /// # Returns
273    ///
274    /// Returns the number of units written to `output`.
275    ///
276    /// # Errors
277    ///
278    /// Returns [`CharsetEncodeError`] when `output_index` is outside `output`,
279    /// the slice cannot hold the complete encoded stream, output sizing
280    /// overflows, or encoding fails. When the output is too small, the prefix
281    /// written before the failing character remains in `output`.
282    pub fn encode_str_into(
283        &mut self,
284        input: &str,
285        output: &mut [C::Unit],
286        output_index: usize,
287    ) -> Result<usize, CharsetEncodeError> {
288        let charset = self.encoder.charset();
289        if output_index > output.len() {
290            return Err(CharsetEncodeError::new(
291                charset,
292                CharsetEncodeErrorKind::InvalidOutputIndex {
293                    output_len: output.len(),
294                },
295                output_index,
296            ));
297        }
298        let mut output_cursor = output_index;
299        output_cursor += match self.encoder.reset(output, output_cursor) {
300            Ok(written) => written,
301            Err(error) => return Err(map_encode_error(charset, error)),
302        };
303
304        let mut chars = input.chars();
305        let mut input_offset = 0;
306        let mut chunk = ['\0'; CHAR_CHUNK_CAPACITY];
307        loop {
308            let chunk_len = fill_char_chunk(&mut chars, &mut chunk);
309            if chunk_len == 0 {
310                break;
311            }
312            map_capacity_bound(self.encoder.max_transcode_output_len(chunk_len), charset)?;
313            let progress = match self.encoder.transcode(&chunk[..chunk_len], 0, output, output_cursor) {
314                Ok(progress) => progress,
315                Err(error) => {
316                    return Err(map_chunk_encode_error(charset, error, input_offset));
317                }
318            };
319            output_cursor += progress.written();
320            if let TranscodeStatus::NeedOutput { required } = progress.status() {
321                let available = output.len().saturating_sub(output_cursor);
322                return Err(CharsetEncodeError::new(
323                    charset,
324                    CharsetEncodeErrorKind::BufferTooSmall {
325                        required: required.get(),
326                        available,
327                    },
328                    output_cursor,
329                ));
330            }
331            input_offset += progress.read();
332        }
333
334        map_capacity_bound(self.encoder.max_finish_output_len(), charset)?;
335        output_cursor += match self.encoder.finish(output, output_cursor) {
336            Ok(written) => written,
337            Err(error) => return Err(map_encode_error(charset, error)),
338        };
339        Ok(output_cursor - output_index)
340    }
341}
342
343/// Fills one bounded character chunk from a UTF-8 scalar iterator.
344///
345/// # Parameters
346///
347/// - `chars`: Iterator supplying the remaining Unicode scalar values.
348/// - `chunk`: Fixed-size destination for the next scalar window.
349///
350/// # Returns
351///
352/// Returns the number of initialized entries in `chunk`.
353fn fill_char_chunk(chars: &mut impl Iterator<Item = char>, chunk: &mut [char; CHAR_CHUNK_CAPACITY]) -> usize {
354    let mut len = 0;
355    while len < chunk.len() {
356        let Some(ch) = chars.next() else {
357            break;
358        };
359        chunk[len] = ch;
360        len += 1;
361    }
362    len
363}
364
365/// Ensures that an owned output exposes a writable range at `output_index`.
366///
367/// # Type Parameters
368///
369/// - `T`: Default-initializable output unit stored in the buffer.
370///
371/// # Parameters
372///
373/// - `output`: Owned unit buffer to grow and initialize.
374/// - `output_index`: Start of the writable range.
375/// - `required`: Number of units that must be writable from `output_index`.
376/// - `charset`: Charset attached to any reported error.
377///
378/// # Errors
379///
380/// Returns [`CharsetEncodeErrorKind::OutputLengthOverflow`] when length
381/// arithmetic overflows or the allocation cannot be reserved.
382fn ensure_owned_capacity<T>(
383    output: &mut Vec<T>,
384    output_index: usize,
385    required: usize,
386    charset: Charset,
387) -> Result<(), CharsetEncodeError>
388where
389    T: Default,
390{
391    let Some(required_len) = output_index.checked_add(required) else {
392        return Err(output_length_overflow(charset));
393    };
394    if required_len <= output.len() {
395        return Ok(());
396    }
397    let additional = required_len - output.len();
398    let reserve_failed = try_reserve_vec(output, additional).is_err();
399    #[cfg(coverage)]
400    let reserve_failed = reserve_failed || coverage_should_fail_reserve();
401    if reserve_failed {
402        return Err(output_length_overflow(charset));
403    }
404    output.resize_with(required_len, T::default);
405    Ok(())
406}
407
408/// Maps a transcode output-bound result into the charset error model.
409///
410/// # Parameters
411///
412/// - `result`: Capacity bound reported by the transcode layer.
413/// - `charset`: Charset attached to a capacity failure.
414///
415/// # Returns
416///
417/// Returns the reported bound when successful.
418///
419/// # Errors
420///
421/// Returns [`CharsetEncodeErrorKind::OutputLengthOverflow`] when the bound
422/// cannot be represented.
423fn map_capacity_bound(result: Result<usize, CapacityError>, charset: Charset) -> Result<usize, CharsetEncodeError> {
424    #[cfg(coverage)]
425    if coverage_should_fail_capacity_bound() {
426        return Err(output_length_overflow(charset));
427    }
428    match result {
429        Ok(capacity) => Ok(capacity),
430        Err(_) => Err(output_length_overflow(charset)),
431    }
432}
433
434/// Converts a transcode-layer encode error into the charset error model.
435///
436/// # Parameters
437///
438/// - `charset`: Charset attached to framework-level failures.
439/// - `error`: Error returned by the transcode layer.
440///
441/// # Returns
442///
443/// Returns the corresponding charset encoding error.
444fn map_encode_error(charset: Charset, error: TranscodeEncodeError<CharsetEncodeError, char>) -> CharsetEncodeError {
445    CharsetEncodeError::from_transcode_error(charset, error)
446}
447
448/// Maps a chunk-local unencodable index to the complete string index.
449///
450/// # Parameters
451///
452/// - `charset`: Charset attached to framework-level failures.
453/// - `error`: Error whose input index is relative to the current chunk.
454/// - `input_offset`: Character offset of the current chunk in the string.
455///
456/// # Returns
457///
458/// Returns an error whose input index is relative to the complete string.
459fn map_chunk_encode_error(
460    charset: Charset,
461    error: TranscodeEncodeError<CharsetEncodeError, char>,
462    input_offset: usize,
463) -> CharsetEncodeError {
464    let error = match error {
465        TranscodeEncodeError::Unencodable { input_index, value } => {
466            let input_index = input_offset.saturating_add(input_index);
467            return CharsetEncodeError::map_unencodable(charset, input_index, value);
468        }
469        error => map_encode_error(charset, error),
470    };
471    match error.kind() {
472        CharsetEncodeErrorKind::InvalidOutputIndex { .. }
473        | CharsetEncodeErrorKind::BufferTooSmall { .. }
474        | CharsetEncodeErrorKind::OutputLengthOverflow => error,
475        kind => CharsetEncodeError::new(charset, kind, input_offset.saturating_add(error.index())),
476    }
477}
478
479#[cfg(coverage)]
480thread_local! {
481    static COVERAGE_RESERVE_FAIL_AFTER: Cell<usize> = const { Cell::new(usize::MAX) };
482    static COVERAGE_CAPACITY_FAIL_AFTER: Cell<usize> = const { Cell::new(usize::MAX) };
483}
484
485/// Reports whether a synthetic capacity-bound failure was requested.
486#[cfg(coverage)]
487fn coverage_should_fail_capacity_bound() -> bool {
488    COVERAGE_CAPACITY_FAIL_AFTER.with(|state| {
489        let remaining = state.get();
490        if remaining == usize::MAX {
491            return false;
492        }
493        if remaining == 0 {
494            state.set(usize::MAX);
495            return true;
496        }
497        state.set(remaining - 1);
498        false
499    })
500}
501
502/// Reports whether a synthetic reserve failure was requested.
503#[cfg(coverage)]
504fn coverage_should_fail_reserve() -> bool {
505    COVERAGE_RESERVE_FAIL_AFTER.with(|state| {
506        let remaining = state.get();
507        if remaining == usize::MAX {
508            return false;
509        }
510        if remaining == 0 {
511            state.set(usize::MAX);
512            return true;
513        }
514        state.set(remaining - 1);
515        false
516    })
517}
518
519/// Creates an output-length overflow error for `charset`.
520///
521/// # Parameters
522///
523/// - `charset`: Charset whose output length could not be represented.
524///
525/// # Returns
526///
527/// Returns an output-length-overflow error at the sentinel maximum index.
528#[inline]
529fn output_length_overflow(charset: Charset) -> CharsetEncodeError {
530    CharsetEncodeError::new(charset, CharsetEncodeErrorKind::OutputLengthOverflow, usize::MAX)
531}
532
533#[cfg(test)]
534mod tests {
535    use qubit_codec::TranscodeDomainError;
536    use qubit_codec::TranscodeEncodeError;
537    use qubit_codec::TranscodeFailure;
538    use qubit_codec_text::Charset;
539    use qubit_codec_text::CharsetEncodeError;
540    use qubit_codec_text::CharsetEncodeErrorKind;
541
542    use super::ensure_owned_capacity;
543    use super::map_chunk_encode_error;
544    use super::map_encode_error;
545
546    #[test]
547    fn test_charset_string_encoder_maps_transcode_failure() {
548        let error = map_encode_error(
549            Charset::UTF_8,
550            TranscodeEncodeError::Failure(TranscodeFailure::insufficient_output(3, 2, 1)),
551        );
552
553        assert_eq!(
554            CharsetEncodeErrorKind::BufferTooSmall {
555                required: 2,
556                available: 1,
557            },
558            error.kind(),
559        );
560        assert_eq!(3, error.index());
561    }
562
563    #[test]
564    fn test_charset_string_encoder_maps_unencodable_transcode_error() {
565        let error = map_encode_error(
566            Charset::UTF_8,
567            TranscodeEncodeError::Unencodable {
568                input_index: 3,
569                value: Some('中'),
570            },
571        );
572
573        assert_eq!(
574            CharsetEncodeErrorKind::UnmappableCharacter { value: '中' as u32 },
575            error.kind(),
576        );
577        assert_eq!(3, error.index());
578    }
579
580    #[test]
581    fn test_charset_string_encoder_maps_chunk_local_errors() {
582        let error = map_chunk_encode_error(
583            Charset::UTF_8,
584            TranscodeEncodeError::Unencodable {
585                input_index: 2,
586                value: Some('中'),
587            },
588            5,
589        );
590        assert_eq!(7, error.index());
591
592        let capacity_error = CharsetEncodeError::new(
593            Charset::UTF_8,
594            CharsetEncodeErrorKind::BufferTooSmall {
595                required: 2,
596                available: 1,
597            },
598            3,
599        );
600        let error = map_chunk_encode_error(
601            Charset::UTF_8,
602            TranscodeEncodeError::Domain(TranscodeDomainError::main(capacity_error, 0)),
603            5,
604        );
605        assert_eq!(capacity_error, error);
606    }
607
608    #[test]
609    fn test_charset_string_encoder_reports_owned_length_addition_overflow() {
610        let mut output = vec![7_u8];
611        let error = ensure_owned_capacity(&mut output, usize::MAX, 1, Charset::UTF_8)
612            .expect_err("owned output length addition should overflow");
613
614        assert_eq!(CharsetEncodeErrorKind::OutputLengthOverflow, error.kind());
615        assert_eq!(output, vec![7]);
616
617        ensure_owned_capacity(&mut output, 1, 0, Charset::UTF_8).expect("satisfied capacity should succeed");
618        assert_eq!(output, vec![7]);
619        ensure_owned_capacity(&mut output, 1, 1, Charset::UTF_8).expect("small owned capacity should be reservable");
620        assert_eq!(output, vec![7, 0]);
621    }
622}