Struct Problem 

pub struct Problem<P: PieceKind, C: ColorKind = SquareColor> {
    pub num_squares: usize,
    pub square_colors: Vec<C>,
    pub pieces: Vec<P>,
    pub constraint: Constraint<P, C>,
}

A constraint-satisfaction problem: a fixed board (size + per-square colour from a user-defined colour set), an alphabet of available piece kinds, and a constraint to satisfy.

pieces is the alphabet — the set of distinct kinds available. Duplicate entries are silently deduplicated; first-appearance order is preserved.

C is the colour kind. The default is SquareColor — the binary light/dark partition used by chess. For N-way partitions define your own enum and use it as the C type parameter.

square_colors must either be empty (no colour partition declared; colour-keyed constraints always see zero matches) or have length exactly num_squares. Call validate to check this and that every constraint references only declared pieces, colours, and squares.

Solve by calling Problem::count for the population size or Problem::iter to stream all satisfying arrangements.

If pieces is empty or num_squares == 0, the problem has no arrangements to enumerate and count() returns 0.

Fields

num_squares: usize

Number of squares (e.g. 8 for a chess back rank).

square_colors: Vec<C>

Colour of each square. square_colors.len() == num_squares.

pieces: Vec<P>

Alphabet of available piece kinds. Duplicates are silently deduped by the solver; size doesn’t have to equal num_squares.

constraint: Constraint<P, C>

Root constraint. Use Constraint::And for conjunctions.

Implementations

impl<P: PieceKind, C: ColorKind> Problem<P, C>

pub fn validate(&self) -> Result<(), ValidationError>

Checks self is internally consistent and returns a ValidationError if not.

Specifically:

• square_colors is either empty or num_squares long.
• Every piece referenced by a constraint is in self.pieces.
• Every colour referenced by a CountOnColor is in self.square_colors. An empty square_colors is valid only for problems that have no CountOnColor constraints; otherwise the colour reference is treated as unknown.
• Every At / NotAt square index is < num_squares.
• Every Order / Relative instance index is < declared count for that piece (only checked when the piece has a Constraint::Count { Eq, n } constraint declaring its count).

count() / iter() / sample() do not auto-validate; if you need correctness up front, call this first or use ProblemBuilder::try_build.

pub fn builder() -> ProblemBuilder<P, C>

Returns a fresh empty ProblemBuilder for fluent construction.

use chess_startpos_rs::{chess, Constraint, CountOp, Problem, SquareColor};

let problem: Problem<chess::Piece> = Problem::builder()
    .squares(8)
    .alternating_colors(SquareColor::Dark, SquareColor::Light)
    .pieces([chess::Piece::King, chess::Piece::Queen])
    .constraint(Constraint::Count {
        piece: chess::Piece::King,
        op: CountOp::Eq,
        value: 1,
    })
    .constraint(Constraint::Count {
        piece: chess::Piece::Queen,
        op: CountOp::Eq,
        value: 7,
    })
    .build();
assert_eq!(problem.count(), 8); // 1 king × 8 placements over 7 queens

The struct-literal API (Problem is a regular public-fields struct) remains a fully supported alternative.

pub fn count(&self) -> u64

Number of distinct arrangements satisfying the constraint.

pub fn iter(&self) -> impl Iterator<Item = Vec<P>> + '_

Streams all distinct arrangements satisfying the constraint in canonical lexicographic order.

pub fn at(&self, index: u64) -> Option<Vec<P>>

Returns the index-th satisfying arrangement in canonical lexicographic order, or None if index >= self.count().

Equivalent to self.iter().nth(index) with u64 indexing. O(index) — for repeated indexed lookup prefer iterating once.

pub fn sample(&self, seed: u64) -> Option<Vec<P>>

Returns a uniformly-random arrangement satisfying the constraint, deterministic in seed. None if the constraint is unsatisfiable.

Single pass over self.iter() using reservoir-of-size-1 sampling: each satisfying arrangement is selected with probability 1 / k where k is its 1-based index in the iterator. The result is uniformly random over the satisfying arrangements without materialising them all.

pub fn with_constraint(&self, c: Constraint<P, C>) -> Self

Returns a copy of self with c added via AND-composition.

Trait Implementations

impl<P: Clone + PieceKind, C: Clone + ColorKind> Clone for Problem<P, C>

fn clone(&self) -> Problem<P, C>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<P: Debug + PieceKind, C: Debug + ColorKind> Debug for Problem<P, C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, P, C> Deserialize<'de> for Problem<P, C>

where P: Deserialize<'de> + PieceKind, C: Deserialize<'de> + ColorKind,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<P, C> Serialize for Problem<P, C>

where P: Serialize + PieceKind, C: Serialize + ColorKind,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.