doc: add roll 4d6 keep 3 lowest example

01.workspace/Cargo.toml

@@ -1,3 +1,5 @@
 [workspace]
+
 resolver = "3"
+
 members = ["oxidice_lib"]

01.workspace/oxidice_lib/examples/roll_3d6.rs

@@ -0,0 +1,6 @@
+use oxidice_lib::dice::*;
+
+fn main() {
+    let outcome = Handful::grab(3, 6).roll();
+    println!("{outcome}");
+}

01.workspace/oxidice_lib/examples/roll_4D_Fudge.rs

@@ -0,0 +1,7 @@
+use oxidice_lib::dice::*;
+
+fn main() {
+    let roll = Handful::grab_range(4, -1..=1).roll();
+    let sum = roll.clone().sum().unwrap();
+    println!("{} -> {}", roll, sum);
+}

01.workspace/oxidice_lib/examples/roll_4d6_keep_3.rs

@@ -0,0 +1,11 @@
+use oxidice_lib::dice::*;
+
+fn main() {
+    let roll = Handful::grab(4, 6).roll();
+    print!("{roll} -> ");
+    let roll = roll.keep_highest(3).unwrap();
+    print!("{roll} -> ");
+    let roll = roll.sum().unwrap();
+    print!("{roll}");
+    println!();
+}

01.workspace/oxidice_lib/examples/roll_4d6_keep_3_lowest.rs

@@ -0,0 +1,10 @@
+use oxidice_lib::dice::*;
+
+fn main() {
+    let result = Handful::grab(4, 6).roll();
+    print!("{result} -> ");
+    let result = result.keep_lowest(3).unwrap();
+    print!("{result} -> ");
+    let result = result.sum().unwrap();
+    println!("{result}");
+}

01.workspace/oxidice_lib/examples/roll_d20_with_advantage.rs

@@ -0,0 +1,7 @@
+use oxidice_lib::dice::*;
+
+fn main() {
+    let roll_result = Handful::grab(2, 20).roll();
+    let result = roll_result.clone().max().unwrap();
+    println!("{} -> {}", roll_result, result);
+}

01.workspace/oxidice_lib/examples/roll_d20_with_disadvantage.rs

@@ -0,0 +1,7 @@
+use oxidice_lib::dice::*;
+
+fn main() {
+    let roll_result = Handful::grab(2, 20).roll();
+    let result = roll_result.clone().min().unwrap();
+    println!("{} -> {}", roll_result, result);
+}

01.workspace/oxidice_lib/examples/roll_exploding_d6.rs

@@ -0,0 +1,6 @@
+use oxidice_lib::dice::*;
+
+fn main() {
+    let roll = Handful::grab_exploding(1, 6, 6).roll();
+    println!("{roll}");
+}

01.workspace/oxidice_lib/examples/roll_ose_stats.rs

@@ -1,17 +1,16 @@
 use oxidice_lib::dice::*;
 
-fn main() -> Result<(), FailedTo>{
-    let str = Dice::grab(3, 6).roll().sum()?;
-    let int = Dice::grab(3, 6).roll().sum()?;
-    let wis = Dice::grab(3, 6).roll().sum()?;
-    let dex = Dice::grab(3, 6).roll().sum()?;
-    let con = Dice::grab(3, 6).roll().sum()?;
-    let cha = Dice::grab(3, 6).roll().sum()?;
-    println!("STR: {str}");
-    println!("INT: {int}");
-    println!("WIS: {wis}");
-    println!("DEX: {dex}");
-    println!("CON: {con}");
-    println!("CHA: {cha}");
-    Ok(())
+fn main() {
+    let str = Handful::grab(3, 6).roll().sum().unwrap();
+    let int = Handful::grab(3, 6).roll().sum().unwrap();
+    let wis = Handful::grab(3, 6).roll().sum().unwrap();
+    let dex = Handful::grab(3, 6).roll().sum().unwrap();
+    let con = Handful::grab(3, 6).roll().sum().unwrap();
+    let cha = Handful::grab(3, 6).roll().sum().unwrap();
+    println!("STR: {}", str);
+    println!("INT: {}", int);
+    println!("WIS: {}", wis);
+    println!("DEX: {}", dex);
+    println!("CON: {}", con);
+    println!("CHA: {}", cha);
 }

01.workspace/oxidice_lib/src/imp/dice_grab.rs

@@ -1,20 +0,0 @@
-use crate::*;
-
-impl Dice {
-    pub fn grab(dice: u16, sides: u16) -> Self {
-        let mut handful = Vec::<Die>::new();
-        for _ in 1..=dice {
-            handful.push(Die::new(sides));
-        }
-        Self {
-            handful,
-            roll_results: Vec::<u16>::new(),
-        }
-    }
-    pub fn and_grab(mut self, dice: u16, sides: u16) -> Self {
-        for _ in 1..=dice {
-            self.handful.push(Die::new(sides));
-        }
-        self
-    }
-}

01.workspace/oxidice_lib/src/imp/dice_roll.rs

@@ -1,11 +0,0 @@
-use crate::*;
-
-impl Dice {
-    pub fn roll(mut self) -> Self {
-        self.roll_results.clear();
-        for die in &self.handful {
-            self.roll_results.push(die.roll())
-        }
-        self
-    }
-}

01.workspace/oxidice_lib/src/imp/dice_sum.rs

@@ -1,16 +0,0 @@
-use crate::*;
-
-impl Dice {
-    pub fn sum(self) -> Result<Sum, FailedTo> {
-        let mut result = Sum::default();
-        for roll_result in self.roll_results {
-            result.roll_results.push(roll_result);
-            result.sum = result
-                .sum
-                .checked_add(roll_result.into())
-                .and_then(|r| r.checked_add(1u64))
-                .ok_or(FailedTo::Sum)?;
-        }
-        Ok(result)
-    }
-}

01.workspace/oxidice_lib/src/imp/die_roll.rs

@@ -1,11 +1,47 @@
 use crate::*;
+use std::ops::*;
+
+fn roll_sides(sides: u16) -> Vec<i32> {
+    let mut rng = rand::rng();
+    vec![rng.random_range(1..=sides as i32)]
+}
+
+fn roll_range(range: RangeInclusive<i32>) -> Vec<i32> {
+    let mut rng = rand::rng();
+    vec![rng.random_range(range)]
+}
+
+fn roll_exploding(sides: u16, threshold: i32) -> Vec<i32> {
+    let mut rng = rand::rng();
+    let mut results = Vec::<i32>::new();
+    loop {
+        let result: i32 = rng.random_range(1..=sides as i32);
+        results.push(result);
+        if result < threshold {
+            break;
+        }
+    }
+    results
+}
 
 impl Die {
-    pub fn roll(&self) -> u16 {
-        let mut rng = rand::rng();
-        rng.random_range(0..self.sides)
+    pub fn roll(&self) -> Vec<i32> {
+        match self {
+            Die::Exploding(sides, threshold) => roll_exploding(*sides, *threshold),
+            Die::Range(range) => roll_range(range.clone()),
+            Die::Sides(sides) => roll_sides(*sides),
+        }
     }
 }
 
-// #[cfg(test)]
-// mod unit_tests { use super::*; }
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn check_roll_range() {
+        let die = Die::Range(5..=5);
+        for _ in 1..=1000 {
+            assert_eq!(die.roll(), [5]);
+        }
+    }
+}

01.workspace/oxidice_lib/src/imp/handful_grab.rs

@@ -0,0 +1,26 @@
+use crate::*;
+use std::ops::*;
+
+impl Handful {
+    pub fn grab(dice_num: u16, sides: u16) -> Self {
+        let mut dice = Vec::<Die>::new();
+        for _ in 1..=dice_num {
+            dice.push(Die::Sides(sides));
+        }
+        Self { dice }
+    }
+    pub fn grab_range(dice_num: u16, range: RangeInclusive<i32>) -> Self {
+        let mut dice = Vec::<Die>::new();
+        for _ in 1..=dice_num {
+            dice.push(Die::Range(range.clone()));
+        }
+        Self { dice }
+    }
+    pub fn grab_exploding(dice_num: u16, sides: u16, threshold: i32) -> Self {
+        let mut dice = Vec::<Die>::new();
+        for _ in 1..=dice_num {
+            dice.push(Die::Exploding(sides, threshold));
+        }
+        Self { dice }
+    }
+}

01.workspace/oxidice_lib/src/imp/handful_roll.rs

@@ -0,0 +1,14 @@
+use crate::*;
+
+impl Handful {
+    pub fn roll(self) -> Outcome {
+        let mut die_rolls = Vec::<i32>::new();
+        for die in self.dice {
+            die_rolls.append(&mut die.roll());
+        }
+        Outcome::List(die_rolls)
+    }
+}
+
+// #[cfg(test)]
+// mod unit_tests { use super::*; }

01.workspace/oxidice_lib/src/imp/mod.rs

@@ -1,5 +1,8 @@
-pub mod dice_grab;
-pub mod dice_roll;
-pub mod dice_sum;
 pub mod die_roll;
-pub mod sum_display;
+pub mod handful_grab;
+pub mod handful_roll;
+pub mod outcome_keep_highest;
+pub mod outcome_keep_lowest;
+pub mod outcome_max;
+pub mod outcome_min;
+pub mod outcome_sum;

01.workspace/oxidice_lib/src/imp/outcome_keep_highest.rs

@@ -0,0 +1,22 @@
+use crate::*;
+use std::cmp::*;
+
+impl Outcome {
+    pub fn keep_highest(self, dice_num: u16) -> Result<Outcome, FailedTo> {
+        if dice_num == 0 {
+            return Err(FailedTo::ProcessInput);
+        }
+        match self {
+            Outcome::Scalar(value) => Ok(Outcome::List(vec![value])),
+            Outcome::List(mut values) => {
+                values.sort_by_key(|&num| Reverse(num));
+                Ok(Outcome::List(
+                    values.into_iter().take(dice_num as usize).collect(),
+                ))
+            }
+        }
+    }
+}
+
+// #[cfg(test)]
+// mod unit_tests { use super::*; }

01.workspace/oxidice_lib/src/imp/outcome_keep_lowest.rs

@@ -0,0 +1,21 @@
+use crate::*;
+
+impl Outcome {
+    pub fn keep_lowest(self, dice_num: u16) -> Result<Outcome, FailedTo> {
+        if dice_num == 0 {
+            return Err(FailedTo::ProcessInput);
+        }
+        match self {
+            Outcome::Scalar(value) => Ok(Outcome::List(vec![value])),
+            Outcome::List(mut values) => {
+                values.sort();
+                Ok(Outcome::List(
+                    values.into_iter().take(dice_num as usize).collect(),
+                ))
+            }
+        }
+    }
+}
+
+// #[cfg(test)]
+// mod unit_tests { use super::*; }

01.workspace/oxidice_lib/src/imp/outcome_max.rs

@@ -0,0 +1,41 @@
+use crate::*;
+
+fn max_of(values: Vec<i32>) -> Result<Outcome, FailedTo> {
+    if values.is_empty() {
+        return Err(FailedTo::ProcessInput);
+    }
+    let ret = Ok(Outcome::Scalar(i32::MIN));
+    ret.and_then(|_| {
+        values
+            .iter()
+            .max()
+            .ok_or(FailedTo::FindMax)
+            .map(|min| Outcome::Scalar(*min))
+    })
+}
+
+impl Outcome {
+    pub fn max(self) -> Result<Outcome, FailedTo> {
+        match self {
+            Outcome::Scalar(value) => Ok(Outcome::Scalar(value)),
+            Outcome::List(values) => max_of(values),
+        }
+    }
+}
+
+#[cfg(test)]
+mod unit_tests {
+    use super::*;
+    #[test]
+    fn check_max() {
+        let outcome = Handful::grab(2, 20).roll();
+        let max = outcome.clone().max().unwrap();
+        match outcome {
+            Outcome::List(values) => {
+                let expected_max = values.iter().max().unwrap();
+                assert_eq!(max, Outcome::Scalar(*expected_max));
+            }
+            _ => panic!("outcome is not a list"),
+        }
+    }
+}

01.workspace/oxidice_lib/src/imp/outcome_min.rs

@@ -0,0 +1,40 @@
+use crate::*;
+
+fn min_of(values: Vec<i32>) -> Result<Outcome, FailedTo> {
+    if values.is_empty() {
+        return Err(FailedTo::ProcessInput);
+    }
+    Ok(Outcome::Scalar(i32::MIN)).and_then(|_| {
+        values
+            .iter()
+            .min()
+            .ok_or(FailedTo::FindMin)
+            .map(|min| Outcome::Scalar(*min))
+    })
+}
+
+impl Outcome {
+    pub fn min(self) -> Result<Outcome, FailedTo> {
+        match self {
+            Outcome::Scalar(value) => Ok(Outcome::Scalar(value)),
+            Outcome::List(values) => min_of(values),
+        }
+    }
+}
+
+#[cfg(test)]
+mod unit_tests {
+    use super::*;
+    #[test]
+    fn check_min() {
+        let roll_result = Handful::grab(2, 20).roll();
+        let min_result = roll_result.clone().min().unwrap();
+        match roll_result {
+            Outcome::List(values) => {
+                let min = values.iter().min().unwrap();
+                assert_eq!(min_result, Outcome::Scalar(*min));
+            }
+            _ => panic!("result is not a list"),
+        }
+    }
+}

01.workspace/oxidice_lib/src/imp/outcome_sum.rs

@@ -0,0 +1,37 @@
+use crate::*;
+
+fn sum_of(values: Vec<i32>) -> Result<Outcome, FailedTo> {
+    if values.is_empty() {
+        return Ok(Outcome::Scalar(0));
+    }
+    let mut ret = Ok(Outcome::Scalar(0));
+    for value in values {
+        ret = ret.and_then(|outcome: Outcome| match outcome {
+            Outcome::List(_) => Err(FailedTo::ProcessInput),
+            Outcome::Scalar(acc) => acc
+                .checked_add(value)
+                .map(|new_acc: i32| Outcome::Scalar(new_acc))
+                .ok_or(FailedTo::SumValues),
+        })
+    }
+    ret
+}
+
+impl Outcome {
+    pub fn sum(self) -> Result<Outcome, FailedTo> {
+        match self {
+            Outcome::Scalar(value) => Ok(Outcome::Scalar(value)),
+            Outcome::List(values) => sum_of(values),
+        }
+    }
+}
+
+#[cfg(test)]
+mod unit_tests {
+    use super::*;
+    #[test]
+    fn check_sum() {
+        let outcome = Handful::grab(5, 1).roll().sum();
+        assert_eq!(outcome, Ok(Outcome::Scalar(5)));
+    }
+}

01.workspace/oxidice_lib/src/imp/sum_display.rs

@@ -1,17 +0,0 @@
-use crate::*;
-
-impl fmt::Display for Sum {
-    fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
-        let str_results: Vec<String> = self
-            .roll_results
-            .iter()
-            .map(|r| r.checked_add(1))
-            .map(|o| o.unwrap_or(0))
-            .map(|r| r.to_string())
-            .collect();
-        write!(f, "[{}]", str_results.join(", "))?;
-        write!(f, " -> ")?;
-        write!(f, "{}", self.sum)?;
-        Ok(())
-    }
-}

01.workspace/oxidice_lib/src/lib.rs

@@ -1,6 +1,5 @@
-use std::*;
-
 use rand::*;
+use std::*;
 
 mod fun;
 mod imp;
@@ -9,13 +8,12 @@ mod str;
 mod trt;
 mod tst;
 
-pub(crate) use crate::str::dice::O as Dice;
-pub(crate) use crate::str::die::O as Die;
+pub(crate) use crate::str::die::E as Die;
 pub(crate) use crate::str::failed_to::E as FailedTo;
-pub(crate) use crate::str::sum::O as Sum;
+pub(crate) use crate::str::handful::O as Handful;
+pub(crate) use crate::str::outcome::E as Outcome;
 
 pub mod dice {
-    pub use crate::str::dice::O as Dice;
-    pub use crate::str::sum::O as Sum;
-    pub use crate::str::failed_to::E as FailedTo;
+    pub use crate::str::handful::O as Handful;
+    pub use crate::str::outcome::E as Outcome;
 }

01.workspace/oxidice_lib/src/str/dice.rs

@@ -1,18 +0,0 @@
-use crate::*;
-
-#[derive(Debug, Default, PartialEq, Clone)]
-pub struct O {
-    pub(crate) handful: Vec<Die>,
-    pub(crate) roll_results: Vec<u16>,
-}
-
-// impl std::fmt::Display for O {
-// fn fmt(&self, _f: &mut std::fmt::Formatter) -> Result<(), std::fmt::Error> {
-// todo!();
-// }
-// }
-
-// #[cfg(test)]
-// mod unit_tests {
-// use super::*;
-// }

01.workspace/oxidice_lib/src/str/die.rs

@@ -1,12 +1,54 @@
 use crate::*;
+use std::ops::*;
+// use std::fmt::Display;
+// use std::str::FromStr;
 
-#[derive(Debug, Default, PartialEq, Clone)]
-pub struct O {
-    pub(crate) sides: u16,
+#[derive(Debug, PartialEq, Eq, Clone, Hash)]
+pub enum E {
+    Exploding(u16, i32),
+    Range(RangeInclusive<i32>),
+    Sides(u16),
 }
 
-impl Die {
-    pub fn new(sides: u16) -> Self {
-        Self { sides }
-    }
-}
+// impl Display for E {
+// fn fmt(&self, f: &mut std::fmt::Formatter) -> std::result::Result<(), std::fmt::Error> {
+// match self {
+// Self::NoValue => write!(f, "NoValue"),
+// }
+// }
+// }
+
+// impl FromStr for E {
+// type Err = Box<dyn std::error::Error>;
+// fn from_str(value: &str) -> std::result::Result<Self, Box<dyn std::error::Error>> {
+// match value {
+// "NoValue" => Ok(Self::NoValue),
+// _ => unreachable!(),
+// }
+// }
+// }
+
+// #[cfg(test)]
+// mod unit_tests {
+// use super::*;
+// #[test]
+// fn check_001() {
+// for value in [E::NoValue] {
+// match value {
+// E::NoValue => assert_eq!(
+// E::NoValue,
+// E::from_str("NoValue").unwrap()
+// ),
+// }
+// }
+// }
+//
+// #[test]
+// fn check_002() {
+// for value in [E::NoValue] {
+// match value {
+// E::NoValue => assert_eq!(&E::NoValue.to_string(), "NoValue"),
+// }
+// }
+// }
+// }

01.workspace/oxidice_lib/src/str/failed_to.rs

@@ -4,7 +4,10 @@
 
 #[derive(Debug, PartialEq, PartialOrd, Eq, Ord, Clone, Copy, Hash)]
 pub enum E {
-    Sum,
+    FindMax,
+    FindMin,
+    ProcessInput,
+    SumValues,
 }
 
 // impl Display for E {

01.workspace/oxidice_lib/src/str/handful.rs

@@ -2,8 +2,7 @@ use crate::*;
 
 #[derive(Debug, Default, PartialEq, Clone)]
 pub struct O {
-    pub(crate) roll_results: Vec<u16>,
-    pub(crate) sum: u64,
+    pub(crate) dice: Vec<Die>,
 }
 
 // impl std::fmt::Display for O {

01.workspace/oxidice_lib/src/str/mod.rs

@@ -1,4 +1,4 @@
-pub mod dice;
 pub mod die;
 pub mod failed_to;
-pub mod sum;
+pub mod handful;
+pub mod outcome;

01.workspace/oxidice_lib/src/str/outcome.rs

@@ -0,0 +1,60 @@
+use crate::*;
+use std::fmt::Display;
+// use std::str::FromStr;
+
+#[derive(Debug, PartialEq, PartialOrd, Eq, Ord, Clone, Hash)]
+pub enum E {
+    Scalar(i32),
+    List(Vec<i32>),
+}
+
+impl Display for E {
+    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::result::Result<(), std::fmt::Error> {
+        match self {
+            Self::Scalar(value) => write!(f, "{}", value),
+            Self::List(value) => {
+                let str_list = value
+                    .iter()
+                    .map(|item| item.to_string())
+                    .collect::<Vec<String>>()
+                    .join(", ");
+                write!(f, "[{}]", str_list)
+            }
+        }
+    }
+}
+
+// impl FromStr for E {
+// type Err = Box<dyn std::error::Error>;
+// fn from_str(value: &str) -> std::result::Result<Self, Box<dyn std::error::Error>> {
+// match value {
+// "NoValue" => Ok(Self::NoValue),
+// _ => unreachable!(),
+// }
+// }
+// }
+
+// #[cfg(test)]
+// mod unit_tests {
+// use super::*;
+// #[test]
+// fn check_001() {
+// for value in [E::NoValue] {
+// match value {
+// E::NoValue => assert_eq!(
+// E::NoValue,
+// E::from_str("NoValue").unwrap()
+// ),
+// }
+// }
+// }
+//
+// #[test]
+// fn check_002() {
+// for value in [E::NoValue] {
+// match value {
+// E::NoValue => assert_eq!(&E::NoValue.to_string(), "NoValue"),
+// }
+// }
+// }
+// }

01.workspace/oxidice_lib/src/tst/dice_grab.rs

@@ -1,28 +0,0 @@
-#[cfg(test)]
-mod tests {
-    use crate::*;
-    #[test]
-    pub fn grab_should_set_correct_number_of_dice() {
-        let dice = Dice::grab(3, 6);
-        assert_eq!(dice.handful.len(), 3);
-    }
-    #[test]
-    pub fn grab_should_set_correct_number_of_sides() {
-        let dice = Dice::grab(3, 6);
-        for idx in 0..=2 {
-            assert_eq!(dice.handful[idx].sides, 6);
-        }
-    }
-    #[test]
-    fn and_grab_should_add_correct_number_of_dice() {
-        let dice = Dice::grab(3, 6).and_grab(2, 8);
-        assert_eq!(dice.handful.len(), 5);
-    }
-    #[test]
-    fn and_grab_should_set_correct_number_of_sides() {
-        let dice = Dice::grab(3, 6).and_grab(2, 8);
-        for idx in 3..4 {
-            assert_eq!(dice.handful[idx].sides, 8);
-        }
-    }
-}

01.workspace/oxidice_lib/src/tst/dice_roll.rs

@@ -1,15 +0,0 @@
-#[cfg(test)]
-mod tests {
-    use crate::*;
-    #[test]
-    pub fn roll_should_yield_correct_number_or_results() {
-        let dice = Dice::grab(3, 6);
-        let dice = dice.roll();
-        assert_eq!(dice.roll_results.len(), 3);
-    }
-    #[test]
-    fn reroll_should_yield_correct_number_of_results() {
-        let dice = Dice::grab(3, 6).roll().roll();
-        assert_eq!(dice.roll_results.len(), 3);
-    }
-}

01.workspace/oxidice_lib/src/tst/dice_sum.rs

@@ -1,16 +0,0 @@
-#[cfg(test)]
-mod tests {
-    use crate::*;
-    #[test]
-    pub fn dice_sum_should_yield_the_correct_sum() {
-        let result = Dice::grab(6, 1).roll().sum().unwrap();
-        assert_eq!(result.sum, 6);
-    }
-    #[test]
-    fn dice_sum_should_list_the_correct_results() {
-        let result = Dice::grab(6, 1).roll().sum().unwrap();
-        for idx in 1..6 {
-            assert_eq!(result.roll_results[idx], 0);
-        }
-    }
-}

01.workspace/oxidice_lib/src/tst/die_roll.rs

@@ -1,11 +0,0 @@
-#[cfg(test)]
-mod tests {
-    use crate::*;
-    #[test]
-    pub fn die_roll_should_always_stay_inside_range() {
-        let die = Die::new(6);
-        for _ in 1..=10000 {
-            assert!(die.roll() < 6);
-        }
-    }
-}

01.workspace/oxidice_lib/src/tst/mod.rs

@@ -1,5 +1 @@
-pub mod dice_grab;
-pub mod dice_roll;
-pub mod dice_sum;
-pub mod die_roll;
-pub mod sum_display;
+

01.workspace/oxidice_lib/src/tst/sum_display.rs

@@ -1,9 +0,0 @@
-#[cfg(test)]
-mod tests {
-    use crate::*;
-    #[test]
-    pub fn sum_display_format_should_be_correct() {
-        let result = Dice::grab(3, 1).roll().sum().unwrap();
-        assert_eq!(&result.to_string(), "[1, 1, 1] -> 3");
-    }
-}