1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

//##################################################################################################
//! A collection of tools to emulate dice and dice rolls.
//##################################################################################################


//##################################################################################################
//************************************* MODULES AND RE-EXPORTS *************************************
//##################################################################################################


pub mod dice_collection;
pub mod value_die;
pub mod numeric_die;


//==================================================================================================


pub use self::numeric_die::NumericDie;
pub use self::value_die::ValueDie;
pub use self::dice_collection::DiceCollection;


//##################################################################################################
//********************************************** TRAITS ********************************************
//##################################################################################################


//==================================================================================================
/// An abstraction representing a die. All dice implement this trait.
//--------------------------------------------------------------------------------------------------
/// Any object implementing Die may be rolled to randomly choose a new value for the object from a
/// predetermined set of values. The value of the Die may be read at any time, including before 
/// being rolled for the first time.
//==================================================================================================
pub trait Die {


    //==============================================================================================
    /// The type of value the die may have.
    //==============================================================================================

    type ValueType;                


    //==============================================================================================
    /// Randomize the value of the die, selecting from the values specified at die construction.
    ///
    //----------------------------------------------------------------------------------------------
    /// ##### Return value
    /// A mutable reference to the Die
    //----------------------------------------------------------------------------------------------
    /// # Examples
    ///
    /// ```
    /// # extern crate ezra;
    /// # fn main() {
    /// use ezra::dice::{Die,NumericDie};
    ///
    /// // Construct a standard six sided die
    /// let mut die = NumericDie::new(1, 1, 6, None);
    ///
    /// // Randomize the value of the die
    /// die.roll();
    ///
    /// let value = die.get_value();
    /// assert!(1 <= value && value <= 6); 
    /// # }
    /// ```
    //----------------------------------------------------------------------------------------------
    /// Since the roll method returns a reference to itself, you may chain die methods together.
    ///
    /// ```
    /// # extern crate ezra;
    /// # fn main() {
    /// # use ezra::dice::{Die,NumericDie};
    /// let mut die = NumericDie::new(1, 1, 6, None);
    ///
    /// // Roll the die three times and print its value
    /// println!("After three rolls the die has value {}.", die.roll().roll().roll().get_value());
    /// # }
    /// ```
    //==============================================================================================

    fn roll(&mut self) -> &mut Self;


    //==============================================================================================
    /// Obtain a copy of the current value of the die.
    ///
    //----------------------------------------------------------------------------------------------
    /// ##### Return value
    /// A copy of the current value of the die
    //----------------------------------------------------------------------------------------------
    /// # Examples
    /// ```
    /// # extern crate ezra;
    /// # fn main() {
    /// use ezra::dice::{Die,NumericDie};
    ///
    /// // Construct a standard six sided die
    /// let mut die = NumericDie::new(1, 1, 6, None);
    ///
    /// die.roll();
    ///
    /// println!("The value of the die is {}.", die.get_value());
    /// # }
    //==============================================================================================

    fn get_value(&self) -> Self::ValueType; 


    //==============================================================================================
    /// Obtain a vector of all possile values the die may take.
    ///
    //----------------------------------------------------------------------------------------------
    /// ##### Return value
    /// A vector of all possible values the die may have
    //----------------------------------------------------------------------------------------------
    /// # Examples
    /// ```
    /// # extern crate ezra;
    /// # fn main() {
    /// use ezra::dice::{Die,NumericDie};
    ///
    /// // Construct a standard six sided die
    /// let die = NumericDie::new(1, 1, 6, None);
    ///
    /// assert_eq!(die.values(), vec![1, 2, 3, 4, 5, 6])
    /// # }
    //==============================================================================================

    fn values(&self) -> Vec<Self::ValueType>;
}