Struct ndm::Dice

pub struct Dice { /* fields omitted */ }

Implementations

impl Dice

pub const COUNT_LIMIT: usize

There’s no compelling reason to roll more than 100 dice at a time. I can’t really see why anyone would want to roll more than about 20 at a time, but 100d6 is a sort of obvious thing for people to do.

pub const SIDES_LIMIT: u16

There’s no good reason to want anything bigger than a d1000. Even that is pushing it, but I can think of games that wanted d1000s for no good reason.

pub fn new(n: usize, m: u16) -> Result<Self, DiceParseError>

Roll (simple) dice. Dice are rolled at creation time and not otherwise modified.

• n is the number of dice and must be non-zero
• m is the number of sides; zero (0) is treated as a request to create Fudge/Fate dice

Dice created this way don’t explode and are all kept.

use ndm::Dice;

// create 1d6
let d6 = Dice::new(1, 6);

pub fn new_exploding(
    count: usize,
    sides: u16,
    fuse: u16
) -> Result<Self, DiceParseError>

Roll “exploding” dice. Dice are rolled at creation time and not otherwise modified.

Any die which is rolls a value greater than or equal to fuse will be added to the total and rolled again.

Dice created this way are all kept.

One-sided dice can’t explode, because if they did, they would never stop. Fudge/Fate dice can’t explode either, because it doesn’t make sense for them to.

use ndm::Dice;

// create 1d6
let d6_explode_5 = Dice::new_exploding(1, 6, 5);

pub fn new_keep_n(
    count: usize,
    sides: u16,
    n: isize
) -> Result<Self, DiceParseError>

Roll dice, adding only the highest or lowest n rolls to the total. Dice are rolled at creation time and not otherwise modified.

If n < 0, the n lowest dice are kept. If n > 0, the n highest dice are kept. If n == 0, all dice are kept.

Dice created this way don’t explode.

use ndm::Dice;

// Roll 4 six-sided dice, keeping the highest 3.
let wis = Dice::new_keep_n(4, 6, 3);
// Roll 2 twenty-sided dice, keeping the lower roll.
let disadvantage = Dice::new_keep_n(2, 20, -1);

pub fn new_extended(
    count: usize,
    sides: u16,
    keep: isize,
    fuse: u16
) -> Result<Self, DiceParseError>

Roll dice which may explode and optionally use some of the dice when calculating the total. Dice are rolled at creation time and not otherwise modified.

If keep < 0, the keep lowest dice are kept. If keep > 0, the keep highest dice are kept. If keep == 0, all dice are kept.

Any die which is rolls a value greater than or equal to fuse will be added to the total and rolled again.

One-sided dice can’t explode, because if they did, they would never stop. Fudge/Fate dice can’t explode either, because it doesn’t make sense for them to.

use ndm::Dice;

// Roll 8 sixteen-sided dice, keeping the highest 3 but exploding on 4 or
// higher.
let dice = Dice::new_extended(8, 16, 3, 4);

pub fn total(&self) -> i32

The net value of this roll (after dropping any dice that weren’t [kept] and adding any that met or exceeded the [fuse]).

pub fn sides(&self) -> u16

The number of sides on the dice. Fate/Fudge dice have zero (0) sides.

pub fn count(&self) -> usize

The number of dice requested. This may differ from the number of dice rolled (as returned by [rolls] and [all_rolls] if any dice exploded (see [fuse]), or if any weren’t kept (see [kept]). This will always be at least one (1).

pub fn rolls(&self) -> &[u16]

The [kept] rolls. This may be less than the number of dice requested if some weren’t kept, or more if some rolls met or exceeded the [fuse]. See [all_rolls] for all dice rolled.

There are two special cases:

• Fudge/Fate dice always return a reference to a Vec of length 3:
  • [0] is the number of minuses or failures
  • [1] is the number of zeroes or neutral results
  • [2] is the number of pluses or successes
• One-sided dice (d1) always return an empty Vec, since they can’t roll anything but a one (1).

Note that neither Fudge/Fate dice nor d1s can “explode”. Also note that for these dice, the [total] is usually the most interesting value.

pub fn all_rolls(&self) -> &Vec<u16>

All dice rolled, including any dice that weren’t [kept] in the total. This may differ from the [count] if any dice met or exceeded the [fuse].

There are two special cases:

• Fudge/Fate dice always return a reference to a Vec of length 3:
  • [0] is the number of minuses or failures
  • [1] is the number of zeroes or neutral results
  • [2] is the number of pluses or successes
• One-sided dice (d1) always return an empty Vec, since they can’t roll anything but a one (1).

Note that neither Fudge/Fate dice nor d1s can “explode”. Also note that for one-sided dice, the [count] and the [total] are usually more useful data.

pub fn fuse(&self) -> u16

The number upon which dice “exploded”, triggering a re-roll. Zero (0) means the dice couldn’t explode.

pub fn exploded(&self) -> bool

Indicates whether any dice actually exploded. This is a utility method as the semantics of measuring how many dice were rolled is not trivially derivable from [all_rolls]. Note that neither Fudge/Fate dice nor d1s can explode.

pub fn kept(&self) -> isize

The number of dice kept when calculating the [total] of this roll.

impl Dice

pub const SIDE_LIMIT: u16

Trait Implementations

impl Clone for Dice

fn clone(&self) -> Dice

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Dice

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Dice

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl Display for Dice

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), FmtError>

The output format for Dice is currently unstable but considered human-readable.

impl FromStr for Dice

type Err = DiceParseError

The associated error which can be returned from parsing.

fn from_str(line: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl PartialEq<Dice> for Dice

fn eq(&self, other: &Dice) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Dice) -> bool

This method tests for !=.

impl Serialize for Dice

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Dice

impl TryFrom<Captures<'_>> for Dice

type Error = DiceParseError

The type returned in the event of a conversion error.

fn try_from(cap: Captures<'_>) -> Result<Self, Self::Error>

Performs the conversion.