qubit-codec-text 0.1.0

Buffer-oriented text encoding and decoding utilities for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
use thiserror::Error;

/// Classifies failures detected while encoding Unicode text into encoded units.
#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
pub enum CharsetEncodeErrorKind {
    /// The supplied code point is not a valid Unicode scalar value.
    #[error("The code point is not a valid Unicode scalar value.")]
    InvalidCodePoint {
        /// Raw code point value reported by the codec.
        value: u32,
    },

    /// The requested input character index is outside the input buffer.
    #[error("The input character index is outside the input buffer.")]
    InvalidInputIndex {
        /// Length of the input provided to the codec call.
        input_len: usize,
    },

    /// The requested output unit index is outside the output buffer.
    #[error("The output unit index is outside the output buffer.")]
    InvalidOutputIndex {
        /// Length of the output provided to the codec call.
        output_len: usize,
    },

    /// The character cannot be represented by the target encoding.
    #[error("The character cannot be represented by the target encoding.")]
    UnmappableCharacter {
        /// Raw character value that cannot be represented.
        value: u32,
    },

    /// The supplied output buffer is too small for the encoded character.
    #[error(
        "The output buffer is too small (required {required} units, available {available} units)."
    )]
    BufferTooSmall {
        /// Total units required to encode the character.
        required: usize,

        /// Total units currently available for the requested output index.
        available: usize,
    },
}

impl CharsetEncodeErrorKind {
    /// Returns the raw value associated with the error kind, if available.
    ///
    /// # Returns
    ///
    /// - `Some(value)` for [`Self::InvalidCodePoint`] and
    ///   [`Self::UnmappableCharacter`];
    /// - `None` for other kinds.
    #[must_use]
    #[inline(always)]
    pub const fn value(self) -> Option<u32> {
        match self {
            Self::InvalidCodePoint { value, .. } => Some(value),
            Self::UnmappableCharacter { value, .. } => Some(value),
            Self::BufferTooSmall { .. }
            | Self::InvalidInputIndex { .. }
            | Self::InvalidOutputIndex { .. } => None,
        }
    }

    /// Returns the number of required output units for this kind, if available.
    ///
    /// # Returns
    ///
    /// - `Some(required)` for [`Self::BufferTooSmall`];
    /// - `None` for all other variants.
    #[must_use]
    #[inline(always)]
    pub const fn required(self) -> Option<usize> {
        match self {
            Self::BufferTooSmall { required, .. } => Some(required),
            Self::InvalidInputIndex { .. }
            | Self::InvalidOutputIndex { .. }
            | Self::InvalidCodePoint { .. }
            | Self::UnmappableCharacter { .. } => None,
        }
    }

    /// Returns the number of currently available output units for this kind, if
    /// available.
    ///
    /// # Returns
    ///
    /// - `Some(available)` for [`Self::BufferTooSmall`];
    /// - `None` for all other variants.
    #[must_use]
    #[inline(always)]
    pub const fn available(self) -> Option<usize> {
        match self {
            Self::BufferTooSmall { available, .. } => Some(available),
            Self::InvalidInputIndex { .. }
            | Self::InvalidOutputIndex { .. }
            | Self::InvalidCodePoint { .. }
            | Self::UnmappableCharacter { .. } => None,
        }
    }

    /// Returns the input length when this error comes from an invalid input
    /// index.
    ///
    /// # Returns
    ///
    /// - `Some(input_len)` for [`Self::InvalidInputIndex`];
    /// - `None` for other variants.
    #[must_use]
    #[inline(always)]
    pub const fn input_len(self) -> Option<usize> {
        match self {
            Self::InvalidInputIndex { input_len } => Some(input_len),
            Self::InvalidCodePoint { .. }
            | Self::UnmappableCharacter { .. }
            | Self::BufferTooSmall { .. }
            | Self::InvalidOutputIndex { .. } => None,
        }
    }

    /// Returns the output length when this error comes from an invalid output
    /// index.
    ///
    /// # Returns
    ///
    /// - `Some(output_len)` for [`Self::InvalidOutputIndex`];
    /// - `None` for other variants.
    #[must_use]
    #[inline(always)]
    pub const fn output_len(self) -> Option<usize> {
        match self {
            Self::InvalidOutputIndex { output_len } => Some(output_len),
            Self::InvalidCodePoint { .. }
            | Self::InvalidInputIndex { .. }
            | Self::UnmappableCharacter { .. }
            | Self::BufferTooSmall { .. } => None,
        }
    }
}