Skip to main content

solverforge_scoring/stream/joiner/
equal.rs

1//! Equal joiner for matching on property equality.
2
3use std::marker::PhantomData;
4
5use super::Joiner;
6
7/// Marker for same-source joins where each unordered pair is considered once.
8pub struct Symmetric;
9
10/// Marker for left/right joins where pair orientation is part of the semantics.
11pub struct Directed;
12
13/// Creates a joiner that matches when a property is equal on both sides.
14///
15/// This is the primary joiner for self-joins where you're matching
16/// entities from the same collection on a shared property.
17///
18/// # Example
19///
20/// ```
21/// use solverforge_scoring::stream::joiner::{equal, Joiner};
22///
23/// #[derive(Clone)]
24/// struct Shift {
25///     employee_id: Option<usize>,
26///     start: i64,
27/// }
28///
29/// // Match shifts with the same employee (self-join)
30/// let same_employee = equal(|s: &Shift| s.employee_id);
31///
32/// let a = Shift {
33///     employee_id: Some(5),
34///     start: 0,
35/// };
36/// let b = Shift {
37///     employee_id: Some(5),
38///     start: 8,
39/// };
40/// let c = Shift {
41///     employee_id: Some(3),
42///     start: 16,
43/// };
44///
45/// assert!(same_employee.matches(&a, &b));
46/// assert!(!same_employee.matches(&a, &c));
47/// ```
48pub fn equal<A, T, F>(key: F) -> EqualJoiner<F, F, T, Symmetric>
49where
50    T: PartialEq,
51    F: Fn(&A) -> T + Clone + Send + Sync,
52{
53    EqualJoiner {
54        left: key.clone(),
55        right: key,
56        _phantom: PhantomData,
57    }
58}
59
60/// Creates a joiner that matches when extracted values are equal.
61///
62/// Use this for cross-joins between different entity types.
63///
64/// # Example
65///
66/// ```
67/// use solverforge_scoring::stream::joiner::{equal_bi, Joiner};
68///
69/// #[derive(Clone)]
70/// struct Employee {
71///     id: usize,
72///     department: String,
73/// }
74/// #[derive(Clone)]
75/// struct Task {
76///     assigned_to: usize,
77///     name: String,
78/// }
79///
80/// // Match employees to their assigned tasks
81/// let by_id = equal_bi(|e: &Employee| e.id, |t: &Task| t.assigned_to);
82///
83/// let emp = Employee {
84///     id: 5,
85///     department: "Engineering".into(),
86/// };
87/// let task1 = Task {
88///     assigned_to: 5,
89///     name: "Review".into(),
90/// };
91/// let task2 = Task {
92///     assigned_to: 3,
93///     name: "Test".into(),
94/// };
95///
96/// assert!(by_id.matches(&emp, &task1));
97/// assert!(!by_id.matches(&emp, &task2));
98/// ```
99pub fn equal_bi<T, Fa, Fb>(left: Fa, right: Fb) -> EqualJoiner<Fa, Fb, T, Directed>
100where
101    T: PartialEq,
102    Fa: Send + Sync,
103    Fb: Send + Sync,
104{
105    EqualJoiner {
106        left,
107        right,
108        _phantom: PhantomData,
109    }
110}
111
112/// Builds an `EqualJoiner` from raw key extractors (crate-internal adapter
113/// for fluent dispatch sites that lift unary keys onto row views).
114pub fn equal_raw<Fa, Fb, T>(left: Fa, right: Fb) -> EqualJoiner<Fa, Fb, T, Directed>
115where
116    T: PartialEq,
117    Fa: Send + Sync,
118    Fb: Send + Sync,
119{
120    EqualJoiner {
121        left,
122        right,
123        _phantom: PhantomData,
124    }
125}
126
127/// Creates a joiner whose left key inspects the whole joined left row.
128///
129/// The left closure receives the borrowed left row (recursive `Concat` of
130/// `Leaf` views), so the second relationship in a chain can inspect any
131/// earlier binding or combine several. The right closure sees only the new
132/// right entity. Successive joins keep independent key types: each uniform
133/// `.join()` carries its own `K2` domain rather than inheriting the first
134/// join's key.
135///
136/// Row and right-input types stay method-generic (never impl generics), so
137/// successive joins keep heterogeneous key types without unifying domains.
138/// See `constraint::tests::relational::fluent_chain` for the exercised shapes.
139pub fn equal_on<K2, LK, KC>(left: LK, right: KC) -> EqualJoiner<LK, KC, K2, Directed>
140where
141    K2: PartialEq,
142    LK: Send + Sync,
143    KC: Send + Sync,
144{
145    EqualJoiner {
146        left,
147        right,
148        _phantom: PhantomData,
149    }
150}
151
152/// A joiner that matches when extracted values are equal.
153///
154/// Created by the [`equal()`] or [`equal_bi()`] functions.
155pub struct EqualJoiner<Fa, Fb, T, Mode = Directed> {
156    left: Fa,
157    right: Fb,
158    _phantom: PhantomData<(fn() -> T, fn() -> Mode)>,
159}
160
161impl<Fa, Fb, T, Mode> EqualJoiner<Fa, Fb, T, Mode> {
162    /// Compose conditions without fixing a borrowed row's lifetime during construction.
163    pub fn and<J>(self, other: J) -> super::AndJoiner<Self, J> {
164        super::AndJoiner {
165            first: self,
166            second: other,
167        }
168    }
169    /// Extracts the join key from an A entity.
170    #[inline]
171    pub fn key_a<A>(&self, a: &A) -> T
172    where
173        Fa: Fn(&A) -> T,
174    {
175        (self.left)(a)
176    }
177
178    /// Extracts the join key from a B entity.
179    #[inline]
180    pub fn key_b<B>(&self, b: &B) -> T
181    where
182        Fb: Fn(&B) -> T,
183    {
184        (self.right)(b)
185    }
186
187    /// Consumes the joiner and returns the key extractors.
188    ///
189    /// This is useful for zero-erasure constraint creation where
190    /// the key extractors need to be stored as concrete types.
191    #[inline]
192    pub fn into_keys(self) -> (Fa, Fb) {
193        (self.left, self.right)
194    }
195
196    /// Returns references to the key extractors.
197    #[inline]
198    pub fn key_extractors(&self) -> (&Fa, &Fb) {
199        (&self.left, &self.right)
200    }
201}
202
203impl<A, B, T, Fa, Fb, Mode> Joiner<A, B> for EqualJoiner<Fa, Fb, T, Mode>
204where
205    T: PartialEq,
206    Fa: Fn(&A) -> T + Send + Sync,
207    Fb: Fn(&B) -> T + Send + Sync,
208{
209    #[inline]
210    fn matches(&self, a: &A, b: &B) -> bool {
211        (self.left)(a) == (self.right)(b)
212    }
213}