Struct Evaluator

pub struct Evaluator {
    pub function: Function,
    pub environment: HashMap<usize, i32>,
}

A dice expression evaluator. The evaluator uses a client-supplied pseudo-random number to generate the results of dice rolls.

Underflows and overflows saturate to the minimum and maximum values of the i32 type, and special arithmetic rules for division, remainder, and exponentiation ensure that no undefined behavior occurs. In particular:

• Division by zero is treated as zero,
• Zero to the power of zero is treated as one,
• Bases raised to negative exponents are treated as zero.

Fields

function: Function

The function to evaluate.

environment: HashMap<usize, i32>

The environment in which to evaluate the function, as a map from external variable indices to values. Missing bindings default to zero.

Implementations

impl Evaluator

pub fn new(function: Function) -> Self

Construct an evaluator for the given function.

Parameters

• function: The function to evaluate.

Returns

The constructed evaluator.

pub fn bind<'s>( &mut self, name: &'s str, value: i32, ) -> Result<(), EvaluationError<'s>>

Bind an external variable to a value. The external variable must be declared in the function’s signature.

Parameters

• name: The name of the target external variable.
• value: The value to bind to the external variable.

Errors

UnrecognizedExternal if the alleged external variable is unrecognized.

pub fn evaluate<R>( &mut self, args: impl IntoIterator<Item = i32>, rng: &mut R, ) -> Result<Evaluation, EvaluationError<'static>>

where R: Rng + ?Sized,

Evaluate the function using the given arguments and pseudo-random number generator (pRNG). Be sure to bind all external variables, and seed the pRNG if desired, before calling this method. Missing external variables default to zero during evaluation, but all parameters must be bound.

Parameters

• args: The arguments to the function.
• rng: The pseudo-random number generator to use for range and dice rolls.

Returns

The result of the evaluation.

Errors

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

impl Evaluator

pub fn bounds( &self, args: impl IntoIterator<Item = i32>, ) -> Result<Bounds, EvaluationError<'_>>

Compute the bounds of the function for the specified arguments and external variables.

Parameters

• args: The arguments to the function.

Returns

The bounds of the function, covering both the value and the number of possible outcomes. The possible outcome count is None if the function contains dynamic range or roll expressions, i.e., range or roll expressions whose count or faces are themselves determined by range or roll expressions. In such cases, the outcome count cannot be determined without generating a complete histogram of the function, which is too expensive to do without a specific request.

Errors

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

Trait Implementations

impl Clone for Evaluator

fn clone(&self) -> Evaluator

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Evaluator

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

Formats the value using the given formatter.

impl Hash for Evaluator

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Evaluator

fn eq(&self, other: &Evaluator) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Evaluator

impl StructuralPartialEq for Evaluator