Struct Dice 

pub struct Dice {
    pub builder_string: String,
    pub min: i64,
    pub max: i64,
    pub median: i64,
    pub mode: Vec<i64>,
    pub mean: BigFraction,
    pub variance: BigFraction,
    pub distribution: Vec<(i64, BigFraction)>,
    pub cumulative_distribution: Vec<(i64, BigFraction)>,
    pub build_time: u64,
}

A Dice represents a discrete probability distribution, providing paramters like mean, standard deviation and the roll() method to randomly sample from this distribution

A Dice is always created using a DiceBuilder. The simplest way is to use:

use dices::Dice;
let dice = Dice::build_from_string("2w6+3").unwrap();

which is equivalent to

use dices::DiceBuilder;
let dice_builder = DiceBuilder::from_string("2w6+3").unwrap();
let dice = dice_builder.build();

Values of the distribution are of type i64 The probabilities are of type BigFraction from the fraction crate. This allows for precise probabilites with infinite precision, at the cost of some slower operations compared to floats, but avoids pitfalls like floating point precision errors.

Fields

builder_string: String

a string that can be used to recreate the DiceBuilder that the Dice was created from.

min: i64

mininum value of the probability distribution

max: i64

maximum value of the probability distribution

median: i64

median of the probability distribution

mode: Vec<i64>

mode or modes of the probability distribution

mean: BigFraction

mean of the probability distribution

variance: BigFraction

variance of the probability distribution

distribution: Vec<(i64, BigFraction)>

the probability mass function (pmf) of the dice

tuples of each value and its probability in ascending order (regarding value)

cumulative_distribution: Vec<(i64, BigFraction)>

the cumulative distribution function (cdf) of the dice

tuples of each value and its cumulative probability in ascending order (regarding value)

build_time: u64

time it took to build the dice in microseconds

Implementations

impl Dice

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

uses the input to create a DiceBuilder and calls build() on it

pub fn builder(input: &str) -> Result<DiceBuilder, DiceBuildingError>

uses the input to create a DiceBuilder. Same as [DiceBuilder::from_string(input)]

pub fn from_builder(dice_builder: DiceBuilder) -> Dice

builds a Dice from a given DiceBuilder

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 roll(&self) -> i64

Rolls a random number for this Dice.

For this a random float is uniformly sampled over the interval [0,1) and checked against the accumulated discrete porbability distribution of this Dice.

Examples

rolling 2 standard playing dice:

use dices::Dice;
let d : Dice = Dice::build_from_string("2d6").unwrap();
println!("rolled: {}", d.roll());
//prints something like: "rolled: 9"

pub fn roll_many(&self, n: usize) -> Vec<i64>

rolls the Dice n times and returns the results as a vector

pub fn prob(&self, value: i64) -> BigFraction

probability that a number sampled from self is value

pub fn prob_lte(&self, value: i64) -> BigFraction

probability that a number sampled from self is less than or equal to value

pub fn prob_lt(&self, value: i64) -> BigFraction

probability that a number sampled from self is less than value

pub fn prob_gte(&self, value: i64) -> BigFraction

probability that a number sampled from self is greater than or equal to value

pub fn prob_gt(&self, value: i64) -> BigFraction

probability that a number sampled from self is greater than value

pub fn prob_all(&self, value: i64) -> ProbAll

returns prob_lt, prob_lte, prob, prob_gte, prob_gt in the [ProbAll] struct. Computes them more efficiently than if we use all the functions individually.

pub fn quantile<T: ToFloat>(&self, p: T) -> i64

returns the smallest p-quantile of the distribution. The smallest p-quantile q is the smallest value in the distribution for which it holds, that P(x ≤ q) ≥ p currently the trait [ToFloat] is implementen for [BigFraction] and f64

Trait Implementations

impl Debug for Dice

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

Formats the value using the given formatter.

impl PartialEq for Dice

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

impl StructuralPartialEq for Dice