add date utility

4 files changed, 246 insertions, 1 deletions

diff --git a/src/StardewModdingAPI.Tests/SDateTests.cs b/src/StardewModdingAPI.Tests/SDateTests.cs
new file mode 100644
index 00000000..a4c65a98
--- /dev/null
+++ b/src/StardewModdingAPI.Tests/SDateTests.cs
@@ -0,0 +1,112 @@
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Text.RegularExpressions;
+using NUnit.Framework;
+using StardewModdingAPI.Utilities;
+
+namespace StardewModdingAPI.Tests
+{
+    /// <summary>Unit tests for <see cref="SDate"/>.</summary>
+    [TestFixture]
+    internal class SDateTests
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>All valid seasons.</summary>
+        private static string[] ValidSeasons = { "spring", "summer", "fall", "winter" };
+
+        /// <summary>All valid days of a month.</summary>
+        private static int[] ValidDays = Enumerable.Range(1, 28).ToArray();
+
+
+        /*********
+        ** Unit tests
+        *********/
+        /****
+        ** Constructor
+        ****/
+        [Test(Description = "Assert that the constructor sets the expected values for all valid dates.")]
+        public void Constructor_SetsExpectedValues([ValueSource(nameof(SDateTests.ValidSeasons))] string season, [ValueSource(nameof(SDateTests.ValidDays))] int day, [Values(1, 2, 100)] int year)
+        {
+            // act
+            SDate date = new SDate(day, season, year);
+
+            // assert
+            Assert.AreEqual(day, date.Day);
+            Assert.AreEqual(season, date.Season);
+            Assert.AreEqual(year, date.Year);
+        }
+
+        [Test(Description = "Assert that the constructor throws an exception if the values are invalid.")]
+        [TestCase(01, "Spring", 1)] // seasons are case-sensitive
+        [TestCase(01, "springs", 1)] // invalid season name
+        [TestCase(-1, "spring", 1)] // day < 0
+        [TestCase(29, "spring", 1)] // day > 28
+        [TestCase(01, "spring", -1)] // year < 1
+        [TestCase(01, "spring", 0)] // year < 1
+        [SuppressMessage("ReSharper", "AssignmentIsFullyDiscarded", Justification = "Deliberate for unit test.")]
+        public void Constructor_RejectsInvalidValues(int day, string season, int year)
+        {
+            // act & assert
+            Assert.Throws<ArgumentException>(() => _ = new SDate(day, season, year), "Constructing the invalid date didn't throw the expected exception.");
+        }
+
+        /****
+        ** ToString
+        ****/
+        [Test(Description = "Assert that ToString returns the expected string.")]
+        [TestCase("14 spring Y1", ExpectedResult = "14 spring Y1")]
+        [TestCase("01 summer Y16", ExpectedResult = "01 summer Y16")]
+        [TestCase("28 fall Y10", ExpectedResult = "28 fall Y10")]
+        [TestCase("01 winter Y1", ExpectedResult = "01 winter Y1")]
+        public string ToString(string dateStr)
+        {
+            return this.ParseDate(dateStr).ToString();
+        }
+
+        /****
+        ** AddDays
+        ****/
+        [Test(Description = "Assert that AddDays returns the expected date.")]
+        [TestCase("01 spring Y1", 15, ExpectedResult = "16 spring Y1")] // day transition
+        [TestCase("01 spring Y1", 28, ExpectedResult = "01 summer Y1")] // season transition
+        [TestCase("01 spring Y1", 28 * 4, ExpectedResult = "01 spring Y2")] // year transition
+        [TestCase("01 spring Y1", 28 * 7 + 17, ExpectedResult = "18 winter Y2")] // year transition
+        [TestCase("15 spring Y1", -14, ExpectedResult = "01 spring Y1")] // negative day transition
+        [TestCase("15 summer Y1", -28, ExpectedResult = "15 spring Y1")] // negative season transition
+        [TestCase("15 summer Y2", -28 * 4, ExpectedResult = "15 summer Y1")] // negative year transition
+        [TestCase("01 spring Y3", -(28 * 7 + 17), ExpectedResult = "12 spring Y1")] // negative year transition
+        public string AddDays(string dateStr, int addDays)
+        {
+            return this.ParseDate(dateStr).AddDays(addDays).ToString();
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>Convert a string date into a game date, to make unit tests easier to read.</summary>
+        /// <param name="dateStr">The date string like "dd MMMM yy".</param>
+        private SDate ParseDate(string dateStr)
+        {
+            void Fail(string reason) => throw new AssertionException($"Couldn't parse date '{dateStr}' because {reason}.");
+
+            // parse
+            Match match = Regex.Match(dateStr, @"^(?<day>\d+) (?<season>\w+) Y(?<year>\d+)$");
+            if (!match.Success)
+                Fail("it doesn't match expected pattern (should be like 28 spring Y1)");
+
+            // extract parts
+            string season = match.Groups["season"].Value;
+            if (!int.TryParse(match.Groups["day"].Value, out int day))
+                Fail($"'{match.Groups["day"].Value}' couldn't be parsed as a day.");
+            if (!int.TryParse(match.Groups["year"].Value, out int year))
+                Fail($"'{match.Groups["year"].Value}' couldn't be parsed as a year.");
+
+            // build date
+            return new SDate(day, season, year);
+        }
+    }
+}
diff --git a/src/StardewModdingAPI.Tests/StardewModdingAPI.Tests.csproj b/src/StardewModdingAPI.Tests/StardewModdingAPI.Tests.csproj
index 3818ec9c..3ddb1326 100644
--- a/src/StardewModdingAPI.Tests/StardewModdingAPI.Tests.csproj
+++ b/src/StardewModdingAPI.Tests/StardewModdingAPI.Tests.csproj
@@ -48,6 +48,7 @@
     <Compile Include="..\GlobalAssemblyInfo.cs">
       <Link>Properties\GlobalAssemblyInfo.cs</Link>
     </Compile>
+    <Compile Include="SDateTests.cs" />
     <Compile Include="TranslationTests.cs" />
     <Compile Include="ModResolverTests.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
diff --git a/src/StardewModdingAPI/StardewModdingAPI.csproj b/src/StardewModdingAPI/StardewModdingAPI.csproj
index ae454a35..7cc537ac 100644
--- a/src/StardewModdingAPI/StardewModdingAPI.csproj
+++ b/src/StardewModdingAPI/StardewModdingAPI.csproj
@@ -202,6 +202,7 @@
     <Compile Include="IReflectionHelper.cs" />
     <Compile Include="SemanticVersion.cs" />
     <Compile Include="Translation.cs" />
+    <Compile Include="Utilities\SDate.cs" />
   </ItemGroup>
   <ItemGroup>
     <None Include="App.config">
@@ -273,4 +274,4 @@
   <!-- Somehow this makes Visual Studio for Mac recognise the previous section. -->
   <!-- Nobody knows why. -->
   <PropertyGroup Condition="'$(RunConfiguration)' == 'Default'" />
-</Project>
+</Project>
\ No newline at end of file
diff --git a/src/StardewModdingAPI/Utilities/SDate.cs b/src/StardewModdingAPI/Utilities/SDate.cs
new file mode 100644
index 00000000..4729bfb9
--- /dev/null
+++ b/src/StardewModdingAPI/Utilities/SDate.cs
@@ -0,0 +1,131 @@
+using System;
+using System.Linq;
+using StardewValley;
+
+namespace StardewModdingAPI.Utilities
+{
+    /// <summary>Represents a Stardew Valley date.</summary>
+    public class SDate
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>The internal season names in order.</summary>
+        private readonly string[] Seasons = { "spring", "summer", "fall", "winter" };
+
+        /// <summary>The number of days in a season.</summary>
+        private readonly int DaysInSeason = 28;
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The day of month.</summary>
+        public int Day { get; }
+
+        /// <summary>The season name.</summary>
+        public string Season { get; }
+
+        /// <summary>The year.</summary>
+        public int Year { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="day">The day of month.</param>
+        /// <param name="season">The season name.</param>
+        /// <exception cref="ArgumentException">One of the arguments has an invalid value (like day 35).</exception>
+        public SDate(int day, string season)
+            : this(day, season, Game1.year) { }
+
+        /// <summary>Construct an instance.</summary>
+        /// <param name="day">The day of month.</param>
+        /// <param name="season">The season name.</param>
+        /// <param name="year">The year.</param>
+        /// <exception cref="ArgumentException">One of the arguments has an invalid value (like day 35).</exception>
+        public SDate(int day, string season, int year)
+        {
+            // validate
+            if (season == null)
+                throw new ArgumentNullException(nameof(season));
+            if (!this.Seasons.Contains(season))
+                throw new ArgumentException($"Unknown season '{season}', must be one of [{string.Join(", ", this.Seasons)}].");
+            if (day < 1 || day > this.DaysInSeason)
+                throw new ArgumentException($"Invalid day '{day}', must be a value from 1 to {this.DaysInSeason}.");
+            if (year < 1)
+                throw new ArgumentException($"Invalid year '{year}', must be at least 1.");
+
+            // initialise
+            this.Day = day;
+            this.Season = season;
+            this.Year = year;
+        }
+
+        /// <summary>Get a new date with the given number of days added.</summary>
+        /// <param name="offset">The number of days to add.</param>
+        /// <returns>Returns the resulting date.</returns>
+        /// <exception cref="ArithmeticException">The offset would result in an invalid date (like year 0).</exception>
+        public SDate AddDays(int offset)
+        {
+            // simple case
+            int day = this.Day + offset;
+            string season = this.Season;
+            int year = this.Year;
+
+            // handle season transition
+            if (day > this.DaysInSeason || day < 1)
+            {
+                // get current season index
+                int curSeasonIndex = Array.IndexOf(this.Seasons, this.Season);
+                if (curSeasonIndex == -1)
+                    throw new InvalidOperationException($"The current season '{this.Season}' wasn't recognised.");
+
+                // get season offset
+                int seasonOffset = day / this.DaysInSeason;
+                if (day < 1)
+                    seasonOffset -= 1;
+
+                // get new date
+                day = this.GetWrappedIndex(day, this.DaysInSeason);
+                season = this.Seasons[this.GetWrappedIndex(curSeasonIndex + seasonOffset, this.Seasons.Length)];
+                year += seasonOffset / this.Seasons.Length;
+            }
+
+            // validate
+            if(year < 1)
+                throw new ArithmeticException($"Adding {offset} days to {this} would result in invalid date {day:00} {season} {year}.");
+
+            // return new date
+            return new SDate(day, season, year);
+        }
+
+        /// <summary>Get a string representation of the date. This is mainly intended for debugging or console messages.</summary>
+        public override string ToString()
+        {
+            return $"{this.Day:00} {this.Season} Y{this.Year}";
+        }
+
+        /// <summary>Get the current in-game date.</summary>
+        public static SDate Now()
+        {
+            return new SDate(Game1.dayOfMonth, Game1.currentSeason, Game1.year);
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>Get the real index in an array which should be treated as a two-way loop.</summary>
+        /// <param name="index">The index in the looped array.</param>
+        /// <param name="length">The number of elements in the array.</param>
+        private int GetWrappedIndex(int index, int length)
+        {
+            int wrapped = index % length;
+            if (wrapped < 0)
+                wrapped += length;
+            return wrapped;
+        }
+    }
+}