Skip to main content

qubit_io_binary/ext/
async_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//! Asynchronous ZigZag reads.
9
10use core::future::Future;
11use std::io::Result;
12
13use qubit_codec_binary::NonStrict;
14use qubit_codec_binary::Strict;
15use qubit_codec_binary::ZigZagCodec;
16use qubit_io::AsyncInput;
17
18use crate::util::read_leb128_payload_async;
19
20macro_rules! zig_zag_read_method {
21    ($doc:literal, $name:ident, $ty:ty, $policy:ty) => {
22        #[doc = $doc]
23        #[doc = ""]
24        #[doc = "# Returns"]
25        #[doc = ""]
26        #[doc = concat!("Returns the decoded `", stringify!($ty), "`.")]
27        #[doc = ""]
28        #[doc = "# Errors"]
29        #[doc = ""]
30        #[doc = "Returns an input error or an invalid-data error when the \
31                 payload is malformed or violates the selected policy."]
32        #[doc = ""]
33        #[doc = "# Cancellation safety"]
34        #[doc = ""]
35        #[doc = "This operation is not cancellation safe. Dropping the future \
36                 retains any bytes already consumed from the input."]
37        #[inline(always)]
38        fn $name(&mut self) -> impl Future<Output = Result<$ty>> + '_
39        where
40            Self: Unpin,
41        {
42            async move {
43                read_leb128_payload_async::<
44                    { ZigZagCodec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
45                    ZigZagCodec<$ty, $policy>,
46                    _,
47                >(self)
48                .await
49            }
50        }
51    };
52}
53
54/// Future-based ZigZag plus unsigned-LEB128 reads.
55///
56/// # Cancellation safety
57///
58/// These reads are not cancellation safe. Dropping a pending future leaves
59/// bytes already consumed from the input consumed.
60///
61/// # Examples
62///
63/// ```
64/// use qubit_io_binary::AsyncZigZagReadExt;
65///
66/// async fn read_i32<R>(input: &mut R) -> std::io::Result<i32>
67/// where
68///     R: AsyncZigZagReadExt + Unpin,
69/// {
70///     input.read_zig_zag_i32_strict_async().await
71/// }
72/// ```
73pub trait AsyncZigZagReadExt: AsyncInput<Item = u8> {
74    zig_zag_read_method!(
75        "Asynchronously reads non-strict ZigZag `i8`.",
76        read_zig_zag_i8_non_strict_async,
77        i8,
78        NonStrict
79    );
80    zig_zag_read_method!(
81        "Asynchronously reads strict ZigZag `i8`.",
82        read_zig_zag_i8_strict_async,
83        i8,
84        Strict
85    );
86    zig_zag_read_method!(
87        "Asynchronously reads non-strict ZigZag `i16`.",
88        read_zig_zag_i16_non_strict_async,
89        i16,
90        NonStrict
91    );
92    zig_zag_read_method!(
93        "Asynchronously reads strict ZigZag `i16`.",
94        read_zig_zag_i16_strict_async,
95        i16,
96        Strict
97    );
98    zig_zag_read_method!(
99        "Asynchronously reads non-strict ZigZag `i32`.",
100        read_zig_zag_i32_non_strict_async,
101        i32,
102        NonStrict
103    );
104    zig_zag_read_method!(
105        "Asynchronously reads strict ZigZag `i32`.",
106        read_zig_zag_i32_strict_async,
107        i32,
108        Strict
109    );
110    zig_zag_read_method!(
111        "Asynchronously reads non-strict ZigZag `i64`.",
112        read_zig_zag_i64_non_strict_async,
113        i64,
114        NonStrict
115    );
116    zig_zag_read_method!(
117        "Asynchronously reads strict ZigZag `i64`.",
118        read_zig_zag_i64_strict_async,
119        i64,
120        Strict
121    );
122    zig_zag_read_method!(
123        "Asynchronously reads non-strict ZigZag `i128`.",
124        read_zig_zag_i128_non_strict_async,
125        i128,
126        NonStrict
127    );
128    zig_zag_read_method!(
129        "Asynchronously reads strict ZigZag `i128`.",
130        read_zig_zag_i128_strict_async,
131        i128,
132        Strict
133    );
134    zig_zag_read_method!(
135        "Asynchronously reads non-strict ZigZag `isize`.",
136        read_zig_zag_isize_non_strict_async,
137        isize,
138        NonStrict
139    );
140    zig_zag_read_method!(
141        "Asynchronously reads strict ZigZag `isize`.",
142        read_zig_zag_isize_strict_async,
143        isize,
144        Strict
145    );
146}
147
148impl<R> AsyncZigZagReadExt for R where R: AsyncInput<Item = u8> + ?Sized {}