Adds timezone support to DateMath

niemyjski · niemyjski · commit 66bee8130018 · 2025-09-21T23:02:52.000-05:00
Extends the DateMath utility to support TimeZoneInfo, enabling accurate date parsing and calculations within specific timezones.

This enhancement allows for parsing expressions using a specified timezone, ensuring that "now" calculations and dates without explicit timezone information are correctly interpreted.
Dates with explicit timezone information are preserved, regardless of the TimeZoneInfo parameter.
diff --git a/README.md b/README.md
@@ -99,6 +99,34 @@ var utcResult = DateMath.Parse("2025-01-01T01:25:35Z||+3d/d", baseTime);
 var offsetResult = DateMath.Parse("2023-06-15T14:30:00+05:00||+1M", baseTime);
 ```
 
+#### TimeZone-Aware DateMath
+
+The `DateMath` utility also provides overloads that work directly with `TimeZoneInfo` for better timezone handling:
+
+```csharp
+using Exceptionless.DateTimeExtensions;
+
+// Parse expressions using a specific timezone
+var utcTimeZone = TimeZoneInfo.Utc;
+var easternTimeZone = TimeZoneInfo.FindSystemTimeZoneById("US/Eastern");
+
+// "now" will use current time in the specified timezone
+var utcResult = DateMath.Parse("now+1h", utcTimeZone);
+var easternResult = DateMath.Parse("now/d", easternTimeZone, isUpperLimit: false);
+
+// TryParse with timezone
+if (DateMath.TryParse("now+2d-3h", easternTimeZone, false, out var result)) {
+    Console.WriteLine($"Eastern time result: {result:O}");
+}
+
+// Dates without explicit timezone use the provided TimeZoneInfo
+var localDate = DateMath.Parse("2023-06-15T14:30:00||+1M", easternTimeZone);
+
+// Dates with explicit timezone are preserved regardless of TimeZoneInfo parameter
+var preservedTz = DateMath.Parse("2023-06-15T14:30:00+05:00||+1M", easternTimeZone);
+// Result will still have +05:00 offset, not Eastern time offset
+```
+
 The `DateMath` utility supports the same comprehensive syntax as `DateTimeRange` but provides a simpler API for direct parsing operations.
 
 ### TimeUnit
diff --git a/src/Exceptionless.DateTimeExtensions/DateMath.cs b/src/Exceptionless.DateTimeExtensions/DateMath.cs
@@ -67,6 +67,52 @@ public static bool TryParse(string expression, DateTimeOffset relativeBaseTime,
         return TryParseFromMatch(match, relativeBaseTime, isUpperLimit, out result);
     }
 
+    /// <summary>
+    /// Parses a date math expression and returns the resulting DateTimeOffset using the specified timezone.
+    /// </summary>
+    /// <param name="expression">The date math expression to parse</param>
+    /// <param name="timeZone">The timezone to use for 'now' calculations and dates without explicit timezone information</param>
+    /// <param name="isUpperLimit">Whether this is for an upper limit (affects rounding behavior)</param>
+    /// <returns>The parsed DateTimeOffset</returns>
+    /// <exception cref="ArgumentException">Thrown when the expression is invalid or cannot be parsed</exception>
+    /// <exception cref="ArgumentNullException">Thrown when timeZone is null</exception>
+    public static DateTimeOffset Parse(string expression, TimeZoneInfo timeZone, bool isUpperLimit = false)
+    {
+        if (timeZone == null)
+            throw new ArgumentNullException(nameof(timeZone));
+
+        if (!TryParse(expression, timeZone, isUpperLimit, out DateTimeOffset result))
+            throw new ArgumentException($"Invalid date math expression: {expression}", nameof(expression));
+
+        return result;
+    }
+
+    /// <summary>
+    /// Tries to parse a date math expression and returns the resulting DateTimeOffset using the specified timezone.
+    /// </summary>
+    /// <param name="expression">The date math expression to parse</param>
+    /// <param name="timeZone">The timezone to use for 'now' calculations and dates without explicit timezone information</param>
+    /// <param name="isUpperLimit">Whether this is for an upper limit (affects rounding behavior)</param>
+    /// <param name="result">The parsed DateTimeOffset if successful</param>
+    /// <returns>True if parsing succeeded, false otherwise</returns>
+    /// <exception cref="ArgumentNullException">Thrown when timeZone is null</exception>
+    public static bool TryParse(string expression, TimeZoneInfo timeZone, bool isUpperLimit, out DateTimeOffset result)
+    {
+        if (timeZone == null)
+            throw new ArgumentNullException(nameof(timeZone));
+
+        result = default;
+
+        if (String.IsNullOrEmpty(expression))
+            return false;
+
+        var match = Parser.Match(expression);
+        if (!match.Success)
+            return false;
+
+        return TryParseFromMatch(match, timeZone, isUpperLimit, out result);
+    }
+
     /// <summary>
     /// Tries to parse a date math expression from a regex match and returns the resulting DateTimeOffset.
     /// This method bypasses the regex matching for cases where the match is already available.
@@ -109,6 +155,50 @@ public static bool TryParseFromMatch(Match match, DateTimeOffset relativeBaseTim
         }
     }
 
+    /// <summary>
+    /// Tries to parse a date math expression from a regex match and returns the resulting DateTimeOffset using the specified timezone.
+    /// This method bypasses the regex matching for cases where the match is already available.
+    /// </summary>
+    /// <param name="match">The regex match containing the parsed expression groups</param>
+    /// <param name="timeZone">The timezone to use for 'now' calculations and dates without explicit timezone information</param>
+    /// <param name="isUpperLimit">Whether this is for an upper limit (affects rounding behavior)</param>
+    /// <param name="result">The parsed DateTimeOffset if successful</param>
+    /// <returns>True if parsing succeeded, false otherwise</returns>
+    public static bool TryParseFromMatch(Match match, TimeZoneInfo timeZone, bool isUpperLimit, out DateTimeOffset result)
+    {
+        result = default;
+
+        try
+        {
+            // Parse the anchor (now or explicit date)
+            DateTimeOffset baseTime;
+            string anchor = match.Groups["anchor"].Value;
+
+            if (anchor.Equals("now", StringComparison.OrdinalIgnoreCase))
+            {
+                // Use current time in the specified timezone
+                baseTime = TimeZoneInfo.ConvertTime(DateTimeOffset.UtcNow, timeZone);
+            }
+            else
+            {
+                // Parse explicit date from the date group
+                string dateStr = match.Groups["date"].Value;
+                TimeSpan offset = timeZone.GetUtcOffset(DateTime.UtcNow);
+                if (!TryParseExplicitDate(dateStr, offset, out baseTime))
+                    return false;
+            }
+
+            // Parse and apply operations
+            string operations = match.Groups["operations"].Value;
+            result = ApplyOperations(baseTime, operations, isUpperLimit);
+            return true;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
     /// <summary>
     /// Checks if the given expression is a valid date math expression.
     /// </summary>
diff --git a/tests/Exceptionless.DateTimeExtensions.Tests/DateMathTests.cs b/tests/Exceptionless.DateTimeExtensions.Tests/DateMathTests.cs
@@ -511,4 +511,250 @@ public void Parse_ComplexExpression_MultipleOperationsWithRounding()
         // Should not equal base time
         Assert.NotEqual(_baseTime, result);
     }
+
+    [Fact]
+    public void Parse_WithTimeZoneInfo_Now_ReturnsCurrentTimeInSpecifiedTimezone()
+    {
+        var utcTimeZone = TimeZoneInfo.Utc;
+        const string expression = "now";
+
+        _logger.LogDebug("Testing Parse with TimeZoneInfo for expression: '{Expression}', TimeZone: {TimeZone}",
+            expression, utcTimeZone.Id);
+
+        var result = DateMath.Parse(expression, utcTimeZone);
+
+        _logger.LogDebug("Parse result: {Result}", result);
+
+        // Should be close to current UTC time
+        var utcNow = DateTimeOffset.UtcNow;
+        Assert.True(Math.Abs((result - utcNow).TotalSeconds) < 5,
+            $"Result {result} should be within 5 seconds of UTC now {utcNow}");
+        Assert.Equal(TimeSpan.Zero, result.Offset); // Should be UTC
+    }
+
+    [Theory]
+    [InlineData("UTC", 0)]
+    [InlineData("US/Eastern", -5)] // EST offset (not considering DST for this test)
+    [InlineData("US/Pacific", -8)] // PST offset (not considering DST for this test)
+    public void Parse_WithTimeZoneInfo_Now_ReturnsCorrectTimezone(string timeZoneId, int expectedOffsetHours)
+    {
+        var timeZone = TimeZoneInfo.FindSystemTimeZoneById(timeZoneId);
+        const string expression = "now";
+
+        _logger.LogDebug("Testing Parse with TimeZoneInfo for expression: '{Expression}', TimeZone: {TimeZone}",
+            expression, timeZone.Id);
+
+        var result = DateMath.Parse(expression, timeZone);
+
+        _logger.LogDebug("Parse result: {Result}, Expected offset hours: {ExpectedOffsetHours}", result, expectedOffsetHours);
+
+        // Note: This test might need adjustment for DST, but it demonstrates the concept
+        Assert.Equal(timeZone.GetUtcOffset(DateTime.UtcNow), result.Offset);
+    }
+
+    [Fact]
+    public void Parse_WithTimeZoneInfo_ExplicitDateWithoutTimezone_UsesSpecifiedTimezone()
+    {
+        var easternTimeZone = TimeZoneInfo.FindSystemTimeZoneById("US/Eastern");
+        const string expression = "2023-06-15T14:30:00||";
+
+        _logger.LogDebug("Testing Parse with TimeZoneInfo for expression: '{Expression}', TimeZone: {TimeZone}",
+            expression, easternTimeZone.Id);
+
+        var result = DateMath.Parse(expression, easternTimeZone);
+
+        _logger.LogDebug("Parse result: {Result}", result);
+
+        Assert.Equal(2023, result.Year);
+        Assert.Equal(6, result.Month);
+        Assert.Equal(15, result.Day);
+        Assert.Equal(14, result.Hour);
+        Assert.Equal(30, result.Minute);
+        Assert.Equal(0, result.Second);
+        
+        // Should use the timezone offset from Eastern Time
+        var expectedOffset = easternTimeZone.GetUtcOffset(new DateTime(2023, 6, 15, 14, 30, 0));
+        Assert.Equal(expectedOffset, result.Offset);
+    }
+
+    [Fact]
+    public void Parse_WithTimeZoneInfo_ExplicitDateWithTimezone_PreservesOriginalTimezone()
+    {
+        var pacificTimeZone = TimeZoneInfo.FindSystemTimeZoneById("US/Pacific");
+        const string expression = "2023-06-15T14:30:00+05:00||"; // Explicit +05:00 timezone
+
+        _logger.LogDebug("Testing Parse with TimeZoneInfo for expression: '{Expression}', TimeZone: {TimeZone}",
+            expression, pacificTimeZone.Id);
+
+        var result = DateMath.Parse(expression, pacificTimeZone);
+
+        _logger.LogDebug("Parse result: {Result}", result);
+
+        Assert.Equal(2023, result.Year);
+        Assert.Equal(6, result.Month);
+        Assert.Equal(15, result.Day);
+        Assert.Equal(14, result.Hour);
+        Assert.Equal(30, result.Minute);
+        Assert.Equal(0, result.Second);
+        
+        // Should preserve the original +05:00 timezone, not use Pacific
+        Assert.Equal(TimeSpan.FromHours(5), result.Offset);
+    }
+
+    [Theory]
+    [InlineData("now+1h", 1)]
+    [InlineData("now+6h", 6)]
+    [InlineData("now-2h", -2)]
+    [InlineData("now+24h", 24)]
+    public void Parse_WithTimeZoneInfo_HourOperations_ReturnsCorrectResult(string expression, int hours)
+    {
+        var utcTimeZone = TimeZoneInfo.Utc;
+        
+        _logger.LogDebug("Testing Parse with TimeZoneInfo for expression: '{Expression}', TimeZone: {TimeZone}, Hours: {Hours}",
+            expression, utcTimeZone.Id, hours);
+
+        var result = DateMath.Parse(expression, utcTimeZone);
+        var utcNow = DateTimeOffset.UtcNow;
+        var expected = utcNow.AddHours(hours);
+
+        _logger.LogDebug("Parse result: {Result}, Expected: approximately {Expected}", result, expected);
+
+        // Should be close to expected time (within 5 seconds to account for execution time)
+        Assert.True(Math.Abs((result - expected).TotalSeconds) < 5,
+            $"Result {result} should be within 5 seconds of expected {expected}");
+        Assert.Equal(TimeSpan.Zero, result.Offset); // Should be UTC
+    }
+
+    [Theory]
+    [InlineData("now/d", false)]
+    [InlineData("now/d", true)]
+    [InlineData("now/h", false)]
+    [InlineData("now/h", true)]
+    [InlineData("now/M", false)]
+    [InlineData("now/M", true)]
+    public void Parse_WithTimeZoneInfo_RoundingOperations_ReturnsCorrectResult(string expression, bool isUpperLimit)
+    {
+        var centralTimeZone = TimeZoneInfo.FindSystemTimeZoneById("US/Central");
+        
+        _logger.LogDebug("Testing Parse with TimeZoneInfo for expression: '{Expression}', TimeZone: {TimeZone}, IsUpperLimit: {IsUpperLimit}",
+            expression, centralTimeZone.Id, isUpperLimit);
+
+        var result = DateMath.Parse(expression, centralTimeZone, isUpperLimit);
+
+        _logger.LogDebug("Parse result: {Result}", result);
+
+        // Verify the result uses Central Time offset
+        var expectedOffset = centralTimeZone.GetUtcOffset(DateTime.UtcNow);
+        Assert.Equal(expectedOffset, result.Offset);
+
+        // Verify rounding behavior
+        if (expression.EndsWith("/d"))
+        {
+            if (isUpperLimit)
+            {
+                Assert.Equal(23, result.Hour);
+                Assert.Equal(59, result.Minute);
+                Assert.Equal(59, result.Second);
+            }
+            else
+            {
+                Assert.Equal(0, result.Hour);
+                Assert.Equal(0, result.Minute);
+                Assert.Equal(0, result.Second);
+            }
+        }
+        else if (expression.EndsWith("/h"))
+        {
+            if (isUpperLimit)
+            {
+                Assert.Equal(59, result.Minute);
+                Assert.Equal(59, result.Second);
+            }
+            else
+            {
+                Assert.Equal(0, result.Minute);
+                Assert.Equal(0, result.Second);
+            }
+        }
+    }
+
+    [Fact]
+    public void TryParse_WithTimeZoneInfo_ValidExpression_ReturnsTrue()
+    {
+        var mountainTimeZone = TimeZoneInfo.FindSystemTimeZoneById("US/Mountain");
+        const string expression = "now+2d";
+
+        _logger.LogDebug("Testing TryParse with TimeZoneInfo for expression: '{Expression}', TimeZone: {TimeZone}",
+            expression, mountainTimeZone.Id);
+
+        bool success = DateMath.TryParse(expression, mountainTimeZone, false, out DateTimeOffset result);
+
+        _logger.LogDebug("TryParse success: {Success}, Result: {Result}", success, result);
+
+        Assert.True(success);
+        Assert.NotEqual(default(DateTimeOffset), result);
+        
+        // Should use Mountain Time offset
+        var expectedOffset = mountainTimeZone.GetUtcOffset(DateTime.UtcNow);
+        Assert.Equal(expectedOffset, result.Offset);
+    }
+
+    [Fact]
+    public void TryParse_WithTimeZoneInfo_InvalidExpression_ReturnsFalse()
+    {
+        var utcTimeZone = TimeZoneInfo.Utc;
+        const string expression = "invalid_expression";
+
+        _logger.LogDebug("Testing TryParse with TimeZoneInfo for invalid expression: '{Expression}', TimeZone: {TimeZone}",
+            expression, utcTimeZone.Id);
+
+        bool success = DateMath.TryParse(expression, utcTimeZone, false, out DateTimeOffset result);
+
+        _logger.LogDebug("TryParse success: {Success}, Result: {Result}", success, result);
+
+        Assert.False(success);
+        Assert.Equal(default(DateTimeOffset), result);
+    }
+
+    [Fact]
+    public void Parse_WithTimeZoneInfo_ComplexExpression_WorksCorrectly()
+    {
+        var utcTimeZone = TimeZoneInfo.Utc;
+        const string expression = "now+1M-2d+3h/h";
+
+        _logger.LogDebug("Testing Parse with TimeZoneInfo for complex expression: '{Expression}', TimeZone: {TimeZone}",
+            expression, utcTimeZone.Id);
+
+        var result = DateMath.Parse(expression, utcTimeZone, false);
+
+        _logger.LogDebug("Parse result: {Result}", result);
+
+        // Should be UTC
+        Assert.Equal(TimeSpan.Zero, result.Offset);
+        
+        // Should be rounded to start of hour
+        Assert.Equal(0, result.Minute);
+        Assert.Equal(0, result.Second);
+        Assert.Equal(0, result.Millisecond);
+    }
+
+    [Fact]
+    public void Parse_WithTimeZoneInfo_NullTimeZone_ThrowsArgumentNullException()
+    {
+        const string expression = "now";
+
+        _logger.LogDebug("Testing Parse with null TimeZoneInfo for expression: '{Expression}'", expression);
+
+        Assert.Throws<ArgumentNullException>(() => DateMath.Parse(expression, (TimeZoneInfo)null!));
+    }
+
+    [Fact]
+    public void TryParse_WithTimeZoneInfo_NullTimeZone_ThrowsArgumentNullException()
+    {
+        const string expression = "now";
+
+        _logger.LogDebug("Testing TryParse with null TimeZoneInfo for expression: '{Expression}'", expression);
+
+        Assert.Throws<ArgumentNullException>(() => DateMath.TryParse(expression, (TimeZoneInfo)null!, false, out _));
+    }
 }
