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