Split DateTime Time Ranges interval into smaller ones?

[rklec]

I guess this is a popular use case:

Split an DateTime interval into smaller intervals, e.g. per day, week, month, quarter, year etc.

Aka, so can build statistics etc. with multiple smaller time spans, inside a bigger "range".

I found multiple Stackoverflow questions asking for the same, but given if you want to support many intervals, it easily get's little complex, so maybe this would be a suitable use case for this library?

• Split a period of time into multiple time periods
• Split DateTime range into hour periods
• Split a date range into several ranges?

(Or maybe it is "easily" implemented oneself, so hmm.)

---

I found #4 and thus also asked/opened in this fork: Occurify/Occurify#73

[Giannoudis]

Yes — splitting a larger DateTime range into calendar buckets (day / month / year / hour) is a main use case of this library. You usually do not need a custom loop over AddDays / AddMonths.

1. CalendarPeriodCollector — calendar buckets inside a range

CalendarPeriodCollector walks a limit range and collects matching calendar periods. Without a filter, every unit in that range matches:

var range = new CalendarTimeRange(
    new DateTime(2024, 1, 15, 10, 0, 0),
    new DateTime(2024, 4, 10, 18, 0, 0));

var collector = new CalendarPeriodCollector(
    new CalendarPeriodCollectorFilter(),
    range);

collector.CollectMonths(); // or CollectDays / CollectYears / CollectHours

foreach (ITimePeriod bucket in collector.Periods)
{
    Console.WriteLine(bucket); // one Month / Day / Year / Hour each
}

Split by	Call
Year	CollectYears()
Month	CollectMonths()
Day	CollectDays()
Hour	CollectHours()

Filters are optional, e.g. only working days / only Fridays / only 08:00–18:00 (WeekDays, CollectingHours, ExcludePeriods for holidays). That is the README sample: all Friday working hours in January.

Caveat: a bucket is added only if it is fully inside the limits (HasInside). A range 15 Jan – 10 Apr therefore yields Feb + Mar for CollectMonths(), not the partial January/April. Same idea for the first/last day when you collect days.

If you need those partial edge buckets (typical for statistics), clip with GetIntersection:

var range = new TimeRange(start, end);
var month = new Month(range.Start);

while (month.Start < range.End)
{
    ITimePeriod slice = range.GetIntersection(month); // clipped to the outer range
    // aggregate stats for `slice` / `month`
    month = month.GetNextMonth();
}

Same pattern with Day / GetNextDay(), Week / GetNextWeek(), Quarter / GetNextQuarter(), Year / GetNextYear(), Hour / GetNextHour().

2. Weeks and quarters

There is no CollectWeeks() / CollectQuarters(). Use the calendar types instead:

var year = new Year(2024);

foreach (Quarter quarter in year.GetQuarters()) { /* … */ }
foreach (Week week in year.GetWeeks())         { /* … */ }
foreach (Month month in year.GetMonths())      { /* … */ }

Or new Weeks(start, weekCount) / new Quarters(...) and then GetWeeks() / GetQuarters(). Fiscal/school years: set ITimeCalendar.YearBaseMonth.

3. Statistics over many smaller spans — combine, then intersect

If the input is many overlapping events inside one outer range, consolidate first so duration is not counted twice:

Consolidation of Time Periods

// 1) merge overlapping/adjacent source periods
var combiner = new TimePeriodCombiner<TimeRange>();
ITimePeriodCollection unique = combiner.CombinePeriods(sourcePeriods);

// 2) split the outer range (collector or Month/Day/Week loop as above)
var collector = new CalendarPeriodCollector(new CalendarPeriodCollectorFilter(), outerRange);
collector.CollectDays();

// 3) per bucket: which source periods fall into this day/month/…
foreach (ITimePeriod bucket in collector.Periods)
{
    ITimePeriodCollection hits = unique.IntersectionPeriods(bucket);

    TimeSpan durationInBucket = TimeSpan.Zero;
    foreach (ITimePeriod hit in hits)
    {
        durationInBucket += hit.GetIntersection(bucket).Duration;
    }

    // durationInBucket = stats for this bucket
}

Related helpers:

• TimePeriodCollection.IntersectionPeriods / OverlapPeriods — “what sits in this bucket?”
• TimePeriodIntersector — overlapping parts only
• TimePeriodSubtractor — subtract holidays, downtime, etc. before aggregating

4. Fixed-length slices (not calendar-aligned)

For “every 4 hours” / “every 90 minutes”, TimePeriodChain or TimeBlock.GetNextPeriod() is a better fit than CalendarPeriodCollector.

Summary

Yes, this belongs in the library. CalendarPeriodCollector for year/month/day/hour (plus filters). Calendar types (Week, Quarter, GetNext*) when you also want weeks/quarters or partial edge buckets. TimePeriodCombiner first if source periods overlap and you are building duration statistics.