Introduce Duration type to keep apart nominal vs exact durations.

[minichma]

This PR addresses shortcomings of the lib regarding the different requirements of nominal vs exact duration as specified by RFC 5545. It introduces the new Duration type that replaces TimeSpan in most places. In contrast to the latter, Duration stores the individual duration parts (weeks, days, hours, minutes, seconds) individually. This is required because according to the RFC weeks and days are considered nominal values while hours, minutes, seconds are considered exact (see https://www.rfc-editor.org/rfc/rfc5545#section-3.3.6, https://www.rfc-editor.org/rfc/rfc5545#section-3.8.5.3).

Most relevant changes:

• CalendarEvent.Duration et al and Period.Duration changed from TimeSpan to Duration
• CalendarEvent.GetTimeSpanToAddToPeriodStartTime replaced by CalendarEvent.GetEffectiveDuration, which takes care of keeping apart nominal vs. exact durations. I.e. if the duration is specified via DTEND, then the returned duration only uses time-related fields, so it is considered exact. If specified via DURATION, the duration is returned as specified by the caller.
• CalDateTime.Add(Duration) and .Subtract() handle the different parts of Duration conformant to the RFC.

[codecov]

Codecov Report

Attention: Patch coverage is 74.27184% with 53 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
Ical.Net/DataTypes/Duration.cs	75%	3 Missing and 12 partials ⚠️
....Net/Serialization/DataTypes/DurationSerializer.cs	76%	7 Missing and 5 partials ⚠️
Ical.Net/DataTypes/Period.cs	59%	3 Missing and 6 partials ⚠️
Ical.Net/CalendarComponents/Alarm.cs	0%	5 Missing ⚠️
Ical.Net/CalendarComponents/CalendarEvent.cs	75%	1 Missing and 1 partial ⚠️
Ical.Net/DataTypes/CalDateTime.cs	93%	1 Missing and 1 partial ⚠️
Ical.Net/Evaluation/EventEvaluator.cs	67%	1 Missing and 1 partial ⚠️
Ical.Net/Evaluation/TodoEvaluator.cs	50%	1 Missing and 1 partial ⚠️
...al.Net/Serialization/DataTypes/PeriodSerializer.cs	60%	0 Missing and 2 partials ⚠️
Ical.Net/CalendarComponents/VTimeZone.cs	50%	1 Missing ⚠️
... and 1 more

@@         Coverage Diff         @@
##           main   #680   +/-   ##
===================================
  Coverage    63%    63%           
===================================
  Files        99    100    +1     
  Lines      4550   4606   +56     
  Branches   1075   1107   +32     
===================================
+ Hits       2863   2909   +46     
+ Misses     1240   1239    -1     
- Partials    447    458   +11     

Files with missing lines	Coverage Δ
Ical.Net/CalendarComponents/Todo.cs	69% <100%> (+5%)	⬆️
Ical.Net/DataTypes/CalendarDataType.cs	49% <100%> (ø)
Ical.Net/DataTypes/Trigger.cs	44% <100%> (ø)
Ical.Net/Evaluation/RecurrencePatternEvaluator.cs	71% <100%> (+<1%)	⬆️
Ical.Net/Serialization/DataTypeMapper.cs	78% <100%> (ø)
Ical.Net/Serialization/SerializerFactory.cs	79% <100%> (ø)
Ical.Net/Utility/DateUtil.cs	59% <100%> (+3%)	⬆️
Ical.Net/CalendarComponents/VTimeZone.cs	73% <50%> (ø)
...l.Net/Serialization/DataTypes/TriggerSerializer.cs	31% <67%> (ø)
Ical.Net/CalendarComponents/CalendarEvent.cs	73% <75%> (-1%)	⬇️
... and 8 more

... and 1 file with indirect coverage changes

[axunonb]

I'll be waiting until this PR gets merged before submitting a PR for EXDATE and RDATE fixes.

[minichma]

I'll be waiting until this PR gets merged before submitting a PR for EXDATE and RDATE fixes.

@axunonb I think the PR should be ready for review, would be great if you'd find some time for it. It's quite some code that has changed, but all in all not too complex, once the basics regarding nominal vs. exact are understood. Probably it makes sense to review the code commit by commit. I tried to keep the commits reasonably separated, but probably not perfectly everywhere. There are certainly some smaller issues around nonexistent times remaining as outlined in #681.

[axunonb]

The plan for a next PR re Periodwas:

• Change public Perdiod() to internal (should not be part of the public API, see Make parameterless CTORs only needed for ICopyable internal #676). ChangeActivator.CreateInstance(type, true) in CalendarDataType.Copy.
• Timezone of StartTime and EndTime (if set) must be the same (as needed in the iCalendar context anyway)
  That's necessary for EXDATE and RDATE.

[axunonb]

good

[minichma]

Yeah, I also tried throwing if IsFloating != dt.IsFloating, but then all kinds of tests fail. Obviously there are quite some cases where DTSTART has a tzid set but DTEND hasn't, which isn't allowed by the RFC though. We should double-check whether we still want to support this case (probably yes, if its used in the wild). If so, we should probably deal with the case in a different place, probably during deserialization, and be more strict here, because the current implementation is somewhat unclear regarding that case.

[axunonb]

Excellent.
See some minor remarks.
{Edit] Just forgot to mention the nullability warnings like Possible null reference argument for parameter 'dt' in 'Duration IDateTime.Subtract(IDateTime dt)' et al

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[minichma]

@axunonb Thanks for the review! Tried to improve.

[axunonb]

Great job, thanks a lot