Skip to main content

qubit_io_binary/ext/
leb128_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
9//! Extension methods for decoding LEB128 values from byte streams.
10
11use std::io::Result;
12
13use qubit_codec_binary::Leb128Codec;
14use qubit_codec_binary::NonStrict;
15use qubit_codec_binary::Strict;
16use qubit_io::ByteInput;
17
18use crate::util::read_leb128_payload;
19
20macro_rules! read_leb128_value {
21    ($reader:expr, $ty:ty, $policy:ty) => {
22        read_leb128_payload::<
23            { Leb128Codec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
24            Leb128Codec<$ty, $policy>,
25            _,
26        >($reader)
27    };
28}
29
30/// Extension methods for reading LEB128 integers from byte streams.
31///
32/// # Target-width integers
33///
34/// `usize` and `isize` methods use the current Rust target's pointer width.
35/// Prefer fixed-width integer methods such as
36/// [`Self::read_uleb_u64_non_strict`] or [`Self::read_sleb_i64_non_strict`] for
37/// persistent files and cross-platform protocols. Non-strict methods use the
38/// `_non_strict` suffix; canonical-only methods use the corresponding `_strict`
39/// suffix.
40/// A failed synchronous read may have consumed part of the current value.
41/// Do not blindly retry the same operation; resume only from a framing
42/// boundary or a trusted seek checkpoint.
43///
44/// # Examples
45///
46/// A non-strict read accepts an overlong encoding that the strict method
47/// rejects:
48///
49/// ```
50/// use std::io::Cursor;
51/// use std::io::ErrorKind;
52/// use qubit_io_binary::Leb128ReadExt;
53///
54/// let mut permissive = Cursor::new([0x80, 0x00]);
55/// assert_eq!(permissive.read_uleb_u64_non_strict()?, 0);
56/// let mut strict = Cursor::new([0x80, 0x00]);
57/// assert_eq!(strict.read_uleb_u64_strict().unwrap_err().kind(), ErrorKind::InvalidData);
58/// # Ok::<(), std::io::Error>(())
59/// ```
60pub trait Leb128ReadExt: ByteInput {
61    /// Reads a non-strict unsigned LEB128 `u8`.
62    ///
63    /// # Returns
64    ///
65    /// Returns the decoded integer.
66    ///
67    /// # Errors
68    ///
69    /// Returns an input error or an invalid-data error when the payload is
70    /// malformed or violates the selected canonicality policy.
71    #[inline(always)]
72    fn read_uleb_u8_non_strict(&mut self) -> Result<u8> {
73        read_leb128_value!(self, u8, NonStrict)
74    }
75
76    /// Reads a strict unsigned LEB128 `u8`.
77    ///
78    /// # Returns
79    ///
80    /// Returns the decoded integer.
81    ///
82    /// # Errors
83    ///
84    /// Returns an input error or an invalid-data error when the payload is
85    /// malformed or violates the selected canonicality policy.
86    #[inline(always)]
87    fn read_uleb_u8_strict(&mut self) -> Result<u8> {
88        read_leb128_value!(self, u8, Strict)
89    }
90
91    /// Reads a non-strict unsigned LEB128 `u16`.
92    ///
93    /// # Returns
94    ///
95    /// Returns the decoded integer.
96    ///
97    /// # Errors
98    ///
99    /// Returns an input error or an invalid-data error when the payload is
100    /// malformed or violates the selected canonicality policy.
101    #[inline(always)]
102    fn read_uleb_u16_non_strict(&mut self) -> Result<u16> {
103        read_leb128_value!(self, u16, NonStrict)
104    }
105
106    /// Reads a strict unsigned LEB128 `u16`.
107    ///
108    /// # Returns
109    ///
110    /// Returns the decoded integer.
111    ///
112    /// # Errors
113    ///
114    /// Returns an input error or an invalid-data error when the payload is
115    /// malformed or violates the selected canonicality policy.
116    #[inline(always)]
117    fn read_uleb_u16_strict(&mut self) -> Result<u16> {
118        read_leb128_value!(self, u16, Strict)
119    }
120
121    /// Reads a non-strict unsigned LEB128 `u32`.
122    ///
123    /// # Returns
124    ///
125    /// Returns the decoded integer.
126    ///
127    /// # Errors
128    ///
129    /// Returns an input error or an invalid-data error when the payload is
130    /// malformed or violates the selected canonicality policy.
131    #[inline(always)]
132    fn read_uleb_u32_non_strict(&mut self) -> Result<u32> {
133        read_leb128_value!(self, u32, NonStrict)
134    }
135
136    /// Reads a strict unsigned LEB128 `u32`.
137    ///
138    /// # Returns
139    ///
140    /// Returns the decoded integer.
141    ///
142    /// # Errors
143    ///
144    /// Returns an input error or an invalid-data error when the payload is
145    /// malformed or violates the selected canonicality policy.
146    #[inline(always)]
147    fn read_uleb_u32_strict(&mut self) -> Result<u32> {
148        read_leb128_value!(self, u32, Strict)
149    }
150
151    /// Reads a non-strict unsigned LEB128 `u64`.
152    ///
153    /// # Returns
154    ///
155    /// Returns the decoded integer.
156    ///
157    /// # Errors
158    ///
159    /// Returns an input error or an invalid-data error when the payload is
160    /// malformed or violates the selected canonicality policy.
161    #[inline(always)]
162    fn read_uleb_u64_non_strict(&mut self) -> Result<u64> {
163        read_leb128_value!(self, u64, NonStrict)
164    }
165
166    /// Reads a strict unsigned LEB128 `u64`.
167    ///
168    /// # Returns
169    ///
170    /// Returns the decoded integer.
171    ///
172    /// # Errors
173    ///
174    /// Returns an input error or an invalid-data error when the payload is
175    /// malformed or violates the selected canonicality policy.
176    #[inline(always)]
177    fn read_uleb_u64_strict(&mut self) -> Result<u64> {
178        read_leb128_value!(self, u64, Strict)
179    }
180
181    /// Reads a non-strict unsigned LEB128 `u128`.
182    ///
183    /// # Returns
184    ///
185    /// Returns the decoded integer.
186    ///
187    /// # Errors
188    ///
189    /// Returns an input error or an invalid-data error when the payload is
190    /// malformed or violates the selected canonicality policy.
191    #[inline(always)]
192    fn read_uleb_u128_non_strict(&mut self) -> Result<u128> {
193        read_leb128_value!(self, u128, NonStrict)
194    }
195
196    /// Reads a strict unsigned LEB128 `u128`.
197    ///
198    /// # Returns
199    ///
200    /// Returns the decoded integer.
201    ///
202    /// # Errors
203    ///
204    /// Returns an input error or an invalid-data error when the payload is
205    /// malformed or violates the selected canonicality policy.
206    #[inline(always)]
207    fn read_uleb_u128_strict(&mut self) -> Result<u128> {
208        read_leb128_value!(self, u128, Strict)
209    }
210
211    /// Reads a non-strict unsigned LEB128 `usize`.
212    ///
213    /// # Returns
214    ///
215    /// Returns the decoded integer.
216    ///
217    /// # Errors
218    ///
219    /// Returns an input error or an invalid-data error when the payload is
220    /// malformed or violates the selected canonicality policy.
221    #[inline(always)]
222    fn read_uleb_usize_non_strict(&mut self) -> Result<usize> {
223        read_leb128_value!(self, usize, NonStrict)
224    }
225
226    /// Reads a strict unsigned LEB128 `usize`.
227    ///
228    /// # Returns
229    ///
230    /// Returns the decoded integer.
231    ///
232    /// # Errors
233    ///
234    /// Returns an input error or an invalid-data error when the payload is
235    /// malformed or violates the selected canonicality policy.
236    #[inline(always)]
237    fn read_uleb_usize_strict(&mut self) -> Result<usize> {
238        read_leb128_value!(self, usize, Strict)
239    }
240
241    /// Reads a non-strict signed LEB128 `i8`.
242    ///
243    /// # Returns
244    ///
245    /// Returns the decoded integer.
246    ///
247    /// # Errors
248    ///
249    /// Returns an input error or an invalid-data error when the payload is
250    /// malformed or violates the selected canonicality policy.
251    #[inline(always)]
252    fn read_sleb_i8_non_strict(&mut self) -> Result<i8> {
253        read_leb128_value!(self, i8, NonStrict)
254    }
255
256    /// Reads a strict signed LEB128 `i8`.
257    ///
258    /// # Returns
259    ///
260    /// Returns the decoded integer.
261    ///
262    /// # Errors
263    ///
264    /// Returns an input error or an invalid-data error when the payload is
265    /// malformed or violates the selected canonicality policy.
266    #[inline(always)]
267    fn read_sleb_i8_strict(&mut self) -> Result<i8> {
268        read_leb128_value!(self, i8, Strict)
269    }
270
271    /// Reads a non-strict signed LEB128 `i16`.
272    ///
273    /// # Returns
274    ///
275    /// Returns the decoded integer.
276    ///
277    /// # Errors
278    ///
279    /// Returns an input error or an invalid-data error when the payload is
280    /// malformed or violates the selected canonicality policy.
281    #[inline(always)]
282    fn read_sleb_i16_non_strict(&mut self) -> Result<i16> {
283        read_leb128_value!(self, i16, NonStrict)
284    }
285
286    /// Reads a strict signed LEB128 `i16`.
287    ///
288    /// # Returns
289    ///
290    /// Returns the decoded integer.
291    ///
292    /// # Errors
293    ///
294    /// Returns an input error or an invalid-data error when the payload is
295    /// malformed or violates the selected canonicality policy.
296    #[inline(always)]
297    fn read_sleb_i16_strict(&mut self) -> Result<i16> {
298        read_leb128_value!(self, i16, Strict)
299    }
300
301    /// Reads a non-strict signed LEB128 `i32`.
302    ///
303    /// # Returns
304    ///
305    /// Returns the decoded integer.
306    ///
307    /// # Errors
308    ///
309    /// Returns an input error or an invalid-data error when the payload is
310    /// malformed or violates the selected canonicality policy.
311    #[inline(always)]
312    fn read_sleb_i32_non_strict(&mut self) -> Result<i32> {
313        read_leb128_value!(self, i32, NonStrict)
314    }
315
316    /// Reads a strict signed LEB128 `i32`.
317    ///
318    /// # Returns
319    ///
320    /// Returns the decoded integer.
321    ///
322    /// # Errors
323    ///
324    /// Returns an input error or an invalid-data error when the payload is
325    /// malformed or violates the selected canonicality policy.
326    #[inline(always)]
327    fn read_sleb_i32_strict(&mut self) -> Result<i32> {
328        read_leb128_value!(self, i32, Strict)
329    }
330
331    /// Reads a non-strict signed LEB128 `i64`.
332    ///
333    /// # Returns
334    ///
335    /// Returns the decoded integer.
336    ///
337    /// # Errors
338    ///
339    /// Returns an input error or an invalid-data error when the payload is
340    /// malformed or violates the selected canonicality policy.
341    #[inline(always)]
342    fn read_sleb_i64_non_strict(&mut self) -> Result<i64> {
343        read_leb128_value!(self, i64, NonStrict)
344    }
345
346    /// Reads a strict signed LEB128 `i64`.
347    ///
348    /// # Returns
349    ///
350    /// Returns the decoded integer.
351    ///
352    /// # Errors
353    ///
354    /// Returns an input error or an invalid-data error when the payload is
355    /// malformed or violates the selected canonicality policy.
356    #[inline(always)]
357    fn read_sleb_i64_strict(&mut self) -> Result<i64> {
358        read_leb128_value!(self, i64, Strict)
359    }
360
361    /// Reads a non-strict signed LEB128 `i128`.
362    ///
363    /// # Returns
364    ///
365    /// Returns the decoded integer.
366    ///
367    /// # Errors
368    ///
369    /// Returns an input error or an invalid-data error when the payload is
370    /// malformed or violates the selected canonicality policy.
371    #[inline(always)]
372    fn read_sleb_i128_non_strict(&mut self) -> Result<i128> {
373        read_leb128_value!(self, i128, NonStrict)
374    }
375
376    /// Reads a strict signed LEB128 `i128`.
377    ///
378    /// # Returns
379    ///
380    /// Returns the decoded integer.
381    ///
382    /// # Errors
383    ///
384    /// Returns an input error or an invalid-data error when the payload is
385    /// malformed or violates the selected canonicality policy.
386    #[inline(always)]
387    fn read_sleb_i128_strict(&mut self) -> Result<i128> {
388        read_leb128_value!(self, i128, Strict)
389    }
390
391    /// Reads a non-strict signed LEB128 `isize`.
392    ///
393    /// # Returns
394    ///
395    /// Returns the decoded integer.
396    ///
397    /// # Errors
398    ///
399    /// Returns an input error or an invalid-data error when the payload is
400    /// malformed or violates the selected canonicality policy.
401    #[inline(always)]
402    fn read_sleb_isize_non_strict(&mut self) -> Result<isize> {
403        read_leb128_value!(self, isize, NonStrict)
404    }
405
406    /// Reads a strict signed LEB128 `isize`.
407    ///
408    /// # Returns
409    ///
410    /// Returns the decoded integer.
411    ///
412    /// # Errors
413    ///
414    /// Returns an input error or an invalid-data error when the payload is
415    /// malformed or violates the selected canonicality policy.
416    #[inline(always)]
417    fn read_sleb_isize_strict(&mut self) -> Result<isize> {
418        read_leb128_value!(self, isize, Strict)
419    }
420}
421
422impl<R> Leb128ReadExt for R where R: ByteInput + ?Sized {}