### 11 releases

0.9.10 | Jul 28, 2023 |
---|---|

0.9.9 | May 3, 2021 |

0.9.8 | Apr 12, 2021 |

0.9.1 | Mar 31, 2021 |

#**74** in Game dev

**162** downloads per month

**MIT/Apache**

69KB

1K
SLoC

# About

Parses dice notation and evaluate algebraic manipulation of sets of dice rolls.

This module provides

and `Dice`

structs, which implement `RollSet`

for
converting from strings. It also provides error types directly related to
parsing dice-related strings.`FromStr`

# Examples

## Dice Examples

### Rolling Dice

Creating

from a string literal:`Dice`

`use` `ndm``::`Dice`;`
`let` d6 `=` `"`1d6`"``.``parse``::``<`Dice`>``(``)``.``unwrap``(``)``;`

You can create them directly:

`use` `ndm``::`Dice`;`
`let` d4 `=` `Dice``::`new`(``1``,` `4``)``;`

### Exploding Dice

Creating exploding dice (which roll again when the highest number is rolled):

`use` `ndm``::`Dice`;`
`let` exploding_d20 `=` `"`1d20!`"``.``parse``::``<`Dice`>``(``)``.``unwrap``(``)``;`
`let` exploding_d6 `=` `Dice``::`new_exploding`(``1``,` `6``,` `6``)``;`

Exploding dice can explode on any number greater than 1:

`use` `ndm``::`Dice`;`
`let` exploding_d13 `=` `"`1d13!2`"``.``parse``::``<`Dice`>``(``)``.``unwrap``(``)``;`

### More Complicated Examples

Rolling multiple

at a time:`Dice`

`use` `ndm``::`Dice`;`
`let` dice `=` `Dice``::`new`(``3``,` `8``)``;`
`let` dice `=` `Dice``::`new_exploding`(``2``,` `4``,` `4``)``;`

### Keeping High or Low Rolls

Keeping the three highest dice:

`use` `ndm``::`Dice`;`
`let` wis `=` `Dice``::`new_keep_n`(``4``,` `6``,` `3``)``;`
`let` dex`:` Dice `=` `"`4d6/H3`"``.``parse``(``)``.``unwrap``(``)``;`

Or the lowest roll:

`use` `ndm``::`Dice`;`
`let` disadvantage `=` `Dice``::`new_keep_n`(``2``,` `20``,` `-``1``)``;`
`let` minimum`:` Dice `=` `"`4d7/L1`"``.``parse``(``)``.``unwrap``(``)``;`

(String parsing isn't case-sensitive.)

Keeping exploding dice:

`use` `ndm``::`Dice`;`
`let` dice `=` `Dice``::`new_extended`(``4``,` `7``,` `5``,` `3``)``;`
`//` or
`let` dice `=` `"`4d7/H3!5`"``.``parse``::``<`Dice`>``(``)``.``unwrap``(``)``;`

### Formatting Dice

can be formatted with the normal `Dice`

operator:`{``}`

`use` `ndm``::`Dice`;`
`println!``(``"``{}``"``,` `Dice``::`new`(``2``,` `10``)``.``unwrap``(``)``)``;`

### Parse Errors

Strings which cannot be parsed cause

s. String parsing is more
strict than the constructors, which currently don't fail, but instead ignore
invalid parameters.`DiceParseError`

## Combinations

Sets of dice, such as multiple sizes of dice, and mathematical operations upon
dice, are represented by

s.`RollSet`

s can only be created by parsing string slices:`RollSet`

`use` `ndm``::`RollSet`;`
`let` roll_set`:` RollSet `=` `"`3d6`"``.``parse``(``)``.``unwrap``(``)``;`

s can contain any combinations of valid `RollSet`

and whole numbers,
joined by `Dice`

or `+`

(or −). These combinations can also be multiplied
by floating-point numbers, using `-`

(or `*`

or `x`

or ×).`X`

`use` `ndm``::`RollSet`;`
`let` roll_set`:` RollSet `=` `"`1d20+4`"``.``parse``(``)``.``unwrap``(``)``;`
`let` empowered `=` `"`4d6 * 1.5`"``.``parse``::``<`RollSet`>``(``)``.``unwrap``(``)``;`
`let` sneak `=` `"`3d8 + 2d6`"``.``parse``::``<`RollSet`>``(``)``.``unwrap``(``)``;`

Extraneous text can be included:

`use` `ndm``::`RollSet`;`
`let` roll_set `=` `"`2d8 slashing + 3d6 fire`"``.``parse``::``<`RollSet`>``(``)``.``unwrap``(``)``;`

End-comments can be indicated by

, which will prevent additional parsing:`#`

`use` `ndm``::`RollSet`;`
`//` Only the 4d6 will be parsed, the 8d6 is just a comment.
`let` roll_set`:` RollSet `=` `"`4d6 # 8d6 on a critical`"``.``parse``(``)``.``unwrap``(``)``;`

s can also be formatted using `RollSet`

, and totals will appear before an
end-of-line comment, if any.`{``}`

`use` `ndm``::`RollSet`;`
`//` Prints something like: `3d6 [ 2, 4, 5: 11] slashing + 4 = 15`
`println!``(``"``{}``"``,` `"`3d6 slashing + 4`"``.``parse``::``<`RollSet`>``(``)``.``unwrap``(``)``)``;`
`//` Prints something like `3d6 [ 3, 5, 6: 14] + 4 = 18 # slashing`
`println!``(``"``{}``"``,` `"`3d6+4 # slashing`"``.``parse``::``<`RollSet`>``(``)``.``unwrap``(``)``)``;`

### Parse Errors

Errors are returned using

. In general, `RollParseError`

s treat
anything that isn't `RollSet`

, operators, or numbers as comments, but will fail if
there isn't a roll anywhere in the string. Some combinations of operators are
also invalid: `Dice`

can't be multiplied by other `Dice`

, text can't be added to
numbers, etc.`Dice`

# More Information

Dice math is from left to right, regardless of operator. For example,

ranges from 24 ((4 + 12) * 1.5) to 54 ((24 + 12) * 1.5), not
from 22 to 42.`4d6 + 12 * 1.5`

Addition and subtraction can be done with whole numbers, dice rolls, and results
of previous operations. Multiplication can be done upon all of the above, but
the right hand side must be a number (either whole or floating-point). Also,
the result of floating-point math is truncated:

ranges from 4 to 29,
not from 4.9 to 29.4.`1d6 * 4.9`

Exploding dice get rerolled as long as they roll at least as high as the “fuse” (which defaults to the highest value on the die, but may be as low as 2).

You can construct

directly, or complex expressions of `Dice`

s.`RollSet`

The dice notation parsed by this library is:

[count]

<sides>[`d`

<`/`

|`H`

><keep>][`L`

[fuse]]`!`

is the number of dice to roll, is optional, and defaults to 1`count`

is the number of sides on the dice and is required`sides`- If numeric, it must be non-negative

or`f`

may be used to represent Fudge/Fate dice`F`

- Optionally,

, followed by`/`

(or`H`

) or`h`

(or`L`

) and`l`- a positive number less than or equal to the number of dice rolled

- Optionally,

, optionally followed by the`!`

as a whole number`fuse`- If the fuse is provided, it must be at least 2
- Otherwise, it defaults to the highest possible roll for the die

Dice can be added with

, subtracted with `+`

[or −], or multiplied
with `-`

[or `*`

or `x`

or ×]. Other text is treated as comments.`X`

can be combined with each other by addition or subtraction. You can also
add or subtract whole numbers and multiply results by floating point numbers.
(Division isn't currently supported directly, but you can multiply by the
reciprocal.)`Dice`

# License

Licensed, at your option, under either the Apache License, Version 2.0 or the MIT license.

## Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache License, Version 2.0, shall be dual licensed as above, without any additional terms or conditions.

#### Dependencies

~3–5MB

~91K SLoC