Crate d20 

D20

D20 is a simple crate designed to evaluate roll expressions. A roll expression is an english-language string that reflects the intent of a dungeon or game master to perform a particular roll.

For example, in a tabletop game you may frequently hear phrases like “roll 2d10”, or “roll 3d6 and add 5”. These are roll expressions, and the components within them are what we call die roll terms. A die roll term is either a term that calls for the rolling of an n-sided die x times (e.g. 3d6) or a modifier that simply adds or subtracts a constant value from the larger expression.

Examples of valid roll expressions include:

• 3d6
• 2d10 + 5
• 1d20-3
• +6
• -2
• 3d10+5d100-21+7

Roll expressions can have arbitrary length and complexity, and it is perfectly legal for the final result of a roll expression to be negative after applying modifiers.

Examples

let r = d20::roll_dice("3d6 + 4").unwrap();
assert!(r.total > 6);
let r = d20::roll_dice("1d1-3").unwrap();
assert_eq!(r.total, -2);

// Bad expressions produce errors rather than panicking.
assert!(d20::roll_dice("roll four chickens and add six ferrets").is_err());

Iterating Roll

A valid Roll can be turned into an open-ended iterator via its rolls() method, providing successive rolls of the given die roll expression.

Note that it will be necessary to constrain the iterator via take(n).

use d20::*;

let v: Vec<Roll> = d20::roll_dice("3d6").unwrap().rolls().take(3).collect();

assert_eq!(v.len(), 3);
assert!(v[0].total >= 3 && v[0].total <= 18);
assert!(v[1].total >= 3 && v[1].total <= 18);
assert!(v[2].total >= 3 && v[2].total <= 18);

Range Rolls

If you are less concerned about dice rolls and require only a random number within a given range, roll_range() will do just that.

let rg = d20::roll_range(1, 100).unwrap();
assert!((1..=100).contains(&rg));

Structs

Roll

Represents the results of an evaluated die roll expression.

RollIterator

An infinite iterator of fresh rolls, created by Roll::rolls.

Enums

D20Error

The error type returned when a roll expression cannot be evaluated.

TermResult

The evaluated result of a single term within a roll expression.

Constants

MAX_DICE

Maximum number of dice a single term may roll (e.g. the 100 in 100d6). Larger counts are rejected with D20Error::DiceCountTooLarge rather than panicking or hanging.

MAX_MODIFIER

Maximum absolute value of a numeric modifier (e.g. the 5 in +5). Larger magnitudes are rejected with D20Error::ModifierTooLarge.

MAX_SIDES

Maximum number of sides a die may have (e.g. the 20 in 1d20). Larger values are rejected with D20Error::SidesTooLarge.

Functions

roll_dice

Evaluates the expression string input as a die roll expression (e.g. 3d6 + 4). The results are returned in a Result containing either a valid Roll or a D20Error describing why the expression could not be evaluated. This function never panics on malformed or out-of-range input.

roll_dice_with_rng

Like roll_dice, but draws randomness from the supplied rng instead of the thread-local generator. Pass a seeded RNG (e.g. StdRng::seed_from_u64) for deterministic, reproducible rolls.

roll_range

Generates a random number within the specified inclusive range [min, max]. Returns a Result containing either the randomly generated i32 or a D20Error::InvalidRange when min > max.

roll_range_with_rng

Like roll_range, but draws randomness from the supplied rng.