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