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