Skip to main content

Module stream

Module stream 

Source
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 Projection instead of stored entities.
relational
Typed relational row machinery for the common operator tree.

Structs§

BalanceConstraintBuilder
Zero-erasure builder for finalizing a balance constraint.
BalanceConstraintStream
Zero-erasure stream for building balance constraints.
BiConstraintBuilder
Builder holding a weighted same-collection tuple constraint until named finalizes it.
BiConstraintStream
Same-collection constraint stream over tuples of A entities whose keys are equal.
ComplementedConstraintBuilder
Zero-erasure builder for finalizing a complemented constraint.
ComplementedConstraintStream
Zero-erasure constraint stream with complemented groups.
ConstraintFactory
Factory for creating constraint streams.
ExistsConstraintBuilder
Builder holding a weighted existence constraint until named finalizes it.
ExistsConstraintStream
Zero-erasure existence stream: a left operator, a right operator, and the named key adapters between them. named() builds the count-backed ExistenceNode and its generic terminal.
FixedWeight
Public wrapper for fixed score weights that are not one of the built-in score types.
FlattenedBiConstraintBuilder
Finalizes a flattened bi-constraint onto the shared operator tree: a JoinNode between the A collection and a FlattenNode over the B collection, joined on (join key, lookup key) == (owner key, child key). Scoring is the generic OperatorTerminal.
FlattenedBiConstraintStream
Flattened bi-constraint stream.
FlattenedCollectionTarget
A stream flattened into child items B, usable as the right side of if_exists/if_not_exists. Built by UniConstraintStream::flattened.
GroupedConstraintBuilder
Zero-erasure builder for finalizing a grouped constraint.
GroupedConstraintStream
Zero-erasure constraint stream over grouped entities.
HardWeight
Public wrapper that marks a fixed or dynamic weight as hard metadata.
JoinedGroupedBuilder
Finalizer for grouped joined rows.
JoinedGroupedStream
Grouped joined rows, backed by the common grouping operator.
PentaConstraintBuilder
Builder holding a weighted same-collection tuple constraint until named finalizes it.
PentaConstraintStream
Same-collection constraint stream over tuples of A entities whose keys are equal.
QuadConstraintBuilder
Builder holding a weighted same-collection tuple constraint until named finalizes it.
QuadConstraintStream
Same-collection constraint stream over tuples of A entities whose keys are equal.
TriConstraintBuilder
Builder holding a weighted same-collection tuple constraint until named finalizes it.
TriConstraintStream
Same-collection constraint stream over tuples of A entities whose keys are equal.
UniConstraintBuilder
Zero-erasure builder for finalizing a uni-constraint.
UniConstraintStream
Zero-erasure constraint stream over a single entity type.

Enums§

ExistenceMode
Whether an existence constraint keeps entities with or without a match.

Traits§

ExistenceTarget
Right-hand side of if_exists and if_not_exists.
Projection
Retained projection for UniConstraintStream::project: maps one entity to a bounded number of scoring rows.
ProjectionSink
Receives the rows a Projection emits.

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.