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