Struct CharsetConverter 

pub struct CharsetConverter<D, E>
where
    D: CharsetCodec,
    E: CharsetEncodeProbe,
{ /* private fields */ }

Converts units encoded with one charset into units encoded with another charset.

The converter owns the source and target charset codecs plus the same decode/encode policy hooks used by crate::CharsetDecoder and crate::CharsetEncoder. A decoded character may be kept pending inside the common buffered convert engine when the target output buffer is full. During BufferedTranscoder::finish, the converter drains internally retained output and finishes the composed decode/encode policy hooks. Callers remain responsible for handling any incomplete input tail before finishing the logical stream.

Type Parameters

• D: Low-level charset codec used by the source decoder.
• E: Low-level charset codec used by the target encoder.

use qubit_codec_text::{
    CharsetConverter,
    CharsetDecoder,
    CharsetEncoder,
    TranscodeStatus,
    BufferedTranscoder,
    Utf16U16Codec,
    Utf8Codec,
};

let mut converter = CharsetConverter::from_codecs(Utf8Codec, Utf16U16Codec);
let mut output = [0_u16; 2];

let progress = converter
    .transcode("AB".as_bytes(), 0, &mut output, 0)
    .expect("transcode bytes to utf-16");

assert_eq!(TranscodeStatus::Complete, progress.status());
assert_eq!(2, progress.read());
assert_eq!(2, progress.written());
assert_eq!([65, 66], output);

Implementations

impl<D, E> CharsetConverter<D, E>

where D: CharsetCodec, E: CharsetEncodeProbe,

pub fn from_codecs(source: D, target: E) -> Self

Creates a charset converter from raw source and target codecs.

Parameters

• source: Source charset codec.
• target: Target charset codec.

Returns

Returns a converter with the default decoder policy and the target encoder policy that can be represented by target. The encoder policy first tries CharsetEncodePolicy::DEFAULT_REPLACEMENT and falls back to CharsetEncodePolicy::DEFAULT_FALLBACK_REPLACEMENT when needed.

Panics

Panics when neither default replacement can be encoded by target.

pub fn from_codecs_with_policies( source: D, target: E, decode_policy: CharsetDecodePolicy, encode_policy: CharsetEncodePolicy, ) -> Result<Self, CharsetEncodeError>

Creates a charset converter from raw codecs and explicit policies.

Parameters

• source: Source charset codec.
• target: Target charset codec.
• decode_policy: Malformed source-input policy.
• encode_policy: Unmappable target-output policy.

Returns

Returns a converter configured with the supplied policies.

Errors

Returns an error when encode_policy uses replacement and the target codec cannot encode the replacement character.

pub const fn decode_policy(&self) -> CharsetDecodePolicy

Returns the configured malformed source-input policy.

Returns

Returns the decoder policy used by this converter.

pub const fn encode_policy(&self) -> CharsetEncodePolicy

Returns the configured unmappable target-output policy.

Returns

Returns the encoder policy used by this converter.

pub const fn malformed_action(&self) -> MalformedAction

Returns the configured malformed-input action.

Returns

Returns the action used when source input is malformed.

pub const fn decode_replacement(&self) -> char

Returns the configured source replacement character.

Returns

Returns the character emitted when malformed source input is replaced.

pub const fn unmappable_action(&self) -> UnmappableAction

Returns the configured unmappable-character action.

Returns

Returns the action used when the target charset cannot represent a character.

pub const fn replacement(&self) -> char

Returns the configured target replacement character.

Returns

Returns the character encoded when unmappable target input is replaced.

Trait Implementations

impl<D, E> BufferedConverter<<D as Codec>::Unit, <E as Codec>::Unit> for CharsetConverter<D, E>

where D: CharsetCodec, E: CharsetEncodeProbe,

impl<D, E> BufferedTranscoder<<D as Codec>::Unit, <E as Codec>::Unit> for CharsetConverter<D, E>

where D: CharsetCodec, E: CharsetEncodeProbe,

fn max_output_len(&self, input_len: usize) -> Result<usize, CapacityError>

Returns the target-side upper bound for converted output units.

fn max_finish_output_len(&self) -> Result<usize, CapacityError>

Returns the maximum target units needed to finalize pending conversion state.

fn reset(&mut self)

Clears any pending decoded character.

fn transcode( &mut self, input: &[D::Unit], input_index: usize, output: &mut [E::Unit], output_index: usize, ) -> Result<TranscodeProgress, Self::Error>

Converts source units to target units through the configured decoder and encoder.

Errors

Returns CharsetConvertError::Decode when input_index is outside the source input buffer or source decoding fails. Returns CharsetConvertError::Encode when target encoding fails.

fn finish( &mut self, output: &mut [E::Unit], output_index: usize, ) -> Result<usize, FinishError<Self::Error>>

Finalizes internally retained decoded characters and policy hook state.

Parameters

• output: Complete output slice visible to the converter.
• output_index: Absolute output index where writing starts.

Returns

Returns the number of target units written during finalization.

Errors

Returns FinishError when output_index is invalid, when output capacity is insufficient, or when encoding pending or final decoded characters violates target charset policy.

type Error = CharsetConvertError

Error reported for semantic conversion failures.

impl<D, E> Clone for CharsetConverter<D, E>

where D: CharsetCodec + Clone, E: CharsetEncodeProbe + Clone, E::Unit: Clone,

fn clone(&self) -> CharsetConverter<D, E>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<D, E> Debug for CharsetConverter<D, E>

where D: CharsetCodec + Debug, E: CharsetEncodeProbe + Debug, E::Unit: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<D, E> Eq for CharsetConverter<D, E>

where D: CharsetCodec + Eq, E: CharsetEncodeProbe + Eq, E::Unit: Eq,

impl<D, E> PartialEq for CharsetConverter<D, E>

where D: CharsetCodec + PartialEq, E: CharsetEncodeProbe + PartialEq, E::Unit: PartialEq,

fn eq(&self, other: &CharsetConverter<D, E>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<D, E> StructuralPartialEq for CharsetConverter<D, E>

where D: CharsetCodec, E: CharsetEncodeProbe,