qubit_codec_misc/hex_codec_config.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//! Configuration shared by hexadecimal byte codecs.
9
10/// Configuration shared by [`crate::HexCodec`] encoding and decoding
11/// operations.
12///
13/// The configuration is intentionally separate from the codec value so the
14/// same formatting and decoding policy can be reused by multiple codecs.
15///
16/// # Examples
17///
18/// ```
19/// use qubit_codec_misc::HexCodec;
20/// use qubit_codec_misc::HexCodecConfig;
21///
22/// let config = HexCodecConfig::new()
23/// .with_uppercase(true)
24/// .with_prefix("0x");
25/// let codec = HexCodec::from_config(config);
26/// assert_eq!(codec.encode(&[0x1f, 0x8b]), "0x1F8B");
27/// ```
28#[must_use]
29#[derive(Debug, Clone, PartialEq, Eq)]
30pub struct HexCodecConfig {
31 /// Whether to use uppercase hexadecimal digits while encoding.
32 pub(crate) uppercase: bool,
33 /// The prefix to use before the whole encoded string.
34 pub(crate) prefix: Option<String>,
35 /// The prefix to use before each encoded byte.
36 pub(crate) byte_prefix: Option<String>,
37 /// The separator to use between bytes in the encoded string.
38 pub(crate) separator: Option<String>,
39 /// Whether to ignore ASCII whitespace while decoding.
40 pub(crate) ignore_ascii_whitespace: bool,
41 /// Whether to ignore ASCII case when matching configured prefixes.
42 pub(crate) ignore_prefix_case: bool,
43}
44
45impl HexCodecConfig {
46 /// Creates a lowercase configuration without prefixes or separators.
47 #[inline]
48 pub fn new() -> Self {
49 Self {
50 uppercase: false,
51 prefix: None,
52 byte_prefix: None,
53 separator: None,
54 ignore_ascii_whitespace: false,
55 ignore_prefix_case: false,
56 }
57 }
58
59 /// Returns whether encoded digits use uppercase characters.
60 #[must_use]
61 #[inline]
62 pub fn is_uppercase(&self) -> bool {
63 self.uppercase
64 }
65
66 /// Returns the configured whole-output prefix.
67 ///
68 /// # Returns
69 /// `Some` contains the prefix written before the encoded bytes; `None`
70 /// means no whole-output prefix is configured.
71 #[inline]
72 pub fn prefix(&self) -> Option<&str> {
73 self.prefix.as_deref()
74 }
75
76 /// Returns the configured per-byte prefix.
77 ///
78 /// # Returns
79 /// `Some` contains the prefix written before each encoded byte; `None`
80 /// means no per-byte prefix is configured.
81 #[inline]
82 pub fn byte_prefix(&self) -> Option<&str> {
83 self.byte_prefix.as_deref()
84 }
85
86 /// Returns the configured separator.
87 ///
88 /// # Returns
89 /// `Some` contains the separator written between bytes; `None` means no
90 /// separator is configured.
91 #[inline]
92 pub fn separator(&self) -> Option<&str> {
93 self.separator.as_deref()
94 }
95
96 /// Returns whether ASCII whitespace is ignored while decoding.
97 #[must_use]
98 #[inline]
99 pub fn ignores_ascii_whitespace(&self) -> bool {
100 self.ignore_ascii_whitespace
101 }
102
103 /// Returns whether configured prefixes are matched case-insensitively.
104 #[must_use]
105 #[inline]
106 pub fn ignores_prefix_case(&self) -> bool {
107 self.ignore_prefix_case
108 }
109
110 /// Sets whether encoded digits should be uppercase.
111 ///
112 /// # Parameters
113 /// - `uppercase`: Whether encoding uses uppercase hexadecimal digits.
114 ///
115 /// # Returns
116 /// The updated configuration.
117 #[inline]
118 pub fn with_uppercase(mut self, uppercase: bool) -> Self {
119 self.uppercase = uppercase;
120 self
121 }
122
123 /// Sets a whole-output prefix.
124 ///
125 /// # Parameters
126 /// - `prefix`: Text written once before all encoded bytes.
127 ///
128 /// # Returns
129 /// The updated configuration.
130 #[inline]
131 pub fn with_prefix(mut self, prefix: impl Into<String>) -> Self {
132 self.prefix = Some(prefix.into());
133 self
134 }
135
136 /// Sets a per-byte prefix.
137 ///
138 /// # Parameters
139 /// - `prefix`: Text written before each encoded byte.
140 ///
141 /// # Returns
142 /// The updated configuration.
143 #[inline]
144 pub fn with_byte_prefix(mut self, prefix: impl Into<String>) -> Self {
145 self.byte_prefix = Some(prefix.into());
146 self
147 }
148
149 /// Sets a separator between encoded bytes.
150 ///
151 /// # Parameters
152 /// - `separator`: Text written between adjacent encoded bytes.
153 ///
154 /// # Returns
155 /// The updated configuration.
156 #[inline]
157 pub fn with_separator(mut self, separator: impl Into<String>) -> Self {
158 self.separator = Some(separator.into());
159 self
160 }
161
162 /// Sets whether ASCII whitespace is ignored while decoding.
163 ///
164 /// # Parameters
165 /// - `ignore`: Whether ASCII whitespace is skipped during decoding.
166 ///
167 /// # Returns
168 /// The updated configuration.
169 #[inline]
170 pub fn with_ignored_ascii_whitespace(mut self, ignore: bool) -> Self {
171 self.ignore_ascii_whitespace = ignore;
172 self
173 }
174
175 /// Sets whether configured prefixes are matched case-insensitively.
176 ///
177 /// # Parameters
178 /// - `ignore`: Whether prefix matching ignores ASCII letter case.
179 ///
180 /// # Returns
181 /// The updated configuration.
182 #[inline]
183 pub fn with_ignore_prefix_case(mut self, ignore: bool) -> Self {
184 self.ignore_prefix_case = ignore;
185 self
186 }
187}
188
189impl Default for HexCodecConfig {
190 #[inline]
191 fn default() -> Self {
192 Self::new()
193 }
194}