From aad0d407c353cd88772e2c85c9d3ca7eb0163144 Mon Sep 17 00:00:00 2001 From: Dan Rhea Date: Sun, 11 Apr 2021 16:29:00 -0400 Subject: [PATCH] 1.0.1.0 - Added comments and documented code (still WIP) --- DiceAPI/Controllers/DiesController.cs | 223 ++++++++++++++------------ DiceAPI/Dice.cs | 33 +++- DiceAPI/DiceAPI.csproj | 7 +- DiceAPI/Die.cs | 42 ++++- DiceAPI/Models/Dies.cs | 3 + DiceAPI/Models/DiesContext.cs | 3 + 6 files changed, 199 insertions(+), 112 deletions(-) diff --git a/DiceAPI/Controllers/DiesController.cs b/DiceAPI/Controllers/DiesController.cs index 769696c..edf4d37 100644 --- a/DiceAPI/Controllers/DiesController.cs +++ b/DiceAPI/Controllers/DiesController.cs @@ -10,14 +10,13 @@ namespace DiceAPI.Controllers public class DiesController : ControllerBase { - //private readonly DiesContext _context; - //private readonly CultureInfo culture = new CultureInfo("en-US"); - - //public DiesController(DiesContext context) - //{ - // _context context; - //} - + /// + /// Create an roll dice and return the result. + /// + /// int: Number of dice to "throw" + /// int: Number of sides on a die + /// int: Adjustment to apply to the total result + /// ActionResult: List of Dies (one record in this case) [HttpGet("qty/{qty}/sides/{sides}/adj/{adj}")] public ActionResult GetDies(int qty, int sides, int adj) { @@ -48,10 +47,17 @@ public ActionResult GetDies(int qty, int sides, int adj) return Ok(Dice[Dice.Count - 1]); } + /// + /// Take a dice notation string to determine what dice we need to + /// throw + /// + /// string: Dice notation string (quantityDsides[[+|-}adjustment], + /// ie 1D6+1) + /// ActionResult: List of Dies (one record in this case) [HttpGet("dand/{cmd}")] public ActionResult GetDandD(string cmd) { - int Quantity = 0; // Default 1D6 + int Quantity = 0; // Default 1D6 int Sides = 6; int Adjustment = 0; List Dice = new(); // List to hold return @@ -74,7 +80,7 @@ public ActionResult GetDandD(string cmd) dies.Sides = Sides; dies.Result = AResult; - // Dump into a list so it can be serialized json + // Dump into a list so it can be serialized by json Dice.Add(dies); } catch (Exception e) @@ -88,120 +94,129 @@ public ActionResult GetDandD(string cmd) return Ok(Dice[Dice.Count - 1]); } + /// + /// Parse the nDx[[+|-]n] dice notation string and return Quantity, Sides and + /// Adjustment by reference to the caller + /// + /// string: Dice notation to be parsed + /// int; The number of dice to roll (1:1000) + /// int: The number of side a die has (0:1000) (0 allows for + /// a special case "coin flip" mode that returns 0 or 1) + /// int: Adjustment that is applied to the total result + /// of the dice throws private void Parse(string arg, ref int Quantity, ref int Sides, ref int Adjustment) { string arrg = arg.Trim().ToUpper(); string[] parm1 = { "D" }; //Dies/sides delimiter string[] parm2 = { "+", "-" }; //Adjustment delimiter - switch (arg) + + // Parse individual dice roll command or default to 1d6+0 + + // No arguments, use 1D6 default + if (arrg.Length == 0) + { + Quantity = 1; + Sides = 6; + Adjustment = 0; + return; + } + + // We started with a D (implies a singlr die) + if (arrg.StartsWith("D")) + { + // Just a "D"? Default with 1D6+0 + if (arrg.Length == 1) + { + Quantity = 1; + Sides = 6; + Adjustment = 0; + return; + } + //More to do here... default to one die and continue + Quantity = 1; + arrg = arrg.Substring(1, arrg.Length - 1); + } + else { + //Didn't start with a "D" split using "D" as a delimiter. The first argument + //should be the die count + string[] ary = arrg.Split(parm1, StringSplitOptions.RemoveEmptyEntries); + string sside = ary[0]; + try + { + Quantity = Convert.ToInt32(sside); + } + catch + { + // Default to one die if dice count is bad + Quantity = 1; + } + if (ary.Length == 1) + { + // Only die count, default to 6 sides die with no adjustment + Sides = 6; + Adjustment = 0; + return; + } + // More to do after "D", pass it along + arrg = ary[1]; + } - default: //Parse individual dice roll command or default to 1d6+0 - if (arrg.Length == 0) + // Split the remaining parts using "+" or "-" as a delimiter + string[] ary2 = arrg.Split(parm2, StringSplitOptions.RemoveEmptyEntries); + if (ary2.Length == 1) + { + // We only got a single result which should be the number of sides + // on the die with no adjustment + try + { + Sides = Convert.ToInt32(ary2[0]); + } + catch + { + // Default to 6 sides if value is bogus + Sides = 6; + } + Adjustment = 0; + } + else + { + // More than a single result, should have die side count and adjustment + if (ary2.Length > 1) + { + try { - Quantity = 1; - Sides = 6; - Adjustment = 0; - break; + Sides = Convert.ToInt32(ary2[0]); } - if (arrg.StartsWith("D")) + catch { - //Does the command start with "D" - if (arrg.Length == 1) - { - Quantity = 1; - Sides = 6; - Adjustment = 0; - break; - } - else - { - //More to do here, default to one die - Quantity = 1; - arrg = arrg.Substring(1, arrg.Length - 1); - } + // Thisis so a bogus adjustment will default to a 6 sided die + Sides = 6; } - else + try { - //Didn't start with a "D" split using "D" as a delimiter. The first argument - //should be the die count - string[] ary = arrg.Split(parm1, StringSplitOptions.RemoveEmptyEntries); - string sside = ary[0]; - try - { - Quantity = Convert.ToInt32(sside); - } - catch - { - Quantity = 1; - } - if (ary.Length == 1) - { - // Only die count, default to 6 sides die with no adjustment - Sides = 6; - Adjustment = 0; - break; - } - else - { - //More to do after "D", pass it along - arrg = ary[1]; - } + Adjustment = Convert.ToInt32(ary2[1]); } - //Split the remaining parts using "+" or "-" as a delimiter - string[] ary2 = arrg.Split(parm2, StringSplitOptions.RemoveEmptyEntries); - if (ary2.Length == 1) + catch { - //We only got a single result which should be the number of sides - //on the die with no adjustment - try - { - Sides = Convert.ToInt32(ary2[0]); - } - catch - { - Sides = 6; - } + // This is so a bogus adjustment will default to 0 adjustment Adjustment = 0; } - else + if (Adjustment > 0) { - //More than a single result, should have die side count and adjustment - if (ary2.Length > 1) - { - try - { - Sides = Convert.ToInt32(ary2[0]); - } - catch - { - Sides = 6; - } - try - { - Adjustment = Convert.ToInt32(ary2[1]); - } - catch - { - Adjustment = 0; - } - if (Adjustment > 0) - { - if (arrg.Contains("-")) - { - //if the delimiter was a "-", negate the adjustment - Adjustment = 0 - Adjustment; - } - } - } - if (ary2.Length <= 0) + if (arrg.Contains("-")) { - //Nothing to see here, default six sided die and no adjustment - Sides = 6; - Adjustment = 0; + // if the delimiter was a "-", negate the adjustment + Adjustment = 0 - Adjustment; } } - break; + } + if (ary2.Length <= 0) + { + // Nothing to see here, default six sided die and no adjustment + Sides = 6; + Adjustment = 0; + } } } } diff --git a/DiceAPI/Dice.cs b/DiceAPI/Dice.cs index a485e49..6693d5b 100644 --- a/DiceAPI/Dice.cs +++ b/DiceAPI/Dice.cs @@ -3,14 +3,20 @@ namespace DiceAPI { + /// + /// Create and throw multiple dice using die class + /// class Dice { public List DiceCup = new(); // A nice list object to hold our dies private int _Quantity; // 1 to 1000 dies - private int _Sides; // 0 to 1000 sides (0 side is for a 1 or 0 coin toss) + private int _Sides; // 1 to 1000 sides (1 side is for a 1 or 0 coin toss) private int _Adjustment; // Value to add to the sum of our results + /// + /// Default constructor throws a singler 6 sides die + /// public Dice() { // Default to 1D6+0 @@ -22,6 +28,14 @@ public Dice() DiceCup.Add(ADie); } + /// + /// Constructor overload + /// Rolls 1 to 1000 dies (dice) with 0 to 1000 sides with an sdjustment to the + /// total result. + /// + /// int: 1 to 1000 dice + /// int: 1 to 1000 sides + /// int: Adjustment to total result public Dice(int DiceQuantity, int DiceSides, int DiceAdjustment) { // Up to 1000 dies at a time @@ -34,13 +48,13 @@ public Dice(int DiceQuantity, int DiceSides, int DiceAdjustment) throw new Exception("Dice error: " + DiceQuantity.ToString() + " dies is out of range (1:1000)."); } // Up to 1000 sides on a die - if (DiceSides >= 0 && DiceSides <= 1000) + if (DiceSides >= 1 && DiceSides <= 1000) { Sides = DiceSides; } else { - throw new Exception("Dice error: " + DiceSides.ToString() + " die sides is out of range (0:1000)."); + throw new Exception("Dice error: " + DiceSides.ToString() + " die sides is out of range (1:1000)."); } Adjustment = DiceAdjustment; //List DiceCup = new() { }; @@ -66,6 +80,10 @@ public Dice(int DiceQuantity, int DiceSides, int DiceAdjustment) } } + /// + /// Get and return the total throw results and adjust + /// + /// int: Adjusted sum of all throws public int Results() { int Sum = 0; @@ -76,18 +94,27 @@ public int Results() return Sum + Adjustment; } + /// + /// Dice Quantity (1:1000) + /// public int Quantity { get => _Quantity; set => _Quantity = value; } + /// + /// Dice Sides (1:1000) + /// public int Sides { get => _Sides; set => _Sides = value; } + /// + /// Dice Adjustment (MinInt:MaxInt) + /// public int Adjustment { get => _Adjustment; diff --git a/DiceAPI/DiceAPI.csproj b/DiceAPI/DiceAPI.csproj index 2884716..7e8fcf7 100644 --- a/DiceAPI/DiceAPI.csproj +++ b/DiceAPI/DiceAPI.csproj @@ -1,7 +1,12 @@ - + net5.0 + 1.0.1.0 + Dan Rhea + DiceAPI + A dice rolling API + Copyright 2021 by Dan Rhea diff --git a/DiceAPI/Die.cs b/DiceAPI/Die.cs index e680910..0eb96f4 100644 --- a/DiceAPI/Die.cs +++ b/DiceAPI/Die.cs @@ -2,14 +2,23 @@ namespace DiceAPI { + /// + /// Create and throw a die + /// class Die { + // Pseudo random number generator private readonly Random Chance = new(); - private int _Id; - private int _Sides; - private int _Result; + private int _Id; // Optional number for a die + private int _Sides; // 1 to 1000 sides for a die + private int _Result; // Throw result + /// + /// Default constructor + /// a single die with 6 sides + /// Note: Die is thrown as soon as it is created + /// public Die() { Sides = 6; @@ -17,9 +26,16 @@ public Die() Result = Toss(); } + /// + /// Constructor overload + /// Create a die with 1 to 1000 sides + /// Note: Die is thrown as soon as it is created + /// + /// int: Id for die (will be 0 or some positive number + /// int: 1 to 1000 sides public Die(int DieId, int DieSides) { - if (DieSides >= 0 && DieSides <= 1000) + if (DieSides >= 1 && DieSides <= 1000) { Sides = DieSides; } @@ -31,6 +47,10 @@ public Die(int DieId, int DieSides) Result = Toss(); } + /// + /// Toss the die and return the result + /// + /// int: Result of die throw private int Toss() { if (Sides == 1) @@ -46,23 +66,37 @@ private int Toss() return Result; } + /// + /// Return the die throw results method + /// + /// public int GetResult() { return Result; } + /// + /// Property: Die ID (0 or 1 to maxint) + /// public int Id { get => _Id; set => _Id = value; } + /// + /// Property: Die Sides (1 to 1000 sides) + /// public int Sides { get => _Sides; set => _Sides = value; } + /// + /// Property: Resullt of throwing this die + /// Note: The result can't be altered once thrown + /// public int Result { get => _Result; diff --git a/DiceAPI/Models/Dies.cs b/DiceAPI/Models/Dies.cs index bbfbd9a..399706a 100644 --- a/DiceAPI/Models/Dies.cs +++ b/DiceAPI/Models/Dies.cs @@ -1,6 +1,9 @@ namespace DiceAPI.Models { + /// + /// Record layout for result return record + /// public class Dies { public int Qty { get; set; } diff --git a/DiceAPI/Models/DiesContext.cs b/DiceAPI/Models/DiesContext.cs index 4b4dd0c..62e5493 100644 --- a/DiceAPI/Models/DiesContext.cs +++ b/DiceAPI/Models/DiesContext.cs @@ -1,6 +1,9 @@ namespace DiceAPI.Models { + /// + /// Just a placeholder for now + /// public class DiesContext { // Placeholder