We all know DateTime and TimeSpan. Sometimes, however, the question is about calendar years and months, or about keeping the endpoints of a period alongside its duration.
Cuemon provides DateSpan, DateTimeRange, and TimeRange for those cases. They share the Cuemon namespace but serve different purposes.
Note
Originally published on the Cuemon blog on 1 October 2018. The publication date and original image are retained; the examples have been updated for Cuemon 11.0.0. These types now live in Cuemon.Kernel. Reference that package directly when upgrading: Cuemon.Core no longer forwards the moved types.
Compare with the original Cuemon blog version, captured 14 November 2026: Read archived webpage. The archive includes later edits made on the original blog; historical links are inactive.
dotnet add package Cuemon.Kernel --version 11.0.0
DateSpan
DateSpan is a readonly struct for calculating an interval between two dates. The two-date constructor uses the invariant culture's calendar; another overload accepts a Calendar explicitly. It normalizes the endpoints, so reversing the arguments produces the same interval.
The original example measured the interval from New Year's Day to the day this article was published. Keeping both dates explicit makes the output reproducible:
using System;
using System.Globalization;
using Cuemon;
namespace DateExamples;
internal static class Program
{
private static void Main()
{
var span = new DateSpan(
new DateTime(2018, 1, 1),
new DateTime(2018, 10, 1));
Console.WriteLine($"{span.Years} years");
Console.WriteLine($"{span.Months} months");
Console.WriteLine($"{span.GetWeeks()} weeks");
Console.WriteLine($"{span.TotalDays} days");
Console.WriteLine($"{span.TotalHours} hours");
Console.WriteLine(span.TotalMinutes.ToString("N0", CultureInfo.InvariantCulture) + " minutes");
Console.WriteLine(span.TotalSeconds.ToString("N0", CultureInfo.InvariantCulture) + " seconds");
}
}
0 years
9 months
40 weeks
273 days
6552 hours
393,120 minutes
23,587,200 seconds
Months is the number of months accumulated across the interval, rather than a remainder constrained to 0–11. GetWeeks() uses Cuemon's calendar-boundary calculation; it is not simply elapsed days divided by seven. Use date subtraction when the requirement is an elapsed TimeSpan, and review calendar-specific behavior before using DateSpan for domain rules.
DateTimeRange
DateTimeRange is a class derived from Range<DateTime>. It retains Start, End, and a TimeSpan named Duration. The default duration is end - start.
var range = new DateTimeRange(
new DateTime(2021, 1, 1),
new DateTime(2021, 5, 3));
Console.WriteLine(range);
A duration of 122.00:00:00 between 2021-01-01T00:00:00 and 2021-05-03T00:00:00.
Unlike DateSpan, this type preserves the supplied endpoint order. It does not normalize the dates or convert time zones. Supply consistently interpreted dates and decide whether a reversed range is valid for your application.
TimeRange
TimeRange represents a period between two TimeSpan values:
var range = new TimeRange(TimeSpan.FromHours(4), TimeSpan.FromHours(6));
Console.WriteLine(range);
A duration of 00.02:00:00 between 04:00:00 and 06:00:00.
Cuemon 11 also accepts an optional duration resolver. For example, an application that interprets 22:00–02:00 as an overnight period can state that rule explicitly:
var overnight = new TimeRange(
TimeSpan.FromHours(22),
TimeSpan.FromHours(2),
() => TimeSpan.FromHours(4));
Console.WriteLine(overnight.Duration); // 04:00:00
The resolver supplies Duration during construction; it does not change the endpoints. Without it, the same endpoints produce a negative twenty-hour duration, because midnight rollover is not inferred.
DateSpan answers calendar-interval questions. The two range classes keep a period's endpoints and duration together. Choose according to the question your code needs to answer.
Code with passion.
Timeline
These stable-version snapshots trace the date and range APIs through their rename, calculation fixes, and current package boundary. The earliest snapshot establishes availability, rather than a first-ever introduction.
v5.1.20192019-02-09DateSpan and the original TimeRange lived in Cuemon.Core.
The tagged source contains calendar-aware
DateSpanconstructors and aTimeRangestruct whose endpoints areDateTimevalues. This is the earlier meaning of the name used in the original article.v6.0.02021-04-18DateTimeRange and TimeRange became separate range classes.
The date-based responsibility moved to
DateTimeRange : Range<DateTime>.TimeRange : Range<TimeSpan>represents the interval between twoTimeSpanvalues. Both classes still belonged to Cuemon.Core.v6.1.02021-05-16DateSpan's TotalYears calculation was corrected.
The package release notes identify the
TotalYearsfix, following a separate DateSpan correction in v6.0.1. These were calculation fixes to the existing type, rather than new date abstractions.v10.1.02025-12-06DateSpan's equality and hash-code implementation was optimized.
The implementation compares stored endpoints and calendar identity, with hash computation over the same state. The release documents this as an optimization of the existing struct.
v11.0.02026-11-11(current)The primitives moved to Cuemon.Kernel, and TimeRange gained a duration resolver.
DateSpan,DateTimeRange,Range<T>, andTimeRangenow belong to Cuemon.Kernel while retaining theCuemonnamespace. Cuemon.Core no longer forwards the moved types.TimeRangeaccepts an optional duration delegate; consumers of its former constructor binary signature must rebuild.
