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(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}