Jacobi.DateTimeOperators 1.1.0

Jacobi DateTime Operators

This package implements operator extensions for DateTime, DateTimeOffset, DateOnly, TimeOnly and TimeSpan.

Note that all of this code is wrapper code and all operations for date-time are implemented using existing methods on the DateTime (and related) types. This will bring down the chance of bugs or inconsistancies.

Key Advantages

1. Readability: Mathematical operations look more natural
2. Maintainability: Less boilerplate code
3. Safety: Type-safe generic constraints ensure valid operations
4. Expressiveness: Natural syntax for manipulating date-time

Usage

Here are some usage examples:

var dt = new DateTime(2025, 11, 21);
var dt1 = dt + 3.Days;

var dt = new DateTime(2025, 11, 21);
var dt1 = dt - 3.M; // Months

var dt = new DateTime(2025, 11, 21, 14, 42, 12);
var dt1 = dt + 7.5.Minutes; // add 7 and a half minutes
// dt1.Minute => 49 (42+7)
// dt1.Second => 42 (12+30)

Type System

The library provides (value) types for every part that plays a role in manipulating date-time.

Examples of how to use the type system:

var years = new Years(2025)   // all value types have a value constructor
var days = 3.d;               // d extension on int returns a Days instance
var days2 = 3.Days;           // use the full name of the extension for readability/preference
var secondsFraction = 2.4.s   // s extension on double returns a SecondsF instance
var ticks = 843710982.t       // t extension on long returns a Ticks instance

Operator Extensions Reference

*) Some operators may introduce an additional value transformation to/from TimeSpan.

Note that TimeSpan already has several overloaded operators for primitive types and arithmetic functions.

Extension Methods

From (static)

All date-time types support From methods for construction with typed parameters:

var years = new Years(2025);
var months = new Months(11);
var days = new Days(21);
var dt = DateTime.From(years, months, days);

The From extension method for DateTimeOffset requires an extra offset parameter (TimeSpan).

Multiple overloads are available per type with different combinations of parameter types.

To

Because the DateTime and related type already have a Deconstruct implementation with 2 and 3 parameters (and for TimeOnly even more), we could not use extensions with the same number of parameters. Instead we've renamed these methods to To.

All date-time types support T methods for deconstructing with typed parameters:

var dt = new DateTime(2025, 11, 21);
dt.To(out Years years, out Months months, out Days days);
// years => 2025
// months => 11
// days => 21

The To extension method for DateTimeOffset returns the offset as a return value.

Multiple overloads are available per type with different combinations of parameter types.

Deconstruct

Deconstruct methods with 2 and 3 parameters are not available for our type system. Us the To method instead.

var dt = new DateTime(2025, 11, 21, 14, 34, 45);
(Years years, Months months, Days days, Hours hours, Minutes minutes, Seconds seconds) = dt;
// years => 2025
// months => 11
// days => 21
// hours => 14
// minutes => 34
// seconds => 45

You may also enjoy the Jacobi.ArrayOperators package that lets you do 'array arithmetic' using operator extensions.