Refactor UCUM unit handling and improve maintainability

Replaced hardcoded unit strings with `UCUMUnits` constants across the codebase to improve readability, maintainability, and consistency. Added new constants for various UCUM units, including `Year`, `Month`, `Day`, and others. Introduced `DaysPerYearDouble` and `DaysPerMonthDouble` for better precision in date calculations.

Updated `CqlDateTime.cs`, `CqlDateTimeMath.cs`, and `CqlTime.cs` to use these constants, consolidating logic and improving error handling. Added `NotImplementedException` placeholders for certain cases requiring further implementation. Removed the unused `NormalizeTo` method.

Enhanced inline documentation and standardized unit handling to reduce redundancy and potential errors.

Author: baseTwo

Cql/Cql.Abstractions/Abstractions/UCUMUnits.cs

@@ -6,8 +6,6 @@
  * available at https://raw.githubusercontent.com/FirelyTeam/firely-cql-sdk/main/LICENSE
  */
 
-using Hl7.Cql.Iso8601;
-
 namespace Hl7.Cql.Abstractions
 {
     /// <summary>
@@ -28,66 +26,90 @@ public static class UCUMUnits
         public const string Unary = "1";
 
         /// <summary>
-        /// Years (annos in Latin).
+        /// Years ("Annos" in Latin).
         /// </summary>
+        /// <remarks>
+        /// Note that this unit is the same as the value of <see cref="DaysPerYearDouble"/> which is 365.25 days.
+        /// </remarks>
         public const string Year = "a";
+
+        /// <summary>
+        /// Defines days per year
+        /// </summary>
+        /// <remarks>
+        /// Used when specifying <see cref="Year"/>.
+        /// </remarks>
+        public const double DaysPerYearDouble = 365.25d;
+
         /// <summary>
         /// Months
         /// </summary>
+        /// <remarks>
+        /// Note that this unit is the same as the value of <see cref="DaysPerMonthDouble"/> which is 30.4375 days.
+        /// </remarks>
         public const string Month = "mo";
+
+        /// <summary>
+        /// Defines days per month
+        /// </summary>
+        /// <remarks>
+        /// Used when specifying <see cref="Month"/>.
+        /// </remarks>
+        public const double DaysPerMonthDouble = 30.4375d;
+
         /// <summary>
         /// Days
         /// </summary>
         public const string Day = "d";
+
         /// <summary>
         /// Hours
         /// </summary>
         public const string Hour = "h";
+
         /// <summary>
         /// Minutes
         /// </summary>
         public const string Minute = "min";
+
         /// <summary>
         /// Seconds
         /// </summary>
         public const string Second = "s";
+
         /// <summary>
         /// Milliseconds
         /// </summary>
         public const string Millisecond = "ms";
+
         /// <summary>
         /// Weeks, equal to 7 <see cref="Day"/>.
         /// </summary>
         public const string Week = "wk";
+
         /// <summary>
         /// Imperial inches
         /// </summary>
         public const string Inch = "[in_i]";
+
         /// <summary>
         /// Imperial feet
         /// </summary>
         public const string Foot = "[ft_i]";
+
         /// <summary>
         /// Imperial yards
         /// </summary>
         public const string Yard = "[yd_i]";
+
         /// <summary>
         /// Meters
         /// </summary>
         public const string Meter = "m";
+
         /// <summary>
         /// Centimeters
         /// </summary>
         public const string Centimeter = "cm";
-        /// <summary>
-        /// Defines days per year
-        /// </summary> 
-        public const double DaysPerYearDouble = 365.25d;
-        /// <summary>
-        /// Defines days per month
-        /// </summary>
-        public const double DaysPerMonthDouble = 30.4375d;
     }
-
-
 }

Cql/Cql.Abstractions/Primitives/CqlDateTime.cs

@@ -155,7 +155,7 @@ public static bool TryParse(string s, out CqlDateTime? cqlDateTime)
             var dto = Value.DateTimeOffset;
             dto = unit switch
             {
-                "a"                                     => dto.AddDays(Math.Sign(value) * UCUMUnits.DaysPerYearDouble),
+                UCUMUnits.Year                         => dto.AddDays(Math.Sign(value) * UCUMUnits.DaysPerYearDouble),
                 "year" or "years"                       => dto.AddYears((int)value),
                 "mo"                                    => dto.AddDays(Math.Sign(value) * UCUMUnits.DaysPerMonthDouble),
                 "month" or "months"                     => dto.AddMonths((int)value),

Cql/Cql.Abstractions/Primitives/CqlDateTimeMath.cs

@@ -28,20 +28,26 @@ internal static class CqlDateTimeMath
         /// <seealso href="https://cql.hl7.org/09-b-cqlreference.html#difference"/>
         internal static int? BoundariesBetween(DateTimeOffset? low, DateTimeOffset? high, string? precision)
         {
-            if (low == null || high == null || precision == null)
+            if (low is not {} firstDto || high is not {} secondDto || precision is null)
                 return null;
 
-            var firstDto = low.Value;
-            var secondDto = high.Value;
             switch (precision)
             {
+                case UCUMUnits.Year:
+                    throw new NotImplementedException();
+
                 case "year":
                     var yearDiff = (secondDto.Year - firstDto.Year);
                     return yearDiff;
+
+                case UCUMUnits.Month:
+                    throw new NotImplementedException();
+
                 case "month":
                     var monthDiff = (12 * (secondDto.Year - firstDto.Year) + secondDto.Month - firstDto.Month);
                     return monthDiff;
-                case "week":
+
+                case "week" or UCUMUnits.Week:
                     {
                         var span = secondDto.Subtract(firstDto);
                         var weeks = span.TotalDays / 7d;
@@ -52,7 +58,8 @@ internal static class CqlDateTimeMath
                             return asInt + 1;
                         else return asInt;
                     }
-                case "day":
+
+                case "day" or UCUMUnits.Day:
                     {
                         var span = secondDto.Subtract(firstDto);
                         var asInt = (int)span.TotalDays;
@@ -64,7 +71,8 @@ internal static class CqlDateTimeMath
                         }
                         else return asInt;
                     }
-                case "hour":
+
+                case "hour" or UCUMUnits.Hour:
                     {
                         var span = secondDto.Subtract(firstDto);
                         var asInt = (int)span.TotalHours;
@@ -76,7 +84,8 @@ internal static class CqlDateTimeMath
                         }
                         else return asInt;
                     }
-                case "minute":
+
+                case "minute" or UCUMUnits.Minute:
                     {
                         var span = secondDto.Subtract(firstDto);
                         var asInt = (int)span.TotalMinutes;
@@ -88,7 +97,8 @@ internal static class CqlDateTimeMath
                         }
                         else return asInt;
                     }
-                case "second":
+
+                case "second" or UCUMUnits.Second:
                     {
                         var span = secondDto.Subtract(firstDto);
                         var asInt = (int)span.TotalSeconds;
@@ -100,7 +110,8 @@ internal static class CqlDateTimeMath
                         }
                         else return asInt;
                     }
-                case "millisecond":
+
+                case "millisecond" or UCUMUnits.Millisecond:
                     {
                         var span = secondDto.Subtract(firstDto);
                         var asInt = (int)span.TotalMilliseconds;
@@ -112,20 +123,22 @@ internal static class CqlDateTimeMath
                         }
                         else return asInt;
                     }
+
                 default: throw new ArgumentException($"Unit '{precision}' is not supported.");
             }
         }
 
-        internal static int? WholeCalendarPeriodsBetween(DateTimeOffset? low, DateTimeOffset? high, string precision)
+        internal static int? WholeCalendarPeriodsBetween(DateTimeOffset? low, DateTimeOffset? high, string? precision)
         {
-            if (low == null || high == null || precision == null)
+            if (low is not {} firstDto || high is not {} secondDto  || precision == null)
                 return null;
 
             var calendar = new GregorianCalendar();
-            var firstDto = low.Value;
-            var secondDto = high.Value;
             switch (precision)
             {
+                case UCUMUnits.Year:
+                    throw new NotImplementedException();
+
                 case "year":
                     var yearDiff = secondDto.Year - firstDto.Year;
                     var firstDayInYear = firstDto.DayOfYear;
@@ -192,20 +205,25 @@ internal static class CqlDateTimeMath
                     else if (yearDiff < 0 && firstDayInYear < secondDayInYear)
                         yearDiff += 1;
                     return yearDiff;
+
+                case UCUMUnits.Month:
+                    throw new NotImplementedException();
+
                 case "month":
                     var monthDiff = (12 * (secondDto.Year - firstDto.Year) + secondDto.Month - firstDto.Month);
                     if (monthDiff > 0 && secondDto.Day < firstDto.Day)
                         monthDiff -= 1;
                     else if (monthDiff < 0 && firstDto.Day < secondDto.Day)
                         monthDiff += 1;
                     return monthDiff;
-                case "week": return (int)(secondDto.Subtract(firstDto).TotalDays / DaysPerWeekDouble);
-                case "day": return (int)secondDto.Subtract(firstDto).TotalDays;
-                case "hour": return (int)secondDto.Subtract(firstDto).TotalHours;
-                case "minute": return (int)secondDto.Subtract(firstDto).TotalMinutes;
-                case "second": return (int)secondDto.Subtract(firstDto).TotalSeconds;
-                case "millisecond": return (int)secondDto.Subtract(firstDto).TotalMilliseconds;
-                default: throw new ArgumentException($"Unit '{precision}' is not supported.");
+
+                case "week" or UCUMUnits.Week:        return (int)(secondDto.Subtract(firstDto).TotalDays / DaysPerWeekDouble);
+                case "day" or UCUMUnits.Day:         return (int)secondDto.Subtract(firstDto).TotalDays;
+                case "hour" or UCUMUnits.Hour:        return (int)secondDto.Subtract(firstDto).TotalHours;
+                case "minute" or UCUMUnits.Minute:      return (int)secondDto.Subtract(firstDto).TotalMinutes;
+                case "second" or UCUMUnits.Second:      return (int)secondDto.Subtract(firstDto).TotalSeconds;
+                case "millisecond" or UCUMUnits.Millisecond: return (int)secondDto.Subtract(firstDto).TotalMilliseconds;
+                default:                              throw new ArgumentException($"Unit '{precision}' is not supported.");
             }
         }
 
@@ -220,67 +238,67 @@ internal static class CqlDateTimeMath
             { DateTimePrecision.Year, new CqlQuantity(1m, "year") },
         };
 
-        /// <summary>
-        /// For datetime addition and subtraction, when quantity is more precise than the datetime, 
-        /// the quantity has to be normalized to the lesser precision and truncated.
-        /// </summary>
-        /// <see href="https://cql.hl7.org/09-b-cqlreference.html#add-1" />
-        internal static CqlQuantity NormalizeTo(this CqlQuantity quantity, DateTimePrecision target)
-        {
-            // using the table found here:
-            // https://cql.hl7.org/09-b-cqlreference.html#equivalent
-            return (quantity.unit, target) switch
-            {
-                (null, _) => quantity,
-                ("mo", DateTimePrecision.Year) => 
-                    new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 12)!, UCUMUnits.Year),
-                
-                ("d", DateTimePrecision.Year) => 
-                    new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 365)!, UCUMUnits.Year),
-                ("d", DateTimePrecision.Month) =>
-                    new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 30)!, UCUMUnits.Month),
-                
-                ("h", DateTimePrecision.Year) => 
-                    new CqlQuantity(Math.Truncate(((quantity.value ?? 0) / 24) / 365)!, UCUMUnits.Year),
-                ("h", DateTimePrecision.Month) => 
-                    new CqlQuantity(Math.Truncate(((quantity.value ?? 0) / 24) / 30)!, UCUMUnits.Month),
-                ("h", DateTimePrecision.Day) =>
-                    new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 24)!, UCUMUnits.Day),
-                
-                ("mi", DateTimePrecision.Year) => 
-                    new CqlQuantity(Math.Truncate((((quantity.value ?? 0) / 60) / 24) / 365)!, UCUMUnits.Year),
-                ("mi", DateTimePrecision.Month) =>
-                    new CqlQuantity(Math.Truncate((((quantity.value ?? 0) / 60) / 24) / 30)!, UCUMUnits.Month),
-                ("mi", DateTimePrecision.Day) => 
-                    new CqlQuantity(Math.Truncate(((quantity.value ?? 0) / 60) / 24)!, UCUMUnits.Day),
-                ("mi", DateTimePrecision.Hour) =>
-                    new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 60)!, UCUMUnits.Hour),
-
-                ("s", DateTimePrecision.Year) =>
-                    new CqlQuantity(Math.Truncate(((((quantity.value ?? 0) / 60) / 60) / 24) / 365)!, UCUMUnits.Year),
-                ("s", DateTimePrecision.Month) =>
-                    new CqlQuantity(Math.Truncate(((((quantity.value ?? 0) / 60) / 60) / 24) / 30)!, UCUMUnits.Month),
-                ("s", DateTimePrecision.Day) =>
-                    new CqlQuantity(Math.Truncate((((quantity.value ?? 0) / 60) / 60) / 24)!, UCUMUnits.Day),
-                ("s", DateTimePrecision.Hour) =>
-                    new CqlQuantity(Math.Truncate(((quantity.value ?? 0) / 60) / 60)!, UCUMUnits.Hour),
-                ("s", DateTimePrecision.Minute) =>
-                    new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 60)!, UCUMUnits.Minute),
-
-                ("ms", DateTimePrecision.Year) =>
-                    new CqlQuantity(Math.Truncate((((((quantity.value ?? 0) / 1000) / 60) / 60) / 24) / 365)!, UCUMUnits.Year),
-                ("ms", DateTimePrecision.Month) =>
-                    new CqlQuantity(Math.Truncate((((((quantity.value ?? 0) / 1000) / 60) / 60) / 24) / 30)!, UCUMUnits.Month),
-                ("ms", DateTimePrecision.Day) =>
-                    new CqlQuantity(Math.Truncate(((((quantity.value ?? 0) / 1000) / 60) / 60) / 24)!, UCUMUnits.Day),
-                ("ms", DateTimePrecision.Hour) =>
-                    new CqlQuantity(Math.Truncate((((quantity.value ?? 0) / 1000) / 60) / 60)!, UCUMUnits.Hour),
-                ("ms", DateTimePrecision.Minute) =>
-                    new CqlQuantity(Math.Truncate(((quantity.value ?? 0) / 1000) / 60)!, UCUMUnits.Minute),
-                ("ms", DateTimePrecision.Second) =>
-                    new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 1000)!, UCUMUnits.Second),
-                (_,_) => quantity
-            };
-        }
+        // /// <summary>
+        // /// For datetime addition and subtraction, when quantity is more precise than the datetime,
+        // /// the quantity has to be normalized to the lesser precision and truncated.
+        // /// </summary>
+        // /// <see href="https://cql.hl7.org/09-b-cqlreference.html#add-1" />
+        // internal static CqlQuantity NormalizeTo(this CqlQuantity quantity, DateTimePrecision target)
+        // {
+        //     // using the table found here:
+        //     // https://cql.hl7.org/09-b-cqlreference.html#equivalent
+        //     return (quantity.unit, target) switch
+        //     {
+        //         (null, _) => quantity,
+        //         ("mo", DateTimePrecision.Year) =>
+        //             new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 12)!, UCUMUnits.Year),
+        //
+        //         ("d", DateTimePrecision.Year) =>
+        //             new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 365)!, UCUMUnits.Year),
+        //         ("d", DateTimePrecision.Month) =>
+        //             new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 30)!, UCUMUnits.Month),
+        //
+        //         ("h", DateTimePrecision.Year) =>
+        //             new CqlQuantity(Math.Truncate(((quantity.value ?? 0) / 24) / 365)!, UCUMUnits.Year),
+        //         ("h", DateTimePrecision.Month) =>
+        //             new CqlQuantity(Math.Truncate(((quantity.value ?? 0) / 24) / 30)!, UCUMUnits.Month),
+        //         ("h", DateTimePrecision.Day) =>
+        //             new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 24)!, UCUMUnits.Day),
+        //
+        //         ("mi", DateTimePrecision.Year) =>
+        //             new CqlQuantity(Math.Truncate((((quantity.value ?? 0) / 60) / 24) / 365)!, UCUMUnits.Year),
+        //         ("mi", DateTimePrecision.Month) =>
+        //             new CqlQuantity(Math.Truncate((((quantity.value ?? 0) / 60) / 24) / 30)!, UCUMUnits.Month),
+        //         ("mi", DateTimePrecision.Day) =>
+        //             new CqlQuantity(Math.Truncate(((quantity.value ?? 0) / 60) / 24)!, UCUMUnits.Day),
+        //         ("mi", DateTimePrecision.Hour) =>
+        //             new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 60)!, UCUMUnits.Hour),
+        //
+        //         ("s", DateTimePrecision.Year) =>
+        //             new CqlQuantity(Math.Truncate(((((quantity.value ?? 0) / 60) / 60) / 24) / 365)!, UCUMUnits.Year),
+        //         ("s", DateTimePrecision.Month) =>
+        //             new CqlQuantity(Math.Truncate(((((quantity.value ?? 0) / 60) / 60) / 24) / 30)!, UCUMUnits.Month),
+        //         ("s", DateTimePrecision.Day) =>
+        //             new CqlQuantity(Math.Truncate((((quantity.value ?? 0) / 60) / 60) / 24)!, UCUMUnits.Day),
+        //         ("s", DateTimePrecision.Hour) =>
+        //             new CqlQuantity(Math.Truncate(((quantity.value ?? 0) / 60) / 60)!, UCUMUnits.Hour),
+        //         ("s", DateTimePrecision.Minute) =>
+        //             new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 60)!, UCUMUnits.Minute),
+        //
+        //         ("ms", DateTimePrecision.Year) =>
+        //             new CqlQuantity(Math.Truncate((((((quantity.value ?? 0) / 1000) / 60) / 60) / 24) / 365)!, UCUMUnits.Year),
+        //         ("ms", DateTimePrecision.Month) =>
+        //             new CqlQuantity(Math.Truncate((((((quantity.value ?? 0) / 1000) / 60) / 60) / 24) / 30)!, UCUMUnits.Month),
+        //         ("ms", DateTimePrecision.Day) =>
+        //             new CqlQuantity(Math.Truncate(((((quantity.value ?? 0) / 1000) / 60) / 60) / 24)!, UCUMUnits.Day),
+        //         ("ms", DateTimePrecision.Hour) =>
+        //             new CqlQuantity(Math.Truncate((((quantity.value ?? 0) / 1000) / 60) / 60)!, UCUMUnits.Hour),
+        //         ("ms", DateTimePrecision.Minute) =>
+        //             new CqlQuantity(Math.Truncate(((quantity.value ?? 0) / 1000) / 60)!, UCUMUnits.Minute),
+        //         ("ms", DateTimePrecision.Second) =>
+        //             new CqlQuantity(Math.Truncate((quantity.value ?? 0) / 1000)!, UCUMUnits.Second),
+        //         (_,_) => quantity
+        //     };
+        // }
     }
 }