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.
60pub trait AsyncZigZagReadExt: AsyncInput<Item = u8> {
61    zig_zag_read_method!(
62        "Asynchronously reads non-strict ZigZag `i8`.",
63        read_zig_zag_i8_non_strict_async,
64        i8,
65        NonStrict
66    );
67    zig_zag_read_method!(
68        "Asynchronously reads strict ZigZag `i8`.",
69        read_zig_zag_i8_strict_async,
70        i8,
71        Strict
72    );
73    zig_zag_read_method!(
74        "Asynchronously reads non-strict ZigZag `i16`.",
75        read_zig_zag_i16_non_strict_async,
76        i16,
77        NonStrict
78    );
79    zig_zag_read_method!(
80        "Asynchronously reads strict ZigZag `i16`.",
81        read_zig_zag_i16_strict_async,
82        i16,
83        Strict
84    );
85    zig_zag_read_method!(
86        "Asynchronously reads non-strict ZigZag `i32`.",
87        read_zig_zag_i32_non_strict_async,
88        i32,
89        NonStrict
90    );
91    zig_zag_read_method!(
92        "Asynchronously reads strict ZigZag `i32`.",
93        read_zig_zag_i32_strict_async,
94        i32,
95        Strict
96    );
97    zig_zag_read_method!(
98        "Asynchronously reads non-strict ZigZag `i64`.",
99        read_zig_zag_i64_non_strict_async,
100        i64,
101        NonStrict
102    );
103    zig_zag_read_method!(
104        "Asynchronously reads strict ZigZag `i64`.",
105        read_zig_zag_i64_strict_async,
106        i64,
107        Strict
108    );
109    zig_zag_read_method!(
110        "Asynchronously reads non-strict ZigZag `i128`.",
111        read_zig_zag_i128_non_strict_async,
112        i128,
113        NonStrict
114    );
115    zig_zag_read_method!(
116        "Asynchronously reads strict ZigZag `i128`.",
117        read_zig_zag_i128_strict_async,
118        i128,
119        Strict
120    );
121    zig_zag_read_method!(
122        "Asynchronously reads non-strict ZigZag `isize`.",
123        read_zig_zag_isize_non_strict_async,
124        isize,
125        NonStrict
126    );
127    zig_zag_read_method!(
128        "Asynchronously reads strict ZigZag `isize`.",
129        read_zig_zag_isize_strict_async,
130        isize,
131        Strict
132    );
133}
134
135impl<R> AsyncZigZagReadExt for R where R: AsyncInput<Item = u8> + ?Sized {}