Refactor Period to be usable with CalDateTimeZoned internally

Update `EventEvaluator` to use `CalDateTimeZoned` with `Period`
No change zu the public API
Add unit test AmbiguousLocalTime_WithShortDurationOfRecurrence which resolves #737
Make CalDateTimeEvaluator.ToString use existing ZoneDateTime

Author: axunonb

Ical.Net.Tests/PeriodTests.cs

@@ -6,6 +6,7 @@
 #nullable enable
 using System;
 using Ical.Net.DataTypes;
+using Ical.Net.Evaluation;
 using NUnit.Framework;
 
 namespace Ical.Net.Tests;
@@ -17,21 +18,29 @@ public class PeriodTests
     public void CreatePeriodWithArguments()
     {
         var period = new Period(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York"));
-        var periodWithEndTime = new Period(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York"), new CalDateTime(2025, 1, 1, 1, 0, 0, "America/New_York"));
-        var periodWithDuration = new Period(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York"), Duration.FromHours(1));
+        var periodWithEndTime = new Period(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York"),
+            new CalDateTime(2025, 1, 1, 1, 0, 0, "America/New_York"));
+        var periodWithDuration =
+            new Period(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York"), Duration.FromHours(1));
 
         Assert.Multiple(() =>
         {
             Assert.That(period.StartTime, Is.EqualTo(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York")));
             Assert.That(period.EndTime, Is.Null);
             Assert.That(period.Duration, Is.Null);
-            
-            Assert.That(periodWithEndTime.StartTime, Is.EqualTo(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York")));
-            Assert.That(periodWithEndTime.EffectiveEndTime, Is.EqualTo(new CalDateTime(2025, 1, 1, 1, 0, 0, "America/New_York")));
+            Assert.That(period.EffectiveEndTime, Is.Null);
+            Assert.That(period.EffectiveDuration, Is.Null);
+
+            Assert.That(periodWithEndTime.StartTime,
+                Is.EqualTo(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York")));
+            Assert.That(periodWithEndTime.EffectiveEndTime,
+                Is.EqualTo(new CalDateTime(2025, 1, 1, 1, 0, 0, "America/New_York")));
             Assert.That(periodWithEndTime.EffectiveDuration, Is.EqualTo(Duration.FromHours(1)));
 
-            Assert.That(periodWithDuration.StartTime, Is.EqualTo(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York")));
-            Assert.That(periodWithDuration.EffectiveEndTime, Is.EqualTo(new CalDateTime(2025, 1, 1, 1, 0, 0, "America/New_York")));
+            Assert.That(periodWithDuration.StartTime,
+                Is.EqualTo(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York")));
+            Assert.That(periodWithDuration.EffectiveEndTime,
+                Is.EqualTo(new CalDateTime(2025, 1, 1, 1, 0, 0, "America/New_York")));
             Assert.That(periodWithDuration.EffectiveDuration, Is.EqualTo(Duration.FromHours(1)));
 
             Assert.That(Period.Create(period.StartTime).Duration, Is.Null);
@@ -42,6 +51,7 @@ public void CreatePeriodWithArguments()
     [Test]
     public void CreatePeriodWithInvalidArgumentsShouldThrow()
     {
+        // Test with CalDateTime
         Assert.Multiple(() =>
         {
             // EndTime is before StartTime
@@ -62,6 +72,28 @@ public void CreatePeriodWithInvalidArgumentsShouldThrow()
             Assert.Throws<ArgumentException>(() => _ = new Period(new CalDateTime(2025, 1, 2, 0, 0, 0),
                 new CalDateTime(2025, 1, 1)));
         });
+
+        // Test with CalDateTimeZoned
+        Assert.Multiple(() =>
+        {
+            // EndTime is before StartTime
+            Assert.Throws<ArgumentException>(() => _ = new Period(
+                new CalDateTime(2025, 1, 2, 0, 0, 0, "America/New_York").AsZoned(),
+                new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York").AsZoned()));
+
+            // Duration is negative
+            Assert.Throws<ArgumentException>(() =>
+                _ = new Period(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York").AsZoned(), Duration.FromHours(-1)));
+
+            // Timezones are different
+            Assert.Throws<ArgumentException>(() => _ = new Period(
+                new CalDateTime(2025, 1, 2, 0, 0, 0, "America/New_York").AsZoned(),
+                new CalDateTime(2025, 1, 1, 0, 0, 0, "Europe/Vienna").AsZoned()));
+
+            // StartTime is date-only while EndTime has time
+            Assert.Throws<ArgumentException>(() => _ = new Period(new CalDateTime(2025, 1, 2, 0, 0, 0).AsZoned(),
+                new CalDateTime(2025, 1, 1).AsZoned()));
+        });
     }
 
     [Test]
@@ -82,6 +114,7 @@ public void Timezones_StartTime_EndTime_MustBeEqual()
             foreach (var p in periods)
             {
                 Assert.Throws<ArgumentException>(() => _ = new Period(p.Item1, p.Item2));
+                Assert.Throws<ArgumentException>(() => _ = new Period(p.Item1.AsZoned(), p.Item2.AsZoned()));
             }
         });
     }
@@ -100,4 +133,95 @@ public void CollidesWithPeriod()
             Assert.That(period2.CollidesWith(period3), Is.True);
         });
     }
+
+    [Test]
+    public void CreatePeriodWith_StartTime_and_Duration()
+    {
+        var dt = new CalDateTime(2025, 7, 1, 10, 0, 0, "Europe/London");
+        var periodCal = new Period(dt, Duration.FromHours(1));
+        var periodZoned = new Period(dt.AsZoned(), Duration.FromHours(1));
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(periodCal.StartTime, Is.EqualTo(dt));
+            Assert.That(periodCal.EffectiveEndTime, Is.EqualTo(new CalDateTime(2025, 7, 1, 11, 0, 0, "Europe/London")));
+            Assert.That(periodZoned.StartTime, Is.EqualTo(dt));
+            Assert.That(periodZoned.EffectiveEndTime,
+                Is.EqualTo(new CalDateTime(2025, 7, 1, 11, 0, 0, "Europe/London")));
+        });
+    }
+
+    [Test]
+    public void CreatePeriodWith_StartTime_and_EndTime()
+    {
+        var dt1 = new CalDateTime(2025, 7, 1, 10, 0, 0, "Europe/London");
+        var dt2 = new CalDateTime(2025, 7, 1, 11, 0, 0, "Europe/London");
+        var periodCal = new Period(dt1, dt2);
+        var periodZoned = new Period(dt1.AsZoned(), dt2.AsZoned());
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(periodCal.StartTime, Is.EqualTo(dt1));
+            Assert.That(periodCal.EndTime, Is.EqualTo(dt2));
+            Assert.That(periodCal.EffectiveEndTime,
+                Is.EqualTo(new CalDateTime(2025, 7, 1, 11, 0, 0, "Europe/London")));
+
+            Assert.That(periodZoned.StartTime, Is.EqualTo(dt1));
+            Assert.That(periodZoned.EndTime, Is.EqualTo(dt2));
+            Assert.That(periodZoned.EffectiveEndTime,
+                Is.EqualTo(new CalDateTime(2025, 7, 1, 11, 0, 0, "Europe/London")));
+        });
+    }
+
+    [Test]
+    public void CreatePeriodWith_StartTime_Only()
+    {
+        var dt = new CalDateTime(2025, 7, 1, 10, 0, 0, "Europe/London");
+        var periodCal = new Period(dt);
+        var periodZoned = new Period(dt.AsZoned());
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(periodCal.StartTime, Is.EqualTo(dt));
+            Assert.That(periodCal.EndTime, Is.Null);
+            Assert.That(periodCal.Duration, Is.Null);
+            Assert.That(periodCal.EffectiveEndTime, Is.Null);
+
+            Assert.That(periodZoned.StartTime, Is.EqualTo(dt));
+            Assert.That(periodZoned.EndTime, Is.Null);
+            Assert.That(periodZoned.Duration, Is.Null);
+            Assert.That(periodZoned.EffectiveEndTime, Is.Null);
+        });
+    }
+
+    [Test]
+    public void PeriodCompareToNull_ShouldReturnOne()
+    {
+        var dt = new CalDateTime(2025, 7, 1, 10, 0, 0, "Europe/London");
+        var period = new Period(dt, Duration.FromHours(1));
+
+        Assert.That(period.CompareTo(null), Is.EqualTo(1));
+    }
+
+    [Test]
+    public void PeriodCopyFrom_ShouldBeEquivalentToOriginal()
+    {
+        var original = new Period(new CalDateTime(2025, 1, 1, 0, 0, 0, "America/New_York"), Duration.FromHours(10));
+        var copy = new Period();
+        copy.CopyFrom(original);
+
+        var copyEmpty = new Period(); // internal CTOR
+        // another ICopyable instance which is not a Period
+        copyEmpty.CopyFrom(new PeriodList());
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(copy.StartTime, Is.EqualTo(original.StartTime));
+            Assert.That(copy.Duration, Is.EqualTo(original.Duration));
+
+            Assert.That(copyEmpty.StartTime, Is.Null);
+            Assert.That(copyEmpty.EndTime, Is.Null);
+            Assert.That(copyEmpty.Duration, Is.Null);
+        });
+    }
 }

Ical.Net.Tests/RecurrenceTests.cs

@@ -4031,4 +4031,37 @@ public void Disallowed_Recurrence_RangeChecks_Should_Throw()
             Assert.That(() => serializer.CheckRange("a", (int?) 0, 1, 2, false), Throws.TypeOf<ArgumentOutOfRangeException>());
         });
     }
+
+    [Test]
+    public void AmbiguousLocalTime_WithShortDurationOfRecurrence()
+    {
+        // Short recurrence falls into an ambiguous local time
+        // for the end time of the second occurrence because
+        // of DST transition on 2025-10-25 03:00
+        // See also: https://github.com/ical-org/ical.net/issues/737
+        var ics = """
+                  BEGIN:VCALENDAR
+                  BEGIN:VEVENT
+                  DTSTART;TZID=Europe/Vienna:20201024T023000
+                  DURATION:PT45M
+                  RRULE:FREQ=DAILY;UNTIL=20201025T013000Z
+                  END:VEVENT
+                  END:VCALENDAR
+                  """;
+        var cal = Calendar.Load(ics)!;
+        var occ = cal.GetOccurrences().ToList();
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(occ.Count, Is.EqualTo(2));
+
+            Assert.That(occ[0].Period.StartTime, Is.EqualTo(new CalDateTime(2020, 10, 24, 2, 30, 0, "Europe/Vienna")));
+            Assert.That(occ[0].Period.EndTime, Is.EqualTo(new CalDateTime(2020, 10, 24, 3, 15, 0, "Europe/Vienna")));
+            Assert.That(occ[0].Period.EffectiveDuration, Is.EqualTo(new Duration(0, 0, 0, 45, 0)));
+
+            Assert.That(occ[1].Period.StartTime, Is.EqualTo(new CalDateTime(2020, 10, 25, 2, 30, 0, "Europe/Vienna")));
+            Assert.That(occ[1].Period.EndTime, Is.EqualTo(new CalDateTime(2020, 10, 25, 2, 15, 0, "Europe/Vienna")));
+            Assert.That(occ[1].Period.EffectiveDuration, Is.EqualTo(new Duration(0, 0, 0, 45, 0)));
+        });
+    }
 }

Ical.Net/CalendarComponents/FreeBusy.cs

@@ -22,7 +22,7 @@ public class FreeBusy : UniqueComponent, IMergeable
         }
 
         var occurrences = occ.GetOccurrences<CalendarEvent>(freeBusyRequest.Start, options)
-            .TakeWhile(p => (freeBusyRequest.End == null) || (p.Period.StartTime.AsZoned().LessThan(freeBusyRequest.End.AsZoned())));
+            .TakeWhile(p => (freeBusyRequest.End == null) || (p.Period.Start.LessThan(freeBusyRequest.End.AsZoned())));
 
         var contacts = new List<string>();
         var isFilteredByAttendees = false;