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