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}