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