zrx_stream/stream/combinator/tuple/
join.rs

1// Copyright (c) 2025-2026 Zensical and contributors
2
3// SPDX-License-Identifier: MIT
4// All contributions are certified under the DCO
5
6// Permission is hereby granted, free of charge, to any person obtaining a copy
7// of this software and associated documentation files (the "Software"), to
8// deal in the Software without restriction, including without limitation the
9// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10// sell copies of the Software, and to permit persons to whom the Software is
11// furnished to do so, subject to the following conditions:
12
13// The above copyright notice and this permission notice shall be included in
14// all copies or substantial portions of the Software.
15
16// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
19// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22// IN THE SOFTWARE.
23
24// ----------------------------------------------------------------------------
25
26//! Stream tuple join.
27
28use crate::stream::combinator::StreamTuple;
29use crate::stream::value::tuple::{All, Any, First, Presence};
30use crate::stream::value::Tuple;
31use crate::stream::Stream;
32
33mod convert;
34
35pub use convert::*;
36
37// ----------------------------------------------------------------------------
38// Traits
39// ----------------------------------------------------------------------------
40
41/// Stream tuple join.
42///
43/// Stream tuples are heterogeneous collections of streams, which is why they
44/// are the natural choice to represent joins. This trait is implemented for
45/// tuples of streams in sizes of 1 to 8, and is further specialized with the
46/// [`Presence`] markers to implement the following join strategies:
47///
48/// - [`All`]: All items are required (inner join).
49/// - [`First`]: Only the first item is required (left join).
50/// - [`Any`]: All items are optional (outer join)
51///
52/// Extensions of this trait include:
53///
54/// - [`IntoJoin`]
55/// - [`IntoJoinFilter`]
56/// - [`IntoJoinFilterMap`]
57/// - [`IntoJoinMap`]
58///
59/// Keeping the concretization of tuples of sizes 1 to 8 together with presence
60/// markers in this base trait allows to keep the join implementations focused.
61pub trait StreamTupleJoin<I, P>: StreamTuple<I>
62where
63    P: Presence,
64{
65    /// Item type.
66    type Item: Tuple<P>;
67}
68
69// ----------------------------------------------------------------------------
70// Macros
71// ----------------------------------------------------------------------------
72
73/// Implements stream join trait with all items required.
74macro_rules! impl_stream_join_all {
75    ($($T:ident),+ $(,)?) => {
76        impl<I, $($T),+> StreamTupleJoin<I, All>
77            for ($(Stream<I, $T>,)+)
78        where
79            ($($T,)+): Tuple<All>,
80        {
81            type Item = ($($T,)+);
82        }
83    };
84}
85
86/// Implements stream join trait with first item required.
87macro_rules! impl_stream_join_first {
88    ($T1:ident $(, $T:ident)* $(,)?) => {
89        impl<I, $T1 $(, $T)*> StreamTupleJoin<I, First>
90            for (Stream<I, $T1>, $(Stream<I, $T>),*)
91        where
92            ($T1, $(Option<$T>),*): Tuple<First>,
93        {
94            type Item = ($T1, $(Option<$T>),*);
95        }
96    };
97}
98
99/// Implements stream join trait with all items optional.
100macro_rules! impl_stream_join_any {
101    ($($T:ident),+ $(,)?) => {
102        impl<I, $($T),+> StreamTupleJoin<I, Any>
103            for ($(Stream<I, $T>,)+)
104        where
105            ($(Option<$T>,)+): Tuple<Any>,
106        {
107            type Item = ($(Option<$T>,)+);
108        }
109    };
110}
111
112/// Implements stream join traits.
113macro_rules! impl_stream_join {
114    ($($T:ident),+ $(,)?) => {
115        impl_stream_join_all!($($T),+);
116        impl_stream_join_first!($($T),+);
117        impl_stream_join_any!($($T),+);
118    };
119}
120
121// ----------------------------------------------------------------------------
122
123impl_stream_join!(T1);
124impl_stream_join!(T1, T2);
125impl_stream_join!(T1, T2, T3);
126impl_stream_join!(T1, T2, T3, T4);
127impl_stream_join!(T1, T2, T3, T4, T5);
128impl_stream_join!(T1, T2, T3, T4, T5, T6);
129impl_stream_join!(T1, T2, T3, T4, T5, T6, T7);
130impl_stream_join!(T1, T2, T3, T4, T5, T6, T7, T8);
zrx_stream/stream/combinator/tuple/join.rs

zrx_stream/stream/combinator/tuple/
join.rs
