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 {}