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::ByteInput;
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.
28///
29/// A length-prefixed read is not transactional. If the decoded length exceeds
30/// max_len, the prefix is consumed but the payload is left unread. If UTF-8
31/// validation fails, both the prefix and the complete payload are consumed.
32/// Do not continue parsing the same record from the current position.
33///
34/// # Examples
35///
36/// Read a length-prefixed string and observe that an oversized length consumes
37/// its prefix while leaving the payload unread:
38///
39/// ```
40/// use std::io::Cursor;
41/// use std::io::ErrorKind;
42/// use qubit_io_binary::StringReadExt;
43///
44/// let mut input = Cursor::new([3, b'a', b'b', b'c']);
45/// assert_eq!(input.read_utf8_string_uleb_u64_strict(3)?, "abc");
46/// let mut oversized = Cursor::new([3, b'a', b'b', b'c']);
47/// assert_eq!(oversized.read_utf8_string_uleb_u64_strict(2).unwrap_err().kind(), ErrorKind::InvalidData);
48/// assert_eq!(oversized.position(), 1);
49/// # Ok::<(), std::io::Error>(())
50/// ```
51pub trait StringReadExt: ByteInput {
52 /// Reads and validates a UTF-8 payload into reusable byte storage.
53 ///
54 /// # Parameters
55 ///
56 /// - `bytes`: Reusable destination buffer. It is cleared before a permitted
57 /// read and contains the received bytes when the read succeeds or when
58 /// UTF-8 validation fails.
59 /// - `len`: UTF-8 payload length in bytes.
60 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
61 ///
62 /// If `len` exceeds `max_len`, `bytes` is left unchanged. Once the length
63 /// is accepted, its previous contents may be cleared even if allocation or
64 /// reading fails. After an I/O error, `bytes` is not a complete payload:
65 /// its length does not report how many bytes were received, and it may
66 /// contain zero-filled bytes that were never read. Invalid UTF-8 is
67 /// reported only after the complete payload has been received, so all
68 /// payload bytes remain available in `bytes` for diagnostics.
69 ///
70 /// # Returns
71 ///
72 /// Returns after `bytes` contains one valid UTF-8 payload.
73 ///
74 /// # Errors
75 ///
76 /// Returns an I/O error for payload reads or allocation failures, or
77 /// [`std::io::ErrorKind::InvalidData`] when `len` exceeds `max_len` or
78 /// the payload is not valid UTF-8.
79 fn read_utf8_payload_into(&mut self, bytes: &mut Vec<u8>, len: usize, max_len: usize) -> Result<()>;
80
81 /// Reads a UTF-8 payload with an already decoded byte length.
82 ///
83 /// # Parameters
84 ///
85 /// - `len`: UTF-8 payload length in bytes.
86 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
87 ///
88 /// # Returns
89 ///
90 /// The decoded string.
91 ///
92 /// # Errors
93 ///
94 /// Returns an I/O error for payload reads,
95 /// [`std::io::ErrorKind::InvalidData`] when `len` exceeds `max_len`, or
96 /// [`std::io::ErrorKind::InvalidData`] when the payload is not valid
97 /// UTF-8.
98 fn read_utf8_payload(&mut self, len: usize, max_len: usize) -> Result<String>;
99
100 /// Reads a UTF-8 string with an unsigned LEB128 byte-length prefix.
101 ///
102 /// The length prefix is decoded as `usize`, so this format is target-width
103 /// dependent. Prefer `u16` or `u32` length-prefix methods for persistent
104 /// files and cross-platform protocols.
105 ///
106 /// # Parameters
107 ///
108 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
109 ///
110 /// # Returns
111 ///
112 /// The decoded string.
113 ///
114 /// # Errors
115 ///
116 /// Returns an I/O error for length or payload reads,
117 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
118 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
119 /// is not valid UTF-8.
120 fn read_utf8_string_uleb_usize(&mut self, max_len: usize) -> Result<String>;
121
122 /// Reads a UTF-8 string with a canonical unsigned LEB128 byte-length
123 /// prefix.
124 ///
125 /// The length prefix is decoded as `usize`, so this format is target-width
126 /// dependent. Prefer `u16` or `u32` length-prefix methods for persistent
127 /// files and cross-platform protocols.
128 ///
129 /// # Parameters
130 ///
131 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
132 ///
133 /// # Returns
134 ///
135 /// The decoded string.
136 ///
137 /// # Errors
138 ///
139 /// Returns an I/O error for length or payload reads,
140 /// [`std::io::ErrorKind::InvalidData`] when the length prefix is
141 /// malformed or non-canonical, [`std::io::ErrorKind::InvalidData`] when
142 /// the encoded length exceeds `max_len`, or
143 /// [`std::io::ErrorKind::InvalidData`] when the payload is not valid
144 /// UTF-8.
145 fn read_utf8_string_uleb_usize_strict(&mut self, max_len: usize) -> Result<String>;
146
147 /// Reads a UTF-8 string with an unsigned LEB128 `u64` byte-length prefix.
148 ///
149 /// Prefer this method over [`Self::read_utf8_string_uleb_usize`] for
150 /// persistent files and cross-platform protocols because the length
151 /// field is independent of the current Rust target's pointer width.
152 ///
153 /// # Parameters
154 ///
155 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
156 ///
157 /// # Returns
158 ///
159 /// The decoded string.
160 ///
161 /// # Errors
162 ///
163 /// Returns an I/O error for length or payload reads,
164 /// [`std::io::ErrorKind::InvalidData`] when the encoded `u64` length
165 /// does not fit the local `usize`, when the encoded length exceeds
166 /// `max_len`, or when the payload is not valid UTF-8.
167 fn read_utf8_string_uleb_u64(&mut self, max_len: usize) -> Result<String>;
168
169 /// Reads a UTF-8 string with a canonical unsigned LEB128 `u64` byte-length
170 /// prefix.
171 ///
172 /// Prefer this method over [`Self::read_utf8_string_uleb_usize_strict`] for
173 /// persistent files and cross-platform protocols because the length field
174 /// is independent of the current Rust target's pointer width.
175 ///
176 /// # Parameters
177 ///
178 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
179 ///
180 /// # Returns
181 ///
182 /// The decoded string.
183 ///
184 /// # Errors
185 ///
186 /// Returns an I/O error for length or payload reads,
187 /// [`std::io::ErrorKind::InvalidData`] when the length prefix is
188 /// malformed or non-canonical, when the encoded `u64` length does not
189 /// fit the local `usize`, when the encoded length exceeds `max_len`, or
190 /// when the payload is not valid UTF-8.
191 fn read_utf8_string_uleb_u64_strict(&mut self, max_len: usize) -> Result<String>;
192
193 /// Reads a UTF-8 string with a runtime-order `u16` byte-length prefix.
194 ///
195 /// # Parameters
196 ///
197 /// - `byte_order`: Byte order used by the length prefix.
198 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
199 ///
200 /// # Returns
201 ///
202 /// The decoded string.
203 ///
204 /// # Errors
205 ///
206 /// Returns an I/O error for length or payload reads,
207 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
208 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
209 /// is not valid UTF-8.
210 fn read_string_with_u16_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String>;
211
212 /// Reads a UTF-8 string with a big-endian `u16` byte-length prefix.
213 ///
214 /// # Parameters
215 ///
216 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
217 ///
218 /// # Returns
219 ///
220 /// The decoded string.
221 ///
222 /// # Errors
223 ///
224 /// Returns an I/O error for length or payload reads,
225 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
226 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
227 /// is not valid UTF-8.
228 fn read_string_with_u16_len_be(&mut self, max_len: usize) -> Result<String>;
229
230 /// Reads a UTF-8 string with a little-endian `u16` byte-length prefix.
231 ///
232 /// # Parameters
233 ///
234 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
235 ///
236 /// # Returns
237 ///
238 /// The decoded string.
239 ///
240 /// # Errors
241 ///
242 /// Returns an I/O error for length or payload reads,
243 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
244 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
245 /// is not valid UTF-8.
246 fn read_string_with_u16_len_le(&mut self, max_len: usize) -> Result<String>;
247
248 /// Reads a UTF-8 string with a runtime-order `u32` byte-length prefix.
249 ///
250 /// # Parameters
251 ///
252 /// - `byte_order`: Byte order used by the length prefix.
253 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
254 ///
255 /// # Returns
256 ///
257 /// The decoded string.
258 ///
259 /// # Errors
260 ///
261 /// Returns an I/O error for length or payload reads,
262 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
263 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
264 /// is not valid UTF-8.
265 fn read_string_with_u32_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String>;
266
267 /// Reads a UTF-8 string with a big-endian `u32` byte-length prefix.
268 ///
269 /// # Parameters
270 ///
271 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
272 ///
273 /// # Returns
274 ///
275 /// The decoded string.
276 ///
277 /// # Errors
278 ///
279 /// Returns an I/O error for length or payload reads,
280 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
281 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
282 /// is not valid UTF-8.
283 fn read_string_with_u32_len_be(&mut self, max_len: usize) -> Result<String>;
284
285 /// Reads a UTF-8 string with a little-endian `u32` byte-length prefix.
286 ///
287 /// # Parameters
288 ///
289 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
290 ///
291 /// # Returns
292 ///
293 /// The decoded string.
294 ///
295 /// # Errors
296 ///
297 /// Returns an I/O error for length or payload reads,
298 /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
299 /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
300 /// is not valid UTF-8.
301 fn read_string_with_u32_len_le(&mut self, max_len: usize) -> Result<String>;
302}
303
304impl<T> StringReadExt for T
305where
306 T: ByteInput + ?Sized,
307{
308 /// Reads a validated UTF-8 payload into the caller's reusable byte buffer.
309 ///
310 /// The buffer contents and error behavior follow the contract documented
311 /// on [`StringReadExt::read_utf8_payload_into`].
312 ///
313 /// # Parameters
314 ///
315 /// - `bytes`: Reusable destination buffer for the received payload.
316 /// - `len`: UTF-8 payload length in bytes.
317 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
318 #[inline]
319 fn read_utf8_payload_into(&mut self, bytes: &mut Vec<u8>, len: usize, max_len: usize) -> Result<()> {
320 read_utf8_payload_into_impl(self, bytes, len, max_len)
321 }
322
323 /// Reads and validates a UTF-8 payload whose byte length is already known.
324 ///
325 /// Length limits and input-consumption behavior follow the contract
326 /// documented on [`StringReadExt::read_utf8_payload`].
327 ///
328 /// # Parameters
329 ///
330 /// - `len`: UTF-8 payload length in bytes.
331 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
332 #[inline]
333 fn read_utf8_payload(&mut self, len: usize, max_len: usize) -> Result<String> {
334 read_utf8_payload_impl(self, len, max_len)
335 }
336
337 /// Decodes a non-strict `usize` ULEB128 length and reads that UTF-8
338 /// payload.
339 ///
340 /// # Parameters
341 ///
342 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
343 #[inline]
344 fn read_utf8_string_uleb_usize(&mut self, max_len: usize) -> Result<String> {
345 let len = self.read_uleb_usize_non_strict()?;
346 read_utf8_payload_impl(self, len, max_len)
347 }
348
349 /// Decodes a canonical `usize` ULEB128 length and reads that UTF-8 payload.
350 ///
351 /// # Parameters
352 ///
353 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
354 #[inline]
355 fn read_utf8_string_uleb_usize_strict(&mut self, max_len: usize) -> Result<String> {
356 let len = self.read_uleb_usize_strict()?;
357 read_utf8_payload_impl(self, len, max_len)
358 }
359
360 /// Decodes a non-strict `u64` ULEB128 length and reads that UTF-8 payload.
361 ///
362 /// Returns an invalid-data error if the length cannot fit in `usize`.
363 ///
364 /// # Parameters
365 ///
366 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
367 #[inline]
368 fn read_utf8_string_uleb_u64(&mut self, max_len: usize) -> Result<String> {
369 let len = self.read_uleb_u64_non_strict()?;
370 #[cfg(target_pointer_width = "64")]
371 let len = len as usize;
372 #[cfg(not(target_pointer_width = "64"))]
373 let len = usize_from_u64_len(len)?;
374 read_utf8_payload_impl(self, len, max_len)
375 }
376
377 /// Decodes a canonical `u64` ULEB128 length and reads that UTF-8 payload.
378 ///
379 /// Returns an invalid-data error for a malformed prefix or a length that
380 /// cannot fit in `usize`.
381 ///
382 /// # Parameters
383 ///
384 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
385 #[inline]
386 fn read_utf8_string_uleb_u64_strict(&mut self, max_len: usize) -> Result<String> {
387 let len = self.read_uleb_u64_strict()?;
388 #[cfg(target_pointer_width = "64")]
389 let len = len as usize;
390 #[cfg(not(target_pointer_width = "64"))]
391 let len = usize_from_u64_len(len)?;
392 read_utf8_payload_impl(self, len, max_len)
393 }
394
395 /// Reads a UTF-8 payload preceded by a `u16` length in the selected byte
396 /// order.
397 ///
398 /// # Parameters
399 ///
400 /// - `byte_order`: Byte order used by the length prefix.
401 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
402 #[inline]
403 fn read_string_with_u16_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String> {
404 let len = usize::from(self.read_u16(byte_order)?);
405 read_utf8_payload_impl(self, len, max_len)
406 }
407
408 /// Reads a UTF-8 payload preceded by a big-endian `u16` length.
409 ///
410 /// # Parameters
411 ///
412 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
413 #[inline]
414 fn read_string_with_u16_len_be(&mut self, max_len: usize) -> Result<String> {
415 let len = self.read_u16_be()? as usize;
416 read_utf8_payload_impl(self, len, max_len)
417 }
418
419 /// Reads a UTF-8 payload preceded by a little-endian `u16` length.
420 ///
421 /// # Parameters
422 ///
423 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
424 #[inline]
425 fn read_string_with_u16_len_le(&mut self, max_len: usize) -> Result<String> {
426 let len = self.read_u16_le()? as usize;
427 read_utf8_payload_impl(self, len, max_len)
428 }
429
430 /// Reads a UTF-8 payload preceded by a `u32` length in the selected byte
431 /// order.
432 ///
433 /// # Parameters
434 ///
435 /// - `byte_order`: Byte order used by the length prefix.
436 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
437 #[inline]
438 fn read_string_with_u32_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String> {
439 let len = self.read_u32(byte_order)?;
440 #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
441 let len = len as usize;
442 #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
443 let len = usize_from_u32_len(len)?;
444 read_utf8_payload_impl(self, len, max_len)
445 }
446
447 /// Reads a UTF-8 payload preceded by a big-endian `u32` length.
448 ///
449 /// # Parameters
450 ///
451 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
452 #[inline]
453 fn read_string_with_u32_len_be(&mut self, max_len: usize) -> Result<String> {
454 let len = self.read_u32_be()?;
455 #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
456 let len = len as usize;
457 #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
458 let len = usize_from_u32_len(len)?;
459 read_utf8_payload_impl(self, len, max_len)
460 }
461
462 /// Reads a UTF-8 payload preceded by a little-endian `u32` length.
463 ///
464 /// # Parameters
465 ///
466 /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
467 #[inline]
468 fn read_string_with_u32_len_le(&mut self, max_len: usize) -> Result<String> {
469 let len = self.read_u32_le()?;
470 #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
471 let len = len as usize;
472 #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
473 let len = usize_from_u32_len(len)?;
474 read_utf8_payload_impl(self, len, max_len)
475 }
476}