ValiDate

IValiDate provides fluent date arithmetic, comparison, and introspection methods. It is registered alongside IValiTime when you call AddValiTime() or AddValiTempo().

IValiDate API

Diff

Calculate the difference between two dates in a given time unit, with decimal precision:

decimal days = date.Diff(DateTime.Today, new DateTime(2025, 12, 31), TimeUnit.Days);
// → e.g. 282.0

decimal months = date.Diff(new DateTime(2024, 1, 1), new DateTime(2025, 6, 15), TimeUnit.Months);
// → ~17.45

Signature: decimal Diff(DateTime from, DateTime to, TimeUnit unit)

Add

Add a decimal amount of a given unit to a date:

DateTime result = date.Add(DateTime.Today, 2.5m, TimeUnit.Hours);
DateTime future = date.Add(DateTime.Today, 3m, TimeUnit.Months);
DateTime later  = date.Add(DateTime.Today, 1.5m, TimeUnit.Years);

Signature: DateTime Add(DateTime dt, decimal amount, TimeUnit unit)

Subtract

Subtract a decimal amount of a given unit from a date:

DateTime pastWeek = date.Subtract(DateTime.Today, 1m, TimeUnit.Weeks);
DateTime lastYear = date.Subtract(DateTime.Today, 365m, TimeUnit.Days);

Signature: DateTime Subtract(DateTime dt, decimal amount, TimeUnit unit)

StartOf

Get the start of a period (day, week, month, quarter, year):

DateTime startOfMonth = date.StartOf(DateTime.Today, DatePart.Month);
// → First day of current month, time 00:00:00

DateTime startOfYear = date.StartOf(DateTime.Today, DatePart.Year);
// → January 1st of current year

DateTime startOfWeek = date.StartOf(DateTime.Today, DatePart.DayOfWeek);
// → Monday (or Sunday) of current week

Signature: DateTime StartOf(DateTime dt, DatePart part)

EndOf

Get the end of a period (inclusive — last tick of that period):

DateTime endOfMonth = date.EndOf(DateTime.Today, DatePart.Month);
// → Last day of current month, time 23:59:59.9999999

DateTime endOfYear = date.EndOf(DateTime.Today, DatePart.Year);
// → December 31st, 23:59:59.9999999

Signature: DateTime EndOf(DateTime dt, DatePart part)

IsBefore

Check if a date is strictly before another:

bool result = date.IsBefore(new DateTime(2024, 1, 1), new DateTime(2025, 1, 1));
// → true

Signature: bool IsBefore(DateTime dt, DateTime other)

IsAfter

Check if a date is strictly after another:

bool result = date.IsAfter(DateTime.Today, new DateTime(2020, 1, 1));
// → true

Signature: bool IsAfter(DateTime dt, DateTime other)

IsSameDay

Check if two dates fall on the same calendar day:

bool same = date.IsSameDay(new DateTime(2025, 3, 15, 8, 0, 0), new DateTime(2025, 3, 15, 20, 0, 0));
// → true (same day, different time)

Signature: bool IsSameDay(DateTime a, DateTime b)

IsSamePeriod

Check if two dates fall in the same calendar period:

bool sameMonth = date.IsSamePeriod(new DateTime(2025, 3, 5), new DateTime(2025, 3, 28), DatePart.Month);
// → true

bool sameYear = date.IsSamePeriod(new DateTime(2025, 1, 1), new DateTime(2025, 12, 31), DatePart.Year);
// → true

Signature: bool IsSamePeriod(DateTime a, DateTime b, DatePart part)

IsWeekend

Return true if the date falls on Saturday or Sunday:

bool weekend = date.IsWeekend(new DateTime(2025, 3, 15)); // Saturday
// → true

Signature: bool IsWeekend(DateTime dt)

IsWeekday

Return true if the date falls on Monday through Friday:

bool weekday = date.IsWeekday(new DateTime(2025, 3, 17)); // Monday
// → true

Signature: bool IsWeekday(DateTime dt)

IsLeapYear

Return true if the year of the given date is a leap year:

bool leap = date.IsLeapYear(new DateTime(2024, 6, 1));
// → true

bool notLeap = date.IsLeapYear(new DateTime(2025, 6, 1));
// → false

Signature: bool IsLeapYear(DateTime dt)

DaysInMonth

Return the number of days in the month of the given date:

int days = date.DaysInMonth(new DateTime(2024, 2, 10)); // Leap February
// → 29

int days2 = date.DaysInMonth(new DateTime(2025, 1, 5));
// → 31

Signature: int DaysInMonth(DateTime dt)

WeekOfYear

Return the ISO 8601 week number for the given date:

int week = date.WeekOfYear(new DateTime(2025, 1, 6));
// → 2

int week2 = date.WeekOfYear(new DateTime(2025, 12, 29), WeekStart.Monday);
// → 1 (ISO 8601 — first week of 2026)

Signature: int WeekOfYear(DateTime dt, WeekStart? weekStart = null)

WeekYear

Return the ISO year that owns the calendar week containing the given date. Near ISO year boundaries this may differ from date.Year:

// Dec 31, 2018 falls in ISO week 1 of 2019
int y = date.WeekYear(new DateTime(2018, 12, 31)); // 2019

// For WeekStart.Sunday the method always returns date.Year
int y2 = date.WeekYear(new DateTime(2018, 12, 31), WeekStart.Sunday); // 2018

Signature: int WeekYear(DateTime date, WeekStart? weekStart = null)

DayOfYear

Return the one-based day number of the year (1–366):

int day = date.DayOfYear(new DateTime(2025, 2, 1));
// → 32

Signature: int DayOfYear(DateTime dt)

ProgressInYear

Return a value between 0.0 and 1.0 representing how far through the year the date is:

decimal progress = date.ProgressInYear(new DateTime(2025, 7, 1));
// → ~0.496 (roughly halfway)

Signature: decimal ProgressInYear(DateTime dt)

ProgressInMonth

Return a value between 0.0 and 1.0 representing how far through the month the date is:

decimal progress = date.ProgressInMonth(new DateTime(2025, 3, 15));
// → ~0.484 (day 15 of 31)

Signature: decimal ProgressInMonth(DateTime dt)

Complete Example

public class DeadlineTracker(IValiDate date)
{
    public void AnalyzeDeadline(DateTime deadline)
    {
        var now = DateTime.Now;

        // Days and weeks remaining
        decimal daysLeft  = date.Diff(now, deadline, TimeUnit.Days);
        decimal weeksLeft = date.Diff(now, deadline, TimeUnit.Weeks);

        // Deadline characteristics
        bool isWeekend  = date.IsWeekend(deadline);
        int  weekNum    = date.WeekOfYear(deadline);
        int  dayOfYear  = date.DayOfYear(deadline);
        decimal yearProg = date.ProgressInYear(deadline);

        // Start/end of deadline's month
        DateTime monthStart = date.StartOf(deadline, DatePart.Month);
        DateTime monthEnd   = date.EndOf(deadline, DatePart.Month);

        Console.WriteLine($"Days remaining:   {daysLeft:F0}");
        Console.WriteLine($"Weeks remaining:  {weeksLeft:F1}");
        Console.WriteLine($"Falls on weekend: {isWeekend}");
        Console.WriteLine($"ISO week number:  {weekNum}");
        Console.WriteLine($"Day of year:      {dayOfYear}");
        Console.WriteLine($"Year progress:    {yearProg:P1}");
        Console.WriteLine($"Month span:       {monthStart:MMM dd} – {monthEnd:MMM dd}");
    }
}