Enum DiceBuilder 

pub enum DiceBuilder {
    Constant(i64),
    FairDie {
        min: i64,
        max: i64,
    },
    SumCompound(Vec<DiceBuilder>),
    ProductCompound(Vec<DiceBuilder>),
    DivisionCompound(Vec<DiceBuilder>),
    MaxCompound(Vec<DiceBuilder>),
    MinCompound(Vec<DiceBuilder>),
    SampleSumCompound(Vec<DiceBuilder>),
}

A DiceBuilder tree-like data structure representing the components of a dice formula like max(2d6+4,d20)

The tree can be used to calculate a discrete probability distribution. This happens when the build() method is called and creates a Dice.

Examples

use dices::DiceBuilder;
use fraction::ToPrimitive;
let dice_builder = DiceBuilder::from_string("2d6+4").unwrap();
let dice = dice_builder.build();
let mean = dice.mean.to_f64().unwrap();
assert_eq!(mean, 11.0);

Variants

Constant(i64)

A constant value (i64) that does not

FairDie

A discrete uniform distribution over the integer interval [min, max]

Fields

min: i64

minimum value of the die, inclusive

max: i64

maximum value of the die, inclusive

SumCompound(Vec<DiceBuilder>)

the sum of multiple DiceBuilder instances, like: d6 + 3 + d20

ProductCompound(Vec<DiceBuilder>)

the product of multiple DiceBuilder instances, like: d6 * 3 * d20

DivisionCompound(Vec<DiceBuilder>)

the division of multiple DiceBuilder instances, left-associative, rounded up to integers like: d6 / 2 = d3

MaxCompound(Vec<DiceBuilder>)

the maximum of multiple DiceBuilder instances, like: max(d6,3,d20)

MinCompound(Vec<DiceBuilder>)

the minimum of multiple DiceBuilder instances, like: min(d6,3,d20)

SampleSumCompound(Vec<DiceBuilder>)

SampleSumCompound(vec![a,b]) can be interpreted as follows: A DiceBuilder b is sampled a times independently of each other. It is represented by an x in input strings, e.g. “a x b” The operator is left-associative, so a x b x c is (a x b) x c.

Examples

throwing 5 six-sided dice:

use dices::DiceBuilder::*;
let five_six_sided_dice = SampleSumCompound(
    vec![Constant(5),FairDie{min: 1, max: 6}]
);

throwing 1, 2 or 3 (randomly determined) six-sided and summing them up:

use dices::DiceBuilder::*;
let dice_1_2_or_3 = SampleSumCompound(
    vec![FairDie{min: 1, max: 3},FairDie{min: 1, max: 6}]
);

for two constants, it is the same as multiplication:

use dices::DiceBuilder::*;
let b1 = SampleSumCompound(vec![Constant(2),Constant(3)]);
let b2 = ProductCompound(vec![Constant(2),Constant(3)]);
assert_eq!(b1.build().distribution, b2.build().distribution);

Implementations

impl DiceBuilder

pub fn from_string(input: &str) -> Result<Self, DiceBuildingError>

parses the string into a tree-like structure to create a DiceBuilder

Syntax Examples:

|—–| | | 4 six-sided dice: “4d6”

Examples:

throwing 3 six-sided dice:

use dices::DiceBuilder;
let builder = DiceBuilder::from_string("3d6");
let builder_2 = DiceBuilder::from_string("3 d6  ");
let builder_3 = DiceBuilder::from_string("3xd6"); // explicitly using sample sum
assert_eq!(builder, builder_2);
assert_eq!(builder_2, builder_3);

the minimum and maximum of multiple dice:

use dices::DiceBuilder;
let min_builder = DiceBuilder::from_string("min(d6,d6)");
let max_builder = DiceBuilder::from_string("max(d6,d6,d20)");

pub fn build(self) -> Dice

builds a Dice from [self]

this method calculates the distribution and all distribution paramters on the fly, to create the Dice. Depending on the complexity of the dice_builder heavy lifting like convoluting probability distributions may take place here.

pub fn build_from_string(input: &str) -> Result<Dice, DiceBuildingError>

shortcut for DiceBuilder::from_string(input).build()

pub fn reconstruct_string(&self) -> String

constructs a string from the DiceBuilder that can be used to reconstruct an equivalent DiceBuilder from it.

currently fails to construct a correct string in case dices with a non-1 minimum are present. This is because there is no string notation for dices with a non-1 minimum yet.

pub fn distribution_iter(&self) -> Box<dyn Iterator<Item = (i64, BigFraction)>>

iterator for the probability mass function (pmf) of the DiceBuilder, with tuples for each value with its probability in ascending order (regarding value)

Calculates the distribution and all distribution paramters. Depending on the complexity of [self] heavy lifting like convoluting probability distributions may take place here.

Trait Implementations

impl Add for Box<DiceBuilder>

type Output = Box<DiceBuilder>

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl Debug for DiceBuilder

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

Formats the value using the given formatter.

impl Display for DiceBuilder

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

Formats the value using the given formatter.

impl Mul for Box<DiceBuilder>

type Output = Box<DiceBuilder>

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation.

impl PartialEq for DiceBuilder

fn eq(&self, other: &DiceBuilder) -> 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 DiceBuilder

impl StructuralPartialEq for DiceBuilder