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}