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
9//! Extension methods for decoding ZigZag-encoded integers from streams.
10
11use std::io::Result;
12
13use qubit_codec_binary::NonStrict;
14use qubit_codec_binary::Strict;
15use qubit_codec_binary::ZigZagCodec;
16use qubit_io::Input;
17
18use crate::util::read_leb128_payload;
19
20macro_rules! read_zig_zag_value {
21    ($reader:expr, $ty:ty, $policy:ty) => {
22        read_leb128_payload::<
23            { ZigZagCodec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
24            ZigZagCodec<$ty, $policy>,
25            _,
26        >($reader)
27    };
28}
29
30/// Extension methods for reading ZigZag + unsigned LEB128 integers.
31///
32/// # Target-width integers
33///
34/// `isize` methods use the current Rust target's pointer width. Prefer
35/// fixed-width integer methods such as [`Self::read_zig_zag_i64_non_strict`]
36/// for persistent files and cross-platform protocols.
37/// Non-strict methods use the `_non_strict` suffix; canonical-only methods use
38/// the corresponding `_strict` suffix.
39pub trait ZigZagReadExt: Input<Item = u8> {
40    /// Reads a non-strict ZigZag `i8`.
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_zig_zag_i8_non_strict(&mut self) -> Result<i8> {
52        read_zig_zag_value!(self, i8, NonStrict)
53    }
54
55    /// Reads a strict ZigZag `i8`.
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_zig_zag_i8_strict(&mut self) -> Result<i8> {
67        read_zig_zag_value!(self, i8, Strict)
68    }
69
70    /// Reads a non-strict ZigZag `i16`.
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_zig_zag_i16_non_strict(&mut self) -> Result<i16> {
82        read_zig_zag_value!(self, i16, NonStrict)
83    }
84
85    /// Reads a strict ZigZag `i16`.
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_zig_zag_i16_strict(&mut self) -> Result<i16> {
97        read_zig_zag_value!(self, i16, Strict)
98    }
99
100    /// Reads a non-strict ZigZag `i32`.
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_zig_zag_i32_non_strict(&mut self) -> Result<i32> {
112        read_zig_zag_value!(self, i32, NonStrict)
113    }
114
115    /// Reads a strict ZigZag `i32`.
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_zig_zag_i32_strict(&mut self) -> Result<i32> {
127        read_zig_zag_value!(self, i32, Strict)
128    }
129
130    /// Reads a non-strict ZigZag `i64`.
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_zig_zag_i64_non_strict(&mut self) -> Result<i64> {
142        read_zig_zag_value!(self, i64, NonStrict)
143    }
144
145    /// Reads a strict ZigZag `i64`.
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_zig_zag_i64_strict(&mut self) -> Result<i64> {
157        read_zig_zag_value!(self, i64, Strict)
158    }
159
160    /// Reads a non-strict ZigZag `i128`.
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_zig_zag_i128_non_strict(&mut self) -> Result<i128> {
172        read_zig_zag_value!(self, i128, NonStrict)
173    }
174
175    /// Reads a strict ZigZag `i128`.
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_zig_zag_i128_strict(&mut self) -> Result<i128> {
187        read_zig_zag_value!(self, i128, Strict)
188    }
189
190    /// Reads a non-strict ZigZag `isize`.
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_zig_zag_isize_non_strict(&mut self) -> Result<isize> {
202        read_zig_zag_value!(self, isize, NonStrict)
203    }
204
205    /// Reads a strict ZigZag `isize`.
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_zig_zag_isize_strict(&mut self) -> Result<isize> {
217        read_zig_zag_value!(self, isize, Strict)
218    }
219}
220
221impl<R> ZigZagReadExt for R where R: Input<Item = u8> + ?Sized {}