Skip to main content

qubit_io_binary/ext/
zig_zag_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    NonStrict,
14    Strict,
15    ZigZagCodec,
16};
17use qubit_io::Input;
18
19macro_rules! read_zig_zag_value {
20    ($reader:expr, $ty:ty, $policy:ty) => {
21        read_leb128_payload::<
22            { ZigZagCodec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
23            ZigZagCodec<$ty, $policy>,
24            _,
25        >($reader)
26    };
27}
28
29/// Extension methods for reading ZigZag + unsigned LEB128 integers.
30///
31/// # Target-width integers
32///
33/// `isize` methods use the current Rust target's pointer width. Prefer
34/// fixed-width integer methods such as [`Self::read_zig_zag_i64_non_strict`]
35/// for persistent files and cross-platform protocols.
36/// Non-strict methods use the `_non_strict` suffix; canonical-only methods use
37/// the corresponding `_strict` suffix.
38pub trait ZigZagReadExt: Input<Item = u8> {
39    /// Reads a non-strict ZigZag `i8`.
40    ///
41    /// # Returns
42    ///
43    /// Returns the decoded integer.
44    ///
45    /// # Errors
46    ///
47    /// Returns an input error or an invalid-data error when the payload is
48    /// malformed or violates the selected canonicality policy.
49    #[inline(always)]
50    fn read_zig_zag_i8_non_strict(&mut self) -> Result<i8> {
51        read_zig_zag_value!(self, i8, NonStrict)
52    }
53
54    /// Reads a strict ZigZag `i8`.
55    ///
56    /// # Returns
57    ///
58    /// Returns the decoded integer.
59    ///
60    /// # Errors
61    ///
62    /// Returns an input error or an invalid-data error when the payload is
63    /// malformed or violates the selected canonicality policy.
64    #[inline(always)]
65    fn read_zig_zag_i8_strict(&mut self) -> Result<i8> {
66        read_zig_zag_value!(self, i8, Strict)
67    }
68
69    /// Reads a non-strict ZigZag `i16`.
70    ///
71    /// # Returns
72    ///
73    /// Returns the decoded integer.
74    ///
75    /// # Errors
76    ///
77    /// Returns an input error or an invalid-data error when the payload is
78    /// malformed or violates the selected canonicality policy.
79    #[inline(always)]
80    fn read_zig_zag_i16_non_strict(&mut self) -> Result<i16> {
81        read_zig_zag_value!(self, i16, NonStrict)
82    }
83
84    /// Reads a strict ZigZag `i16`.
85    ///
86    /// # Returns
87    ///
88    /// Returns the decoded integer.
89    ///
90    /// # Errors
91    ///
92    /// Returns an input error or an invalid-data error when the payload is
93    /// malformed or violates the selected canonicality policy.
94    #[inline(always)]
95    fn read_zig_zag_i16_strict(&mut self) -> Result<i16> {
96        read_zig_zag_value!(self, i16, Strict)
97    }
98
99    /// Reads a non-strict ZigZag `i32`.
100    ///
101    /// # Returns
102    ///
103    /// Returns the decoded integer.
104    ///
105    /// # Errors
106    ///
107    /// Returns an input error or an invalid-data error when the payload is
108    /// malformed or violates the selected canonicality policy.
109    #[inline(always)]
110    fn read_zig_zag_i32_non_strict(&mut self) -> Result<i32> {
111        read_zig_zag_value!(self, i32, NonStrict)
112    }
113
114    /// Reads a strict ZigZag `i32`.
115    ///
116    /// # Returns
117    ///
118    /// Returns the decoded integer.
119    ///
120    /// # Errors
121    ///
122    /// Returns an input error or an invalid-data error when the payload is
123    /// malformed or violates the selected canonicality policy.
124    #[inline(always)]
125    fn read_zig_zag_i32_strict(&mut self) -> Result<i32> {
126        read_zig_zag_value!(self, i32, Strict)
127    }
128
129    /// Reads a non-strict ZigZag `i64`.
130    ///
131    /// # Returns
132    ///
133    /// Returns the decoded integer.
134    ///
135    /// # Errors
136    ///
137    /// Returns an input error or an invalid-data error when the payload is
138    /// malformed or violates the selected canonicality policy.
139    #[inline(always)]
140    fn read_zig_zag_i64_non_strict(&mut self) -> Result<i64> {
141        read_zig_zag_value!(self, i64, NonStrict)
142    }
143
144    /// Reads a strict ZigZag `i64`.
145    ///
146    /// # Returns
147    ///
148    /// Returns the decoded integer.
149    ///
150    /// # Errors
151    ///
152    /// Returns an input error or an invalid-data error when the payload is
153    /// malformed or violates the selected canonicality policy.
154    #[inline(always)]
155    fn read_zig_zag_i64_strict(&mut self) -> Result<i64> {
156        read_zig_zag_value!(self, i64, Strict)
157    }
158
159    /// Reads a non-strict ZigZag `i128`.
160    ///
161    /// # Returns
162    ///
163    /// Returns the decoded integer.
164    ///
165    /// # Errors
166    ///
167    /// Returns an input error or an invalid-data error when the payload is
168    /// malformed or violates the selected canonicality policy.
169    #[inline(always)]
170    fn read_zig_zag_i128_non_strict(&mut self) -> Result<i128> {
171        read_zig_zag_value!(self, i128, NonStrict)
172    }
173
174    /// Reads a strict ZigZag `i128`.
175    ///
176    /// # Returns
177    ///
178    /// Returns the decoded integer.
179    ///
180    /// # Errors
181    ///
182    /// Returns an input error or an invalid-data error when the payload is
183    /// malformed or violates the selected canonicality policy.
184    #[inline(always)]
185    fn read_zig_zag_i128_strict(&mut self) -> Result<i128> {
186        read_zig_zag_value!(self, i128, Strict)
187    }
188
189    /// Reads a non-strict ZigZag `isize`.
190    ///
191    /// # Returns
192    ///
193    /// Returns the decoded integer.
194    ///
195    /// # Errors
196    ///
197    /// Returns an input error or an invalid-data error when the payload is
198    /// malformed or violates the selected canonicality policy.
199    #[inline(always)]
200    fn read_zig_zag_isize_non_strict(&mut self) -> Result<isize> {
201        read_zig_zag_value!(self, isize, NonStrict)
202    }
203
204    /// Reads a strict ZigZag `isize`.
205    ///
206    /// # Returns
207    ///
208    /// Returns the decoded integer.
209    ///
210    /// # Errors
211    ///
212    /// Returns an input error or an invalid-data error when the payload is
213    /// malformed or violates the selected canonicality policy.
214    #[inline(always)]
215    fn read_zig_zag_isize_strict(&mut self) -> Result<isize> {
216        read_zig_zag_value!(self, isize, Strict)
217    }
218}
219
220impl<R> ZigZagReadExt for R where R: Input<Item = u8> + ?Sized {}