# Crate d20 [−] [src]

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

extern crate d20; fn main() { 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); let r = d20::roll_dice("roll four chickens and add six ferrets"); match r { Ok(_) => assert!(false), // this should NOT be ok, fail Err(_) => assert!(true), // bad expressions produce errors } }

### Iterating Roll

A valid `Roll`

can be converted into an open ended iterator via its `into_iter()`

method, providing successive
rolls of the given die roll expression.

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

extern crate d20; use d20::*; fn main() { let v: Vec<Roll> = d20::roll_dice("3d6").unwrap().into_iter().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!(rg >= 1 && rg <= 100);

## Structs

Roll |
Represents the |

RollIterator |
A |

## Enums

DieRollTerm |
Represents an individual term within a die roll expression. Terms can either be numeric
modifiers like |

## Functions

roll_dice |
Evaluates the expression string input as a die roll expression (e.g. 3d6 + 4). The
results are returned in a |

roll_range |
Generates a random number within the specified range. Returns a |