Zmplr.Chronometry 2026.0.0

Zmplr.Chronometry

Zmplr.Chronometry is a small .NET library of DateTime helpers, inclusive date intervals, calendar slicing, and Christian movable-feast dates. Use it when you need weekday navigation, period boundaries (week / month / quarter / season), day enumeration between two dates, or interval set operations without pulling in a heavy calendar framework.

It is deliberately focused on calendar dates (day granularity). It is not a time-zone database, NodaTime replacement, or business-holiday calendar for every country.

What it does

• Date navigation — next/previous Monday–Sunday (nth occurrence), first/last day of week/month/year
• Period boundaries — calendar quarter, half-year, and season as Interval values
• Inclusive ranges — enumerate days, weekdays, weekends, months, and years between two dates
• Duration counts — days/weeks/months/quarters/years left or until a date; hour spans with DST-aware UTC conversion
• Intervals — contain, intersect, except, and slice a range into calendar units
• Movable feasts — Easter and related Western Christian dates for a given year
• EU daylight-saving markers — last Sunday of March / October helpers

Mental model

Requirements

Multi-targets:

No extra runtime packages are required.

Install

dotnet add package Zmplr.Chronometry

using Zmplr.Chronometry;

Quick start

using Zmplr.Chronometry;

var today = new DateTime(2026, 8, 9); // Sunday

// Week boundaries (Monday–Sunday)
var weekStart = today.FirstDayOfWeek();  // 2026-08-03
var weekEnd   = today.LastDayOfWeek();   // 2026-08-09

// Next / previous weekday
var nextMonday = today.NextMonday();     // 2026-08-10
var prevFriday = today.PrevFriday(2);    // second Friday before today

// Period containing a date
Interval q3 = today.Quarter();           // 2026-07-01 .. 2026-09-30
int q       = today.QuarterOrdinal();    // 3

// Inclusive day walk and weekday filter
var days = new DateTime(2026, 2, 15).WeekDaysUntil(new DateTime(2026, 2, 28));
// 10 weekdays

// Slice a multi-year span into decades
var span = new Interval(new DateTime(1968, 10, 4), new DateTime(2018, 10, 4));
Interval[] decades = span.Slice(CalendarUnit.Decade).ToArray();

// Easter family for a year
DateTime easter = HolidayExtensions.EasterSunday(2026);
DateTime goodFriday = HolidayExtensions.GoodFriday(2026);

DateTime extensions

All methods are in DateTimeExtensions under Zmplr.Chronometry.

Week, month, and year boundaries

new DateTime(2019, 3, 5).FirstDayOfWeek(); // 2019-03-04 (Monday)
new DateTime(2019, 3, 5).LastDayOfWeek();  // 2019-03-10 (Sunday)
new DateTime(2000, 2, 15).LastDayOfMonth(); // 2000-02-29

Quarters, half-years, and seasons

var d = new DateTime(2026, 11, 15);
d.Quarter();   // 2026-10-01 .. 2026-12-31
d.HalfYear();  // 2026-07-01 .. 2026-12-31
d.Season();    // 2026-10-01 .. 2027-03-31

Next and previous weekdays

NextMonday … NextSunday and PrevMonday … PrevSunday take an optional count (default 1) for the nth occurrence strictly after or strictly before self. count must be > 0.

var today = new DateTime(2016, 10, 4); // Tuesday
today.NextMonday();    // 2016-10-10
today.NextTuesday(2);  // 2016-10-18
today.PrevFriday();    // 2016-09-30

Enumerate and count until a date

Ranges are inclusive of both endpoints unless noted.

var from = new DateTime(2010, 2, 15);
var to   = new DateTime(2010, 2, 28);

from.NumberOfDaysLeftInMonth();           // 13
from.WeekDaysUntil(to).Count();           // 10
from.HoursUntil(new DateTime(2003, 3, 31)); // 743 in a European spring-forward month

Daylight saving (EU-style)

These match common EU transition dates, not arbitrary IANA zones. Use a proper time-zone library when you need zone rules.

Misc

Interval

Interval is an inclusive calendar-day range with Start, Stop, and TimeSpan (Stop - Start).

var interval = new Interval(new DateTime(2026, 1, 1), new DateTime(2026, 1, 31));
interval.Contains(new DateTime(2026, 1, 15)); // true
interval.TimeSpan; // 30 days in ticks

Containment and set operations

var a = new Interval(new DateTime(2026, 1, 1), new DateTime(2026, 1, 20));
var b = new Interval(new DateTime(2026, 1, 10), new DateTime(2026, 1, 31));

Interval overlap = a.Intersect(b);
// Start = 2026-01-10, Stop = 2026-01-20

Slice by calendar unit

IEnumerable<Interval> Slice(CalendarUnit calendarUnit);
static IEnumerable<Interval> Slice(DateTime from, DateTime to, CalendarUnit calendarUnit);

Splits the interval into sub-intervals of the given unit. The first and last pieces may be partial (e.g. a week that does not start on Monday).

Supported by Slice:

HalfYear and Season exist on the enum for use with DateTime helpers (HalfYear(), Season()); they are not implemented in Interval.Slice.

var from = new DateTime(1968, 10, 4);
var to   = new DateTime(2018, 10, 4);
var decades = new Interval(from, to).Slice(CalendarUnit.Decade).ToArray();
// 6 decade slices across the span

Weekdays inside an interval

interval.Mondays();
interval.Tuesdays();
// ...
interval.Sundays();
interval.FilterOnDayOfWeek(DayOfWeek.Wednesday);

Returns ordered DateTime[] of matching calendar days in [Start, Stop].

Holidays (movable feasts)

HolidayExtensions computes Western Christian movable dates from Easter for a given year (Computus). These are not a full public-holiday calendar (no fixed national holidays, no Orthodox Easter).

int year = 2026;
var easter = HolidayExtensions.EasterSunday(year);
var advent = HolidayExtensions.FirstSundayOfAdvent(year);

Design notes and caveats

1. Calendar days, not instants — Most helpers ignore time-of-day or normalize to dates. Prefer DateTime.Date inputs when mixing with timestamps.
2. Inclusive intervals — Interval and *Until enumerations include both ends.
3. Monday-based weeks — Consistent with ISO week start; differs from CultureInfo calendars that start on Sunday.
4. HoursUntil and DST — Converts date bounds to UTC so spring-forward / fall-back days can yield 23 or 25 hours. Behaviour depends on the local system’s time-zone conversion rules.
5. No IANA / NodaTime — For zone-safe scheduling across regions, compose this library with TimeZoneInfo or NodaTime; do not treat EU DST helpers as global truth.
6. Holiday scope — Easter-derived dates only; build country-specific holiday sets yourself on top if needed.
7. CalendarUnit.HalfYear / Season in Slice — Use DateTime.HalfYear() / Season() (or custom grouping); Slice does not expand those units today.

Package contents

Source: github.com/mtanneryd/zmplr.chronometry

Versioning

Package versions are produced with GitVersion (same scheme as other Zmplr libraries):

License

Licensed under the Apache License, Version 2.0.