qubit_codec_text/codec/charset_codec.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// =============================================================================
8use crate::{
9 Charset,
10 CharsetDecodeError,
11 CharsetEncodeError,
12};
13use qubit_codec::Codec;
14
15/// Charset metadata carried by a low-level `Codec<Value = char>`.
16///
17/// `CharsetCodec` stays at the same low-level layer as [`Codec`]. It identifies
18/// the charset, while actual storage unit type, single-value encoding, and
19/// decoding are provided by the inherited unsafe [`Codec`] contract. Checked
20/// buffer management, stream boundary handling, replacement policy, and
21/// unmappable-character policy live in [`crate::CharsetDecoder`] and
22/// [`crate::CharsetEncoder`].
23///
24/// Built-in variable-width codecs report incomplete prefixes through
25/// [`CharsetDecodeError`], so buffered decoders can call
26/// [`Codec::decode_unchecked`] as soon as at least
27/// [`Codec::min_units_per_value`] units are available.
28///
29/// # Associated Types
30///
31/// Implementors must also implement the low-level [`Codec`] contract with
32/// `Value = char`, plus [`CharsetDecodeError`] and [`CharsetEncodeError`] as
33/// the concrete error types. The storage unit is inherited from
34/// [`Codec::Unit`], keeping text wrappers bound to the same object without
35/// duplicating associated types.
36pub trait CharsetCodec:
37 Codec<
38 Value = char,
39 DecodeError = CharsetDecodeError,
40 EncodeError = CharsetEncodeError,
41 >
42{
43 /// Returns the charset handled by this codec.
44 ///
45 /// # Returns
46 ///
47 /// Returns the codec's charset descriptor.
48 #[must_use]
49 fn charset(&self) -> Charset;
50}