Skip to main content

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}