Skip to main content

solverforge_scoring/stream/
mod.rs

1//! Fluent constraint stream API for zero-erasure constraint programming.
2//!
3//! This module provides an ergonomic builder pattern for defining constraints
4//! that compile to fully monomorphized, monomorphized constraint implementations.
5//!
6//! # Overview
7//!
8//! The stream API transforms verbose constraint definitions into concise,
9//! fluent declarations while preserving full type information through the
10//! entire evaluation pipeline.
11//!
12//! # Example
13//!
14//! ```
15//! use solverforge_core::score::SoftScore;
16//! use solverforge_scoring::api::constraint_set::{ConstraintSet, IncrementalConstraint};
17//! use solverforge_scoring::stream::ConstraintFactory;
18//!
19//! #[derive(Clone)]
20//! struct Schedule {
21//!     shifts: Vec<Shift>,
22//! }
23//! # use solverforge_scoring::stream::{source, ChangeSource, CollectionExtract};
24//! # impl Schedule {
25//! #     fn shifts() -> impl CollectionExtract<Schedule, Item = Shift> {
26//! #         fn shifts(s: &Schedule) -> &[Shift] {
27//! #             s.shifts.as_slice()
28//! #         }
29//! #         source(shifts as fn(&Schedule) -> &[Shift], ChangeSource::Descriptor(0))
30//! #     }
31//! # }
32//!
33//! #[derive(Clone, Debug)]
34//! struct Shift {
35//!     employee_idx: Option<usize>,
36//!     required_skill: String,
37//! }
38//!
39//! // Define constraints using the fluent API
40//! let unassigned = ConstraintFactory::<Schedule, SoftScore>::new()
41//!     .for_each(Schedule::shifts())
42//!     .filter(|shift: &Shift| shift.employee_idx.is_none())
43//!     .penalize(SoftScore::of(1))
44//!     .named("Unassigned shift");
45//!
46//! // Use the constraint
47//! let schedule = Schedule {
48//!     shifts: vec![
49//!         Shift {
50//!             employee_idx: Some(0),
51//!             required_skill: "A".into(),
52//!         },
53//!         Shift {
54//!             employee_idx: None,
55//!             required_skill: "B".into(),
56//!         },
57//!     ],
58//! };
59//!
60//! assert_eq!(unassigned.evaluate(&schedule), SoftScore::of(-1));
61//! ```
62//!
63//! # Architecture
64//!
65//! The stream builders produce existing constraint types at definition time:
66//!
67//! ```text
68//! ConstraintFactory::new()
69//! .for_each(extractor)     -> UniConstraintStream<S, A, Sc>
70//! .filter(predicate)            -> UniConstraintStream (accumulates filters)
71//! .penalize(weight)             -> UniConstraintBuilder<S, A, Sc>
72//! .named(name)                  -> IncrementalUniConstraint<S, A, Sc>
73//! ```
74//!
75//! The final `IncrementalUniConstraint` is fully monomorphized with no
76//! virtual dispatch in the hot path.
77
78#[macro_use]
79mod arity_stream_macros;
80mod balance_stream;
81mod bi_stream;
82mod chain_stream;
83pub mod collection_extract;
84pub mod collector;
85mod complemented_stream;
86mod cross_bi_stream;
87mod cross_penta_stream;
88pub(crate) mod cross_quad_stream;
89mod cross_tri_stream;
90mod existence_stream;
91mod existence_target;
92mod factory;
93pub mod filter;
94mod flattened_bi_stream;
95mod group_by_penta;
96mod group_by_quad;
97mod group_by_tri;
98mod grouped_stream;
99mod joined_grouped_stream;
100pub use joined_grouped_stream::{JoinedGroupedBuilder, JoinedGroupedStream};
101pub mod join_target;
102pub mod joiner;
103pub mod key_extract;
104mod penta_stream;
105mod projected_stream;
106mod quad_stream;
107pub mod relational;
108mod tri_stream;
109mod unassigned;
110mod uni_stream;
111mod weighting_support;
112
113#[cfg(test)]
114mod tests;
115
116/// Cross-collection join streams and their builders.
117pub mod cross {
118    pub use super::cross_bi_stream::{
119        Bi, Builder, ComplementedGrouped, ComplementedGroupedBuilder, Grouped, GroupedBuilder,
120    };
121    pub use super::cross_penta_stream::{Penta, PentaBuilder};
122    pub use super::cross_quad_stream::{Quad, QuadBuilder};
123    pub use super::cross_tri_stream::Tri;
124}
125
126/// Chain stream and builder.
127pub mod chain {
128    pub use super::chain_stream::{Chain, ChainBuilder};
129}
130
131/// Projected streams: rows emitted by a [`Projection`] instead of stored entities.
132pub mod projected {
133    pub use super::projected_stream::{
134        Bi, BiBuilder, Builder, ComplementedGrouped, ComplementedGroupedBuilder, DirectedBi,
135        DirectedBiBuilder, Grouped, GroupedBuilder, JoinedSource, ProjectedJoinTarget, Projection,
136        ProjectionSink, RowCoordinate, RowOwner, Source, Stream,
137    };
138}
139
140pub use balance_stream::{BalanceConstraintBuilder, BalanceConstraintStream};
141pub use bi_stream::{BiConstraintBuilder, BiConstraintStream};
142pub use collection_extract::{
143    source, ChangeSource, CollectionExtract, FlattenExtract, SourceExtract,
144};
145pub use complemented_stream::{ComplementedConstraintBuilder, ComplementedConstraintStream};
146pub use existence_stream::{ExistenceMode, ExistsConstraintBuilder, ExistsConstraintStream};
147pub use existence_target::{ExistenceTarget, FlattenedCollectionTarget};
148pub use factory::ConstraintFactory;
149pub use flattened_bi_stream::{FlattenedBiConstraintBuilder, FlattenedBiConstraintStream};
150pub use grouped_stream::{GroupedConstraintBuilder, GroupedConstraintStream};
151pub use join_target::JoinTarget;
152pub use key_extract::{EntityKeyAdapter, KeyExtract};
153pub use penta_stream::{PentaConstraintBuilder, PentaConstraintStream};
154pub use projected_stream::{Projection, ProjectionSink};
155pub use quad_stream::{QuadConstraintBuilder, QuadConstraintStream};
156pub use tri_stream::{TriConstraintBuilder, TriConstraintStream};
157#[doc(hidden)]
158pub use unassigned::UnassignedEntity;
159pub use uni_stream::{UniConstraintBuilder, UniConstraintStream};
160#[doc(hidden)]
161pub use weighting_support::ConstraintWeight;
162pub use weighting_support::{fixed_weight, hard_weight, FixedWeight, HardWeight};