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;
83mod closures;
84pub mod collection_extract;
85pub mod collector;
86mod complemented_stream;
87mod cross_bi_stream;
88mod cross_penta_stream;
89pub(crate) mod cross_quad_stream;
90mod cross_tri_stream;
91mod existence_stream;
92mod existence_target;
93mod factory;
94pub mod filter;
95mod flattened_bi_stream;
96mod group_by_penta;
97mod group_by_quad;
98mod group_by_tri;
99mod grouped_stream;
100mod joined_grouped_stream;
101pub use joined_grouped_stream::{JoinedGroupedBuilder, JoinedGroupedStream};
102pub mod join_target;
103pub mod joiner;
104pub mod key_extract;
105mod penta_stream;
106mod projected_stream;
107mod quad_stream;
108pub mod relational;
109mod tri_stream;
110mod unassigned;
111mod uni_stream;
112mod weighting_support;
113
114#[cfg(test)]
115mod tests;
116
117/// Cross-collection join streams and their builders.
118pub mod cross;
119
120/// Chain stream and builder.
121pub mod chain;
122
123/// Projected streams: rows emitted by a [`Projection`] instead of stored entities.
124pub mod projected;
125
126pub use balance_stream::{BalanceConstraintBuilder, BalanceConstraintStream};
127pub use bi_stream::{BiConstraintBuilder, BiConstraintStream};
128pub use collection_extract::{
129    model_source, source, AnalysisPlanningId, ChangeSource, CollectionExtract, FlattenExtract,
130    ModelPlanningIds, NoPlanningIds, RenderPlanningId, RenderPlanningIdDebug,
131    RenderPlanningIdDisplay, RenderPlanningIdNone, SourceExtract, SourcePlanningIds,
132};
133pub use complemented_stream::{ComplementedConstraintBuilder, ComplementedConstraintStream};
134pub use existence_stream::{ExistenceMode, ExistsConstraintBuilder, ExistsConstraintStream};
135pub use existence_target::{ExistenceTarget, FlattenedCollectionTarget};
136pub use factory::ConstraintFactory;
137pub use flattened_bi_stream::{FlattenedBiConstraintBuilder, FlattenedBiConstraintStream};
138pub use grouped_stream::{GroupedConstraintBuilder, GroupedConstraintStream};
139pub use join_target::JoinTarget;
140pub use key_extract::{EntityKeyAdapter, KeyExtract};
141pub use penta_stream::{PentaConstraintBuilder, PentaConstraintStream};
142pub use projected_stream::{Projection, ProjectionSink};
143pub use quad_stream::{QuadConstraintBuilder, QuadConstraintStream};
144pub use tri_stream::{TriConstraintBuilder, TriConstraintStream};
145pub use unassigned::UnassignedEntity;
146pub use uni_stream::{UniConstraintBuilder, UniConstraintStream};
147pub use weighting_support::{fixed_weight, hard_weight, ConstraintWeight, FixedWeight, HardWeight};