Trait HistogramBuilder

pub trait HistogramBuilder<'inst, T>
where
    T: 'inst,
{
    // Required methods
    fn new(evaluator: Evaluator) -> Self;
    fn build_while(
        &self,
        args: impl IntoIterator<Item = i32> + Send,
        condition: impl Fn(&i32) -> bool + Send + Sync,
    ) -> Result<Histogram, EvaluationError<'_>>;
    fn iter(
        &'inst self,
        args: impl IntoIterator<Item = i32>,
    ) -> Result<T, EvaluationError<'inst>>;

    // Provided methods
    fn build(
        &self,
        args: impl IntoIterator<Item = i32> + Send,
    ) -> Result<Histogram, EvaluationError<'_>> { ... }
    fn build_with_limit(
        &self,
        args: impl IntoIterator<Item = i32> + Send,
        limit: u64,
    ) -> Result<Histogram, EvaluationError<'_>> { ... }
}

A builder for histograms of the outcomes of dice expressions.

Type Parameters

• T: The type of iterator to use when building the histogram. Deliberately not bounded by Iterator to allow for parallel iterators.

Required Methods

fn new(evaluator: Evaluator) -> Self

Constructs a new histogram builder from the given evaluator.

Parameters

• evaluator: The evaluator, suitably configured to evaluate the function.

Returns

A new histogram builder.

fn build_while( &self, args: impl IntoIterator<Item = i32> + Send, condition: impl Fn(&i32) -> bool + Send + Sync, ) -> Result<Histogram, EvaluationError<'_>>

Build the histogram of the outcomes of the dice expression for as long as the supplied condition evaluates to true. The histogram will contain possible outcomes of the dice expression, but may be incomplete.

Parameters

• args: The arguments to the dice expression.
• condition: The condition that must be satisfied for histogram construction to continue. Applied to an outcome of the dice expression.

Returns

The histogram of the outcomes of the dice expression.

Errors

BadArity if the number of arguments provided disagrees with the number of formal parameters in the function signature.

fn iter( &'inst self, args: impl IntoIterator<Item = i32>, ) -> Result<T, EvaluationError<'inst>>

Build an iterator that can be consumed to compute the histogram of the outcomes of the dice expression. The iterator will compute the histogram lazily, and may be terminated early for any reason, such as exceeding the desired maximum number of outcomes or running out of time. Afterward, the (potentially incomplete) histogram may be retrieved from the builder.

Returns

An iterator of outcomes.

Errors

BadArity if the number of arguments provided disagrees with the number of formal parameters in the function signature.

Provided Methods

fn build( &self, args: impl IntoIterator<Item = i32> + Send, ) -> Result<Histogram, EvaluationError<'_>>

Build the histogram of the outcomes of the dice expression, irrespective of the number of outcomes. The histogram will contain all possible outcomes rolled by the dice expression. Highly convenient, but not recommended for dice expressions with many ranges, many dice, and/or many-sided dice.

Parameters

• args: The arguments to the dice expression.

Returns

The histogram of the outcomes of the dice expression.

Errors

BadArity if the number of arguments provided disagrees with the number of formal parameters in the function signature.

fn build_with_limit( &self, args: impl IntoIterator<Item = i32> + Send, limit: u64, ) -> Result<Histogram, EvaluationError<'_>>

Build the histogram of the outcomes of the dice expression, stopping short after limit outcomes have been rolled. The histogram will contain at most limit outcomes rolled by the dice expression.

Parameters

• args: The arguments to the dice expression.
• limit: The maximum number of outcomes to roll.

Returns

The histogram of the outcomes of the dice expression.

Errors

BadArity if the number of arguments provided disagrees with the number of formal parameters in the function signature.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'inst> HistogramBuilder<'inst, EvaluationStateIterator<'inst>> for xdy::parallel::HistogramBuilder

impl<'inst> HistogramBuilder<'inst, EvaluationStateIterator<'inst>> for xdy::serial::HistogramBuilder