Crate dices

A crate for calculating distrete probability distributions of dice.

To create a Dice, build it from a DiceBuilder or directly from a string:

use dices::{Dice, DiceBuilder};
let dice: Dice = DiceBuilder::from_string("2d6").unwrap().build();
let dice: Dice = Dice::build_from_string("2d6").unwrap();

---

Properties of these dice are calculated in the build() function:

min: 2
max: 12
mode: vec![7],
mean: 7,
median: 7,
distribution: vec![(2, 1/36), (3, 1/18), (4, 1/12), (5, 1/9), (5, 1/9), (6, 5/36), (7, 1/6), ...]
cumulative_distribution: vec![(2, 1/36), (3, 1/12), (4, 1/6), ...]

A DiceBuildingError could be returned, if the input string could not be parsed into a proper syntax tree for the DiceBuilder.

To roll a Dice call the roll() function, for rolling multiple times call the roll_multiple() function:

use dices::Dice;
let dice = Dice::build_from_string("2d6").unwrap();
let num = dice.roll();
let nums = dice.roll_many(10);
// num will be some i64 between 2 and 12, sampled according to the dices distribution
// nums could be vec![7,3,9,11,7,8,5,6,3,6]

---

Syntax Examples:

Some exaple strings that can be passed into the DiceBuilder::from_string(input) function

3 six-sided dice:

"3d6", "3w6" or "3xw6"

one six-sided die multiplied by 3:

"3*d6" or "d6*3"

rolling one or two six sided dice and summing them up

"d2xd6"

the maximum of two six-sided-dice minus the minimum of two six sided dice

"max(d6,d6)-min(d6,d6)""

rolling a die but any value below 2 becomes 2 and above 5 becomes 5

"min(max(2,d6),5)"

multiplying 3 20-sided-dice

"d20*d20*d20"

Calculating Probabilities

Background Information

This crate uses the BigFraction data type from the fraction crate to represent probabilities This is quite nice because it allows for precise probabilities with infinite precision. The drawback is that it is less efficient than using floats.

While "d100*d100" takes about 100ms for me, something like “d10xd100” took 9.000 ms to finish calculating the probability distribution. There is room for optimization.

Structs

Dice

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

Enums

DiceBuilder

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