Struct Equation 

pub struct Equation { /* private fields */ }

struct containing the Equation compiled for faster evaluation

Example

use dice_forge::Equation;
let my_equation = Equation::new("3d5").unwrap();
let my_roll = my_equation.roll().unwrap();

Implementations

impl Equation

pub fn new(input: &str) -> Result<Equation, InvalidExpressionError>

Compiles and returns a new Equation object.

The input parameter should be a string representing a valid mathematical equation. The equation can include dice notation in the format “NdM” where N is the number of dice to roll, and M is the number of sides on each die. For example, “2d6” would roll two six-sided dice. The equation can also include standard mathematical operators such as addition (+), subtraction (-), multiplication (*), and division (/). Parentheses can be used to group sub-expressions together.

The function compiles the equation into a postfix format that is optimized for efficient evaluation. The resulting Equation object can then be used to roll the dice and perform basic math operations without the need for recompilation.

Example

Creating a new Equation object and rolling the dice:

use dice_forge::Equation;

let my_equation = Equation::new("3d5+10/2^2").unwrap();
let result = my_equation.roll().unwrap();
println!("Result: {}", result);

Examples found in repository

examples/damage.rs (line 11)

    fn new(health: i32, d: &str) -> Self {
        let damage =
            dice_forge::Equation::new(d).expect("dont do this in your code handle the error");
        Person { health, damage }
    }

examples/is_average_average.rs (line 4)

fn main() {
    let my_die = Equation::new("d100").expect("handle the error in real code");
    let mut results: u64 = 0;
    let mut hit_low = false;
    let mut hit_high = false;
    let mut highest: u64 = 0;
    let mut lowest: u64 = 100;
    for _n in 0..10000 {
        let rez = my_die.roll().unwrap();
        if rez == 1 {
            hit_low = true;
        } else if rez == 100 {
            hit_high = true;
        }
        if (rez as u64) < lowest {
            lowest = rez as u64;
        }
        if (rez as u64) > highest {
            highest = rez as u64;
        }
        results += my_die.roll().unwrap() as u64;
    }
    println!("average: {}", results / 10000);
    println!("Hit High: {}, number: {}", hit_high, highest);
    println!("Hit Low: {}, number: {}", hit_low, lowest);
    println!("single roll {}", my_die.roll().unwrap());
}

examples/doc_examples.rs (line 5)

fn main() {
    let my_equation = match Equation::new("3d5") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    let my_roll = my_equation.roll().unwrap();
    println!("my_roll:{}", my_roll);

    let doc_equation = match Equation::new("3d5+10/2^2") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    println!("You rolled {}", doc_equation.roll().unwrap());
    println!("Average roll {}", doc_equation.average().unwrap());
    let (low, high) = doc_equation.range().unwrap();
    println!("range {} to {}", low, high);
    println!("lowest possable number {}", doc_equation.low().unwrap());
    println!("highest possable number {}", doc_equation.high().unwrap());
    match roll::roll("test") {
        Ok(v) => println!("{}", v),
        Err(e) => println!("{}", e),
    }
}

pub fn roll(&self) -> Result<i32, InvalidExpressionError>

Rolls the given Equation object.

The input parameter should be a string representing a valid mathematical equation that can include dice notation. Dice notation should be in the format “NdM” where N is the number of dice to roll, and M is the number of sides on each die. For example, “2d6” would roll two six-sided dice. Dice notation can also be combined with standard mathematical operators, such as addition (+), subtraction (-), multiplication (), division (/), and exponent (^). Parentheses can also be used to group sub-expressions together. For example, “10+(3+2d62)+3(2d20)+d2” is a valid equation that includes dice notation.

Examples

Rolling 1d4:

use dice_forge::Equation;

let my_equation = Equation::new("1d4").unwrap();
let result = my_equation.roll().unwrap();

println!("Result: {}", result);

Rolling 2d6 a modifier:

use dice_forge::Equation;

let my_equation = Equation::new("2d6+4").unwrap();
let result = my_equation.roll().unwrap();

println!("Result: {}", result);

Rolling a more complex equation:

use dice_forge::Equation;
let my_equation = Equation::new("10+(3+2d6*2)+3(2d20)+d2").unwrap();
let result = my_equation.roll().unwrap();

println!("Result: {}", result);

Examples found in repository

examples/damage.rs (line 15)

    fn attack(&self) -> i32 {
        self.damage.roll().unwrap()
    }

examples/is_average_average.rs (line 11)

fn main() {
    let my_die = Equation::new("d100").expect("handle the error in real code");
    let mut results: u64 = 0;
    let mut hit_low = false;
    let mut hit_high = false;
    let mut highest: u64 = 0;
    let mut lowest: u64 = 100;
    for _n in 0..10000 {
        let rez = my_die.roll().unwrap();
        if rez == 1 {
            hit_low = true;
        } else if rez == 100 {
            hit_high = true;
        }
        if (rez as u64) < lowest {
            lowest = rez as u64;
        }
        if (rez as u64) > highest {
            highest = rez as u64;
        }
        results += my_die.roll().unwrap() as u64;
    }
    println!("average: {}", results / 10000);
    println!("Hit High: {}, number: {}", hit_high, highest);
    println!("Hit Low: {}, number: {}", hit_low, lowest);
    println!("single roll {}", my_die.roll().unwrap());
}

examples/doc_examples.rs (line 12)

fn main() {
    let my_equation = match Equation::new("3d5") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    let my_roll = my_equation.roll().unwrap();
    println!("my_roll:{}", my_roll);

    let doc_equation = match Equation::new("3d5+10/2^2") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    println!("You rolled {}", doc_equation.roll().unwrap());
    println!("Average roll {}", doc_equation.average().unwrap());
    let (low, high) = doc_equation.range().unwrap();
    println!("range {} to {}", low, high);
    println!("lowest possable number {}", doc_equation.low().unwrap());
    println!("highest possable number {}", doc_equation.high().unwrap());
    match roll::roll("test") {
        Ok(v) => println!("{}", v),
        Err(e) => println!("{}", e),
    }
}

pub fn average(&self) -> Result<i32, InvalidExpressionError>

calculates the product of the equation assuming the average roll of all die in the equation

Example

use dice_forge::Equation;
println!("average roll {}", Equation::new("3d5+10/2^2").unwrap().average().unwrap());

Examples found in repository

examples/doc_examples.rs (line 23)

fn main() {
    let my_equation = match Equation::new("3d5") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    let my_roll = my_equation.roll().unwrap();
    println!("my_roll:{}", my_roll);

    let doc_equation = match Equation::new("3d5+10/2^2") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    println!("You rolled {}", doc_equation.roll().unwrap());
    println!("Average roll {}", doc_equation.average().unwrap());
    let (low, high) = doc_equation.range().unwrap();
    println!("range {} to {}", low, high);
    println!("lowest possable number {}", doc_equation.low().unwrap());
    println!("highest possable number {}", doc_equation.high().unwrap());
    match roll::roll("test") {
        Ok(v) => println!("{}", v),
        Err(e) => println!("{}", e),
    }
}

pub fn range(&self) -> Result<(i32, i32), InvalidExpressionError>

Calculates the range of possible values that can be produced by the equation.

The range is calculated by finding the product of the highest and lowest possible rolls for all dice in the equation. Note that this calculation will not take into account any additional mathematical operations in the equation, and may not accurately represent the true range of possible values.

Example

use dice_forge::Equation;

let (low, high) = Equation::new("3d5+10/2^2").unwrap().range().unwrap();

println!("Range: {} - {}", low, high);

Examples found in repository

examples/doc_examples.rs (line 24)

fn main() {
    let my_equation = match Equation::new("3d5") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    let my_roll = my_equation.roll().unwrap();
    println!("my_roll:{}", my_roll);

    let doc_equation = match Equation::new("3d5+10/2^2") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    println!("You rolled {}", doc_equation.roll().unwrap());
    println!("Average roll {}", doc_equation.average().unwrap());
    let (low, high) = doc_equation.range().unwrap();
    println!("range {} to {}", low, high);
    println!("lowest possable number {}", doc_equation.low().unwrap());
    println!("highest possable number {}", doc_equation.high().unwrap());
    match roll::roll("test") {
        Ok(v) => println!("{}", v),
        Err(e) => println!("{}", e),
    }
}

pub fn low(&self) -> Result<i32, InvalidExpressionError>

Calculates the lowest possible value that can be produced by the equation.

The value is calculated by finding the product of the lowest possible rolls for all dice in the equation. Note that this calculation will not take into account any additional mathematical operations in the equation, and may not accurately represent the true lowest of possible values.

Example

use dice_forge::Equation;

let low = Equation::new("3d5+10/2^2").unwrap().low().unwrap();

println!("Low: {}", low);

Examples found in repository

examples/doc_examples.rs (line 26)

fn main() {
    let my_equation = match Equation::new("3d5") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    let my_roll = my_equation.roll().unwrap();
    println!("my_roll:{}", my_roll);

    let doc_equation = match Equation::new("3d5+10/2^2") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    println!("You rolled {}", doc_equation.roll().unwrap());
    println!("Average roll {}", doc_equation.average().unwrap());
    let (low, high) = doc_equation.range().unwrap();
    println!("range {} to {}", low, high);
    println!("lowest possable number {}", doc_equation.low().unwrap());
    println!("highest possable number {}", doc_equation.high().unwrap());
    match roll::roll("test") {
        Ok(v) => println!("{}", v),
        Err(e) => println!("{}", e),
    }
}

pub fn high(&self) -> Result<i32, InvalidExpressionError>

Calculates the highest possible value that can be produced by the equation.

The value is calculated by finding the product of the highest possible rolls for all dice in the equation. Note that this calculation will not take into account any additional mathematical operations in the equation, and may not accurately represent the true highest of possible values.

Example

use dice_forge::Equation;

let high = Equation::new("3d5+10/2^2").unwrap().high().unwrap();

println!("High: {}", high);

Examples found in repository

examples/doc_examples.rs (line 27)

fn main() {
    let my_equation = match Equation::new("3d5") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    let my_roll = my_equation.roll().unwrap();
    println!("my_roll:{}", my_roll);

    let doc_equation = match Equation::new("3d5+10/2^2") {
        Ok(value) => value,
        Err(error) => {
            println!("{}", error);
            panic!()
        }
    };
    println!("You rolled {}", doc_equation.roll().unwrap());
    println!("Average roll {}", doc_equation.average().unwrap());
    let (low, high) = doc_equation.range().unwrap();
    println!("range {} to {}", low, high);
    println!("lowest possable number {}", doc_equation.low().unwrap());
    println!("highest possable number {}", doc_equation.high().unwrap());
    match roll::roll("test") {
        Ok(v) => println!("{}", v),
        Err(e) => println!("{}", e),
    }
}

pub fn advantage(&self) -> Result<i32, InvalidExpressionError>

Rolls the given Equation object with advantage.

The input parameter should be a string representing a valid mathematical equation that can include dice notation. Dice notation should be in the format “NdM” where N is the number of dice to roll, and M is the number of sides on each die. For example, “2d6” would roll two six-sided dice. Dice notation can also be combined with standard mathematical operators, such as addition (+), subtraction (-), multiplication (), division (/), and exponent (^). Parentheses can also be used to group sub-expressions together. For example, “10+(3+2d62)+3(2d20)+d2” is a valid equation that includes dice notation.

The function rolls the given equation twice and returns the greater of the two results. This emulates the “advantage” mechanic in some games, where a player can roll two dice and take the greater result.

Examples

Rolling 1d4:

use dice_forge::Equation;

let my_equation = Equation::new("1d4").unwrap();
let result = my_equation.advantage().unwrap();

println!("Result: {}", result);

Rolling 2d6 a modifier:

use dice_forge::Equation;

let my_equation = Equation::new("2d6+4").unwrap();
let result = my_equation.advantage().unwrap();

println!("Result: {}", result);

Rolling a more complex equation:

use dice_forge::Equation;
let my_equation = Equation::new("10+(3+2d6*2)+3(2d20)+d2").unwrap();
let result = my_equation.advantage().unwrap();

println!("Result: {}", result);

pub fn disadvantage(&self) -> Result<i32, InvalidExpressionError>

Rolls the given Equation object with disadvantage.

The input parameter should be a string representing a valid mathematical equation that can include dice notation. Dice notation should be in the format “NdM” where N is the number of dice to roll, and M is the number of sides on each die. For example, “2d6” would roll two six-sided dice. Dice notation can also be combined with standard mathematical operators, such as addition (+), subtraction (-), multiplication (), division (/), and exponent (^). Parentheses can also be used to group sub-expressions together. For example, “10+(3+2d62)+3(2d20)+d2” is a valid equation that includes dice notation.

The function rolls the given equation twice and returns the lesser of the two results. This emulates the “disadvantage” mechanic in some games, where a player can roll two dice and take the lesser result.

Examples

Rolling 1d4:

use dice_forge::Equation;

let my_equation = Equation::new("1d4").unwrap();
let result = my_equation.disadvantage().unwrap();

println!("Result: {}", result);

Rolling 2d6 a modifier:

use dice_forge::Equation;

let my_equation = Equation::new("2d6+4").unwrap();
let result = my_equation.disadvantage().unwrap();

println!("Result: {}", result);

Rolling a more complex equation:

use dice_forge::Equation;
let my_equation = Equation::new("10+(3+2d6*2)+3(2d20)+d2").unwrap();
let result = my_equation.disadvantage().unwrap();

println!("Result: {}", result);

pub fn emphasis(&self) -> Result<i32, InvalidExpressionError>

Calculates the highest possible value that can be produced by the equation.

The value is calculated by finding the product of the highest possible rolls for all dice in the equation. Note that this calculation will not take into account any additional mathematical operations in the equation, and may not accurately represent the true highest of possible values.

Example

use dice_forge::Equation;

let high = Equation::new("3d5+10/2^2").unwrap().high().unwrap();

println!("High: {}", high);