Expand description
Fluent constraint stream API for zero-erasure constraint programming.
This module provides an ergonomic builder pattern for defining constraints that compile to fully monomorphized, monomorphized constraint implementations.
§Overview
The stream API transforms verbose constraint definitions into concise, fluent declarations while preserving full type information through the entire evaluation pipeline.
§Example
use solverforge_core::score::SoftScore;
use solverforge_scoring::api::constraint_set::{ConstraintSet, IncrementalConstraint};
use solverforge_scoring::stream::ConstraintFactory;
#[derive(Clone)]
struct Schedule {
shifts: Vec<Shift>,
}
#[derive(Clone, Debug)]
struct Shift {
employee_idx: Option<usize>,
required_skill: String,
}
// Define constraints using the fluent API
let unassigned = ConstraintFactory::<Schedule, SoftScore>::new()
.for_each(Schedule::shifts())
.filter(|shift: &Shift| shift.employee_idx.is_none())
.penalize(SoftScore::of(1))
.named("Unassigned shift");
// Use the constraint
let schedule = Schedule {
shifts: vec![
Shift {
employee_idx: Some(0),
required_skill: "A".into(),
},
Shift {
employee_idx: None,
required_skill: "B".into(),
},
],
};
assert_eq!(unassigned.evaluate(&schedule), SoftScore::of(-1));§Architecture
The stream builders produce existing constraint types at definition time:
ConstraintFactory::new()
.for_each(extractor) -> UniConstraintStream<S, A, Sc>
.filter(predicate) -> UniConstraintStream (accumulates filters)
.penalize(weight) -> UniConstraintBuilder<S, A, Sc>
.named(name) -> IncrementalUniConstraint<S, A, Sc>The final IncrementalUniConstraint is fully monomorphized with no
virtual dispatch in the hot path.
Re-exports§
pub use collection_extract::CollectionExtract;pub use collection_extract::FlattenExtract;pub use join_target::JoinTarget;pub use key_extract::EntityKeyAdapter;pub use key_extract::KeyExtract;
Modules§
- chain
- Chain stream and builder.
- collection_
extract CollectionExtract: the source of a stream’s rows.- collector
- Collectors for grouping and aggregating stream matches.
- cross
- Cross-collection join streams and their builders.
- filter
- Zero-erasure filter composition for constraint streams.
- join_
target - JoinTarget trait for single
.join()dispatch on UniConstraintStream. - joiner
- Joiner functions for constraint stream joins.
- key_
extract - KeyExtract trait and adapters for zero-erasure join key extraction.
- projected
- Projected streams: rows emitted by a
Projectioninstead of stored entities. - relational
- Typed relational row machinery for the common operator tree.
Structs§
- Balance
Constraint Builder - Zero-erasure builder for finalizing a balance constraint.
- Balance
Constraint Stream - Zero-erasure stream for building balance constraints.
- BiConstraint
Builder - Builder holding a weighted same-collection tuple constraint until
namedfinalizes it. - BiConstraint
Stream - Same-collection constraint stream over tuples of
Aentities whose keys are equal. - Complemented
Constraint Builder - Zero-erasure builder for finalizing a complemented constraint.
- Complemented
Constraint Stream - Zero-erasure constraint stream with complemented groups.
- Constraint
Factory - Factory for creating constraint streams.
- Exists
Constraint Builder - Builder holding a weighted existence constraint until
namedfinalizes it. - Exists
Constraint Stream - Zero-erasure existence stream: a left operator, a right operator, and the
named key adapters between them.
named()builds the count-backedExistenceNodeand its generic terminal. - Fixed
Weight - Public wrapper for fixed score weights that are not one of the built-in score types.
- Flattened
BiConstraint Builder - Finalizes a flattened bi-constraint onto the shared operator tree: a
JoinNodebetween the A collection and aFlattenNodeover the B collection, joined on(join key, lookup key) == (owner key, child key). Scoring is the genericOperatorTerminal. - Flattened
BiConstraint Stream - Flattened bi-constraint stream.
- Flattened
Collection Target - A stream flattened into child items
B, usable as the right side ofif_exists/if_not_exists. Built byUniConstraintStream::flattened. - Grouped
Constraint Builder - Zero-erasure builder for finalizing a grouped constraint.
- Grouped
Constraint Stream - Zero-erasure constraint stream over grouped entities.
- Hard
Weight - Public wrapper that marks a fixed or dynamic weight as hard metadata.
- Joined
Grouped Builder - Finalizer for grouped joined rows.
- Joined
Grouped Stream - Grouped joined rows, backed by the common grouping operator.
- Penta
Constraint Builder - Builder holding a weighted same-collection tuple constraint until
namedfinalizes it. - Penta
Constraint Stream - Same-collection constraint stream over tuples of
Aentities whose keys are equal. - Quad
Constraint Builder - Builder holding a weighted same-collection tuple constraint until
namedfinalizes it. - Quad
Constraint Stream - Same-collection constraint stream over tuples of
Aentities whose keys are equal. - TriConstraint
Builder - Builder holding a weighted same-collection tuple constraint until
namedfinalizes it. - TriConstraint
Stream - Same-collection constraint stream over tuples of
Aentities whose keys are equal. - UniConstraint
Builder - Zero-erasure builder for finalizing a uni-constraint.
- UniConstraint
Stream - Zero-erasure constraint stream over a single entity type.
Enums§
- Existence
Mode - Whether an existence constraint keeps entities with or without a match.
Traits§
- Constraint
Weight - The weight a
penalizeorrewardcall scores each match with. - Existence
Target - Right-hand side of
if_existsandif_not_exists. - Projection
- Retained projection for
UniConstraintStream::project: maps one entity to a bounded number of scoring rows. - Projection
Sink - Receives the rows a
Projectionemits. - Unassigned
Entity - An entity that knows whether its planning variable is unassigned, which
enables
UniConstraintStream::unassignedon streams over it.
Functions§
- fixed_
weight - Wraps a fixed score weight while preserving static dispatch.
- hard_
weight - Wraps a weight and forces hard constraint metadata while preserving static dispatch.