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