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