Refactor date/time arithmetic and add operator support

Simplified `Subtract` methods by delegating to `Add` with negated quantities, reducing duplication. Added `+` and `-` operator overloads for `CqlDate`, `CqlDateTime`, and `CqlTime` to enable intuitive arithmetic operations.

Enhanced `CqlQuantity` with negation support via `Negate` method and `-` operator. Improved precision handling in `CqlTime` with explicit handling for `DateTimePrecision.Unknown`.

Fixed arithmetic logic for year (`"a"`) and month (`"mo"`) units to account for value signs. Overrode `Equals` and `GetHashCode` for proper equality and hashing in `CqlDate`, `CqlDateTime`, and `CqlTime`.

Refactored `CqlTime` constructor for compactness and added `MinValue`/`MaxValue` static properties. Improved boundary calculation methods for readability.

Updated test case in `PrimitiveTests.cs` to reflect corrected subtraction logic. Performed general code cleanup to improve readability and maintainability.

Author: baseTwo

Cql/CoreTests/PrimitiveTests.cs

@@ -33,7 +33,7 @@ public void CqlDate_Subtract_Months_From_Year()
         {
             Assert.IsTrue(CqlDateTime.TryParse("2014", out var baseDate));
             var result = baseDate.Subtract(new CqlQuantity(25m, "month"));
-            Assert.AreEqual(2016, result.Value.Year);
+            Assert.AreEqual(2011, result.Value.Year);
             Assert.AreEqual(DateTimePrecision.Year, result.Precision);
         }
 

Cql/Cql.Abstractions/Primitives/CqlDate.cs

@@ -17,7 +17,11 @@ namespace Hl7.Cql.Primitives
     /// </summary>
     /// <see href="https://cql.hl7.org/09-b-cqlreference.html#date"/>
     [CqlPrimitiveType(CqlPrimitiveType.Date)]
-    public class CqlDate : ICqlComparable<CqlDate>, IEquivalentable<CqlDate>
+    public class CqlDate :
+        ICqlComparable<CqlDate>,
+        IEquivalentable<CqlDate>,
+        IAdditionOperators<CqlDate?, CqlQuantity?, CqlDate?>,
+        ISubtractionOperators<CqlDate?, CqlQuantity?, CqlDate?>
     {
         /// <summary>
         /// Defines the minimum value for System dates (@0001-01-01).
@@ -98,9 +102,9 @@ public static bool TryParse(string s, out CqlDate? cqlDate)
             var dto = Value.DateTimeOffset;
             dto = unit switch
             {
-                "a"                                     => dto.AddDays(UCUMUnits.DaysPerYearDouble),
+                "a"                                     => dto.AddDays(Math.Sign(value) * UCUMUnits.DaysPerYearDouble),
                 "year" or "years"                       => dto.AddYears((int)value),
-                "mo"                                    => dto.AddDays(UCUMUnits.DaysPerMonthDouble),
+                "mo"                                    => dto.AddDays(Math.Sign(value) * UCUMUnits.DaysPerMonthDouble),
                 "month" or "months"                     => dto.AddMonths((int)value),
                 "wk" or "week" or "weeks"               => dto.AddDays((int)(value! * CqlDateTimeMath.DaysPerWeek)),
                 "d" or "day" or "days"                  => dto.AddDays((int)value!),
@@ -122,30 +126,7 @@ public static bool TryParse(string s, out CqlDate? cqlDate)
         /// <param name="quantity">The quantity to subtract.</param>
         /// <returns>A new date with <paramref name="quantity"/> subtracted from it.</returns>
         /// <exception cref="ArgumentException">If the quantity is not expressed in supported units, or an overflow occurs.</exception>
-        public CqlDate? Subtract(CqlQuantity? quantity)
-        {
-            if (quantity is not { value: { } value, unit: { } unit })
-                return null;
-
-            var dto = Value.DateTimeOffset;
-            dto = unit switch
-            {
-                "a"                                     => dto.AddDays(-1 * UCUMUnits.DaysPerYearDouble),
-                "year" or "years"                       => dto.AddYears((int)value),
-                "mo"                                    => dto.AddDays(-1 * UCUMUnits.DaysPerMonthDouble),
-                "month" or "months"                     => dto.AddMonths((int)value),
-                "wk" or "week" or "weeks"               => dto.AddDays((int)(value! * CqlDateTimeMath.DaysPerWeek)),
-                "d" or "day" or "days"                  => dto.AddDays((int)value!),
-                "hour" or "hours"                       => dto.AddHours(Math.Truncate((double)value)),
-                "min" or "minute" or "minutes"          => dto.AddMinutes(Math.Truncate((double)value)),
-                "s" or "second" or "seconds"            => dto.AddSeconds(Math.Truncate((double)value)),
-                "ms" or "millisecond" or "milliseconds" => dto.AddMilliseconds(Math.Truncate((double)value)),
-                _                                       => throw new ArgumentException($"Unknown date unit {unit} supplied")
-            };
-            var newIsoDate = new DateIso8601(dto, Value.Precision);
-            var result = new CqlDate(newIsoDate);
-            return result;
-        }
+        public CqlDate? Subtract(CqlQuantity? quantity) => Add(-quantity);
 
         /// <summary>
         /// Gets the component of this date.
@@ -299,15 +280,35 @@ public bool EquivalentToValue(CqlDate other, string? precision) =>
         /// Returns <see cref="DateIso8601.ToString"/> for <see cref="Value"/>.
         /// </summary>
         public override string ToString() => Value.ToString();
+
         /// <summary>
         /// Compares this object to <paramref name="obj"/> for equality.
         /// </summary>
         /// <param name="obj">The object to compare against this value.</param>
         /// <returns><see langword="true"/> if equal.</returns>
         public override bool Equals(object? obj) => Value.Equals((obj as CqlDate)?.Value!);
+
         /// <summary>
         /// Gets the value of <see cref="DateIso8601.GetHashCode"/> for <see cref="Value"/>.
         /// </summary>
         public override int GetHashCode() => Value.GetHashCode();
+
+        /// <summary>
+        /// Adds a specified quantity to a date, returning a new date that is offset by the given quantity.
+        /// </summary>
+        /// <param name="left">The date to which the quantity will be added. May be null.</param>
+        /// <param name="right">The quantity to add to the date. May be null.</param>
+        /// <returns>A new <see cref="CqlDate"/> representing the result of adding <paramref name="right"/> to <paramref
+        /// name="left"/>. Returns null if either argument is null.</returns>
+        public static CqlDate? operator +(CqlDate? left, CqlQuantity? right) => left?.Add(right);
+
+        /// <summary>
+        /// Subtracts the specified quantity from the given date, returning a new date that is offset by the quantity.
+        /// </summary>
+        /// <param name="left">The date from which to subtract the quantity. May be null.</param>
+        /// <param name="right">The quantity to subtract from the date. May be null.</param>
+        /// <returns>A new <see cref="CqlDate"/> representing the result of subtracting <paramref name="right"/> from <paramref
+        /// name="left"/>. Returns null if either argument is null.</returns>
+        public static CqlDate? operator -(CqlDate? left, CqlQuantity? right) => left?.Subtract(right);
     }
 }

Cql/Cql.Abstractions/Primitives/CqlDateTime.cs

@@ -17,7 +17,11 @@ namespace Hl7.Cql.Primitives
     /// </summary>
     /// <see href="https://cql.hl7.org/09-b-cqlreference.html#datetime"/>
     [CqlPrimitiveType(CqlPrimitiveType.DateTime)]
-    public class CqlDateTime : ICqlComparable<CqlDateTime>, IEquivalentable<CqlDateTime>
+    public class CqlDateTime :
+        ICqlComparable<CqlDateTime>,
+        IEquivalentable<CqlDateTime>,
+        IAdditionOperators<CqlDateTime?, CqlQuantity?, CqlDateTime?>,
+        ISubtractionOperators<CqlDateTime?, CqlQuantity?, CqlDateTime?>
     {
         /// <summary>
         /// Defines the minimum value for System date times (@0001-01-01T00:00:00.000Z).
@@ -151,9 +155,9 @@ public static bool TryParse(string s, out CqlDateTime? cqlDateTime)
             var dto = Value.DateTimeOffset;
             dto = unit switch
             {
-                "a"                                     => dto.AddDays(UCUMUnits.DaysPerYearDouble),
+                "a"                                     => dto.AddDays(Math.Sign(value) * UCUMUnits.DaysPerYearDouble),
                 "year" or "years"                       => dto.AddYears((int)value),
-                "mo"                                    => dto.AddDays(UCUMUnits.DaysPerMonthDouble),
+                "mo"                                    => dto.AddDays(Math.Sign(value) * UCUMUnits.DaysPerMonthDouble),
                 "month" or "months"                     => dto.AddMonths((int)value),
                 "wk" or "week" or "weeks"               => dto.AddDays((int)(value! * CqlDateTimeMath.DaysPerWeek)),
                 "d" or "day" or "days"                  => dto.AddDays((int)value!),
@@ -175,31 +179,7 @@ public static bool TryParse(string s, out CqlDateTime? cqlDateTime)
         /// <param name="quantity">The quantity to subtract.</param>
         /// <returns>A new date time with <paramref name="quantity"/> subtracted from it.</returns>
         /// <exception cref="ArgumentException">If the quantity is not expressed in supported units, or an overflow occurs.</exception>
-        public CqlDateTime? Subtract(CqlQuantity quantity)
-        {
-            if (quantity is not { value: { } value, unit: { } unit })
-                return null;
-
-            var dto = Value.DateTimeOffset;
-            dto = unit switch
-            {
-                "a"                                     => dto.AddDays(-1 * UCUMUnits.DaysPerYearDouble),
-                "year" or "years"                       => dto.AddYears((int)value),
-                "mo"                                    => dto.AddDays(-1 * UCUMUnits.DaysPerMonthDouble),
-                "month" or "months"                     => dto.AddMonths((int)value),
-                "wk" or "week" or "weeks"               => dto.AddDays((int)(value! * CqlDateTimeMath.DaysPerWeek)),
-                "d" or "day" or "days"                  => dto.AddDays((int)value!),
-                "h" or "hour" or "hours"                => dto.AddHours(Math.Truncate((double)value)),
-                "min" or "minute" or "minutes"          => dto.AddMinutes(Math.Truncate((double)value)),
-                "s" or "second" or "seconds"            => dto.AddSeconds(Math.Truncate((double)value)),
-                "ms" or "millisecond" or "milliseconds" => dto.AddMilliseconds(Math.Truncate((double)value)),
-                _                                       => throw new ArgumentException($"Unknown date unit {unit} supplied")
-            };
-
-            var newIsoDate = new DateTimeIso8601(dto, Value.Precision);
-            var result = new CqlDateTime(newIsoDate);
-            return result;
-        }
+        public CqlDateTime? Subtract(CqlQuantity? quantity) => Add(-quantity);
 
         /// <summary>
         /// Gets the component of this date time.
@@ -503,15 +483,36 @@ public bool EquivalentToValue(CqlDateTime other, string? precision) =>
         /// Returns <see cref="DateTimeIso8601.ToString"/> for <see cref="Value"/>.
         /// </summary>
         public override string ToString() => Value.ToString();
+
         /// <summary>
         /// Compares this object to <paramref name="obj"/> for equality.
         /// </summary>
         /// <param name="obj">The object to compare against this value.</param>
         /// <returns><see langword="true"/> if equal.</returns>
         public override bool Equals(object? obj) => Value.Equals((obj as CqlDateTime)?.Value!);
+
         /// <summary>
         /// Gets the value of <see cref="DateTimeIso8601.GetHashCode"/> for <see cref="Value"/>.
         /// </summary>
         public override int GetHashCode() => Value.GetHashCode();
+
+        /// <summary>
+        /// Adds a specified quantity to a CqlDateTime value, returning a new CqlDateTime that represents the result.
+        /// </summary>
+        /// <param name="left">The CqlDateTime value to which the quantity will be added. May be null.</param>
+        /// <param name="right">The CqlQuantity representing the amount to add to the date and time. May be null.</param>
+        /// <returns>A new CqlDateTime that is the result of adding the specified quantity to the original value, or null if
+        /// either operand is null.</returns>
+        public static CqlDateTime? operator +(CqlDateTime? left, CqlQuantity? right) => left?.Add(right);
+
+        /// <summary>
+        /// Subtracts a specified quantity from a CqlDateTime value, returning a new CqlDateTime that represents the
+        /// result.
+        /// </summary>
+        /// <param name="left">The CqlDateTime value from which to subtract. May be null.</param>
+        /// <param name="right">The CqlQuantity value to subtract from the CqlDateTime. May be null.</param>
+        /// <returns>A new CqlDateTime representing the result of subtracting the specified quantity from the original date and
+        /// time, or null if either operand is null.</returns>
+        public static CqlDateTime? operator -(CqlDateTime? left, CqlQuantity? right) => left?.Subtract(right);
     }
 }

Cql/Cql.Abstractions/Primitives/CqlQuantity.cs

@@ -6,16 +6,14 @@
  * available at https://raw.githubusercontent.com/FirelyTeam/firely-cql-sdk/main/LICENSE
  */
 
-using Hl7.Cql.Abstractions;
-
 namespace Hl7.Cql.Primitives
 {
     /// <summary>
     /// Implements the System Quantity type.
     /// </summary>
     /// <see href="https://cql.hl7.org/09-b-cqlreference.html#quantity"/>
     [CqlPrimitiveType(CqlPrimitiveType.Quantity)]
-    public class CqlQuantity
+    public class CqlQuantity : IUnaryNegationOperators<CqlQuantity?, CqlQuantity?>
     {
         /// <summary>
         /// Creates an instance.
@@ -98,5 +96,14 @@ public static bool TryParse(string s, out CqlQuantity? q)
             else return v;
         }
 
+        public static CqlQuantity? operator -(CqlQuantity? value) => Negate(value)!;
+
+        public static CqlQuantity? Negate(CqlQuantity? cqlQuantity) =>
+            cqlQuantity switch
+            {
+                { value: { } value, unit: var unit } => new CqlQuantity(-value, unit),
+                { value: null, unit: var unit }      => new CqlQuantity(null, unit),
+                null                                 => null,
+            };
     }
 }