qubit_io_binary/ext/string_read_ext.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//! Extension methods for reading length-prefixed UTF-8 strings.
9
10use std::io::Result;
11
12use qubit_codec::ByteOrder;
13use qubit_io::Input;
14
15use crate::BinaryReadExt;
16use crate::Leb128ReadExt;
17use crate::util::read_utf8_payload as read_utf8_payload_impl;
18use crate::util::read_utf8_payload_into as read_utf8_payload_into_impl;
19#[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
20use crate::util::usize_from_u32_len;
21#[cfg(not(target_pointer_width = "64"))]
22use crate::util::usize_from_u64_len;
23
24/// Extension methods for reading length-prefixed UTF-8 strings.
25///
26/// String-producing methods may return allocation failures as I/O errors in
27/// addition to input and validation errors described below.
28pub trait StringReadExt: Input<Item = u8> {
29 /// Reads and validates a UTF-8 payload into reusable byte storage.
30 ///
31 /// # Parameters
32 ///
33 /// - `bytes`: Reusable destination buffer. It is cleared before a permitted
34 /// read and contains the received bytes when the read succeeds or when
35 /// UTF-8 validation fails.
36 /// - `len`: UTF-8 payload length in bytes.
37 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
38 ///
39 /// # Returns
40 ///
41 /// Returns after `bytes` contains one valid UTF-8 payload.
42 ///
43 /// # Errors
44 ///
45 /// Returns an I/O error for payload reads or allocation failures, or
46 /// [`std::io::ErrorKind::InvalidData`] when `len` exceeds `max_len` or
47 /// the payload is not valid UTF-8.
48 fn read_utf8_payload_into(&mut self, bytes: &mut Vec<u8>, len: usize, max_len: usize) -> Result<()>;
49
50 /// Reads a UTF-8 payload with an already decoded byte length.
51 ///
52 /// # Parameters
53 ///
54 /// - `len`: UTF-8 payload length in bytes.
55 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
56 ///
57 /// # Returns
58 ///
59 /// The decoded string.
60 ///
61 /// # Errors
62 ///
63 /// Returns an I/O error for payload reads,
64 /// [`std::io::ErrorKind::InvalidData`] when `len` exceeds `max_len`, or
65 /// [`std::io::ErrorKind::InvalidData`] when the payload is not valid
66 /// UTF-8.
67 fn read_utf8_payload(&mut self, len: usize, max_len: usize) -> Result<String>;
68
69 /// Reads a UTF-8 string with an unsigned LEB128 byte-length prefix.
70 ///
71 /// The length prefix is decoded as `usize`, so this format is target-width
72 /// dependent. Prefer `u16` or `u32` length-prefix methods for persistent
73 /// files and cross-platform protocols.
74 ///
75 /// # Parameters
76 ///
77 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
78 ///
79 /// # Returns
80 ///
81 /// The decoded string.
82 ///
83 /// # Errors
84 ///
85 /// Returns an I/O error for length or payload reads,
86 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
87 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
88 /// is not valid UTF-8.
89 fn read_utf8_string_uleb_usize(&mut self, max_len: usize) -> Result<String>;
90
91 /// Reads a UTF-8 string with a canonical unsigned LEB128 byte-length
92 /// prefix.
93 ///
94 /// The length prefix is decoded as `usize`, so this format is target-width
95 /// dependent. Prefer `u16` or `u32` length-prefix methods for persistent
96 /// files and cross-platform protocols.
97 ///
98 /// # Parameters
99 ///
100 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
101 ///
102 /// # Returns
103 ///
104 /// The decoded string.
105 ///
106 /// # Errors
107 ///
108 /// Returns an I/O error for length or payload reads,
109 /// [`std::io::ErrorKind::InvalidData`] when the length prefix is
110 /// malformed or non-canonical, [`std::io::ErrorKind::InvalidData`] when
111 /// the encoded length exceeds `max_len`, or
112 /// [`std::io::ErrorKind::InvalidData`] when the payload is not valid
113 /// UTF-8.
114 fn read_utf8_string_uleb_usize_strict(&mut self, max_len: usize) -> Result<String>;
115
116 /// Reads a UTF-8 string with an unsigned LEB128 `u64` byte-length prefix.
117 ///
118 /// Prefer this method over [`Self::read_utf8_string_uleb_usize`] for
119 /// persistent files and cross-platform protocols because the length
120 /// field is independent of the current Rust target's pointer width.
121 ///
122 /// # Parameters
123 ///
124 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
125 ///
126 /// # Returns
127 ///
128 /// The decoded string.
129 ///
130 /// # Errors
131 ///
132 /// Returns an I/O error for length or payload reads,
133 /// [`std::io::ErrorKind::InvalidData`] when the encoded `u64` length
134 /// does not fit the local `usize`, when the encoded length exceeds
135 /// `max_len`, or when the payload is not valid UTF-8.
136 fn read_utf8_string_uleb_u64(&mut self, max_len: usize) -> Result<String>;
137
138 /// Reads a UTF-8 string with a canonical unsigned LEB128 `u64` byte-length
139 /// prefix.
140 ///
141 /// Prefer this method over [`Self::read_utf8_string_uleb_usize_strict`] for
142 /// persistent files and cross-platform protocols because the length field
143 /// is independent of the current Rust target's pointer width.
144 ///
145 /// # Parameters
146 ///
147 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
148 ///
149 /// # Returns
150 ///
151 /// The decoded string.
152 ///
153 /// # Errors
154 ///
155 /// Returns an I/O error for length or payload reads,
156 /// [`std::io::ErrorKind::InvalidData`] when the length prefix is
157 /// malformed or non-canonical, when the encoded `u64` length does not
158 /// fit the local `usize`, when the encoded length exceeds `max_len`, or
159 /// when the payload is not valid UTF-8.
160 fn read_utf8_string_uleb_u64_strict(&mut self, max_len: usize) -> Result<String>;
161
162 /// Reads a UTF-8 string with a runtime-order `u16` byte-length prefix.
163 ///
164 /// # Parameters
165 ///
166 /// - `byte_order`: Byte order used by the length prefix.
167 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
168 ///
169 /// # Returns
170 ///
171 /// The decoded string.
172 ///
173 /// # Errors
174 ///
175 /// Returns an I/O error for length or payload reads,
176 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
177 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
178 /// is not valid UTF-8.
179 fn read_string_with_u16_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String>;
180
181 /// Reads a UTF-8 string with a big-endian `u16` byte-length prefix.
182 ///
183 /// # Parameters
184 ///
185 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
186 ///
187 /// # Returns
188 ///
189 /// The decoded string.
190 ///
191 /// # Errors
192 ///
193 /// Returns an I/O error for length or payload reads,
194 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
195 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
196 /// is not valid UTF-8.
197 fn read_string_with_u16_len_be(&mut self, max_len: usize) -> Result<String>;
198
199 /// Reads a UTF-8 string with a little-endian `u16` byte-length prefix.
200 ///
201 /// # Parameters
202 ///
203 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
204 ///
205 /// # Returns
206 ///
207 /// The decoded string.
208 ///
209 /// # Errors
210 ///
211 /// Returns an I/O error for length or payload reads,
212 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
213 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
214 /// is not valid UTF-8.
215 fn read_string_with_u16_len_le(&mut self, max_len: usize) -> Result<String>;
216
217 /// Reads a UTF-8 string with a runtime-order `u32` byte-length prefix.
218 ///
219 /// # Parameters
220 ///
221 /// - `byte_order`: Byte order used by the length prefix.
222 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
223 ///
224 /// # Returns
225 ///
226 /// The decoded string.
227 ///
228 /// # Errors
229 ///
230 /// Returns an I/O error for length or payload reads,
231 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
232 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
233 /// is not valid UTF-8.
234 fn read_string_with_u32_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String>;
235
236 /// Reads a UTF-8 string with a big-endian `u32` byte-length prefix.
237 ///
238 /// # Parameters
239 ///
240 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
241 ///
242 /// # Returns
243 ///
244 /// The decoded string.
245 ///
246 /// # Errors
247 ///
248 /// Returns an I/O error for length or payload reads,
249 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
250 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
251 /// is not valid UTF-8.
252 fn read_string_with_u32_len_be(&mut self, max_len: usize) -> Result<String>;
253
254 /// Reads a UTF-8 string with a little-endian `u32` byte-length prefix.
255 ///
256 /// # Parameters
257 ///
258 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
259 ///
260 /// # Returns
261 ///
262 /// The decoded string.
263 ///
264 /// # Errors
265 ///
266 /// Returns an I/O error for length or payload reads,
267 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
268 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
269 /// is not valid UTF-8.
270 fn read_string_with_u32_len_le(&mut self, max_len: usize) -> Result<String>;
271}
272
273impl<T> StringReadExt for T
274where
275 T: Input<Item = u8> + ?Sized,
276{
277 #[inline]
278 fn read_utf8_payload_into(&mut self, bytes: &mut Vec<u8>, len: usize, max_len: usize) -> Result<()> {
279 read_utf8_payload_into_impl(self, bytes, len, max_len)
280 }
281
282 #[inline]
283 fn read_utf8_payload(&mut self, len: usize, max_len: usize) -> Result<String> {
284 read_utf8_payload_impl(self, len, max_len)
285 }
286
287 #[inline]
288 fn read_utf8_string_uleb_usize(&mut self, max_len: usize) -> Result<String> {
289 let len = self.read_uleb_usize_non_strict()?;
290 read_utf8_payload_impl(self, len, max_len)
291 }
292
293 #[inline]
294 fn read_utf8_string_uleb_usize_strict(&mut self, max_len: usize) -> Result<String> {
295 let len = self.read_uleb_usize_strict()?;
296 read_utf8_payload_impl(self, len, max_len)
297 }
298
299 #[inline]
300 fn read_utf8_string_uleb_u64(&mut self, max_len: usize) -> Result<String> {
301 let len = self.read_uleb_u64_non_strict()?;
302 #[cfg(target_pointer_width = "64")]
303 let len = len as usize;
304 #[cfg(not(target_pointer_width = "64"))]
305 let len = usize_from_u64_len(len)?;
306 read_utf8_payload_impl(self, len, max_len)
307 }
308
309 #[inline]
310 fn read_utf8_string_uleb_u64_strict(&mut self, max_len: usize) -> Result<String> {
311 let len = self.read_uleb_u64_strict()?;
312 #[cfg(target_pointer_width = "64")]
313 let len = len as usize;
314 #[cfg(not(target_pointer_width = "64"))]
315 let len = usize_from_u64_len(len)?;
316 read_utf8_payload_impl(self, len, max_len)
317 }
318
319 #[inline]
320 fn read_string_with_u16_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String> {
321 let len = usize::from(self.read_u16(byte_order)?);
322 read_utf8_payload_impl(self, len, max_len)
323 }
324
325 #[inline]
326 fn read_string_with_u16_len_be(&mut self, max_len: usize) -> Result<String> {
327 let len = self.read_u16_be()? as usize;
328 read_utf8_payload_impl(self, len, max_len)
329 }
330
331 #[inline]
332 fn read_string_with_u16_len_le(&mut self, max_len: usize) -> Result<String> {
333 let len = self.read_u16_le()? as usize;
334 read_utf8_payload_impl(self, len, max_len)
335 }
336
337 #[inline]
338 fn read_string_with_u32_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String> {
339 let len = self.read_u32(byte_order)?;
340 #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
341 let len = len as usize;
342 #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
343 let len = usize_from_u32_len(len)?;
344 read_utf8_payload_impl(self, len, max_len)
345 }
346
347 #[inline]
348 fn read_string_with_u32_len_be(&mut self, max_len: usize) -> Result<String> {
349 let len = self.read_u32_be()?;
350 #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
351 let len = len as usize;
352 #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
353 let len = usize_from_u32_len(len)?;
354 read_utf8_payload_impl(self, len, max_len)
355 }
356
357 #[inline]
358 fn read_string_with_u32_len_le(&mut self, max_len: usize) -> Result<String> {
359 let len = self.read_u32_le()?;
360 #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
361 let len = len as usize;
362 #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
363 let len = usize_from_u32_len(len)?;
364 read_utf8_payload_impl(self, len, max_len)
365 }
366}