Core Types

Detailed documentation for Pragmatic.Temporal types.

LocalDate

Represents a calendar date without time or timezone. Use for dates that are meaningful regardless of timezone.

Creation

// From components
var date = new LocalDate(2024, 6, 15);

// From DateTime
var fromDt = LocalDate.FromDateTime(DateTime.Now);

// From DateTimeOffset
var fromDto = LocalDate.FromDateTimeOffset(DateTimeOffset.Now);

// Today
var today = LocalDate.Today;

Properties

var date = new LocalDate(2024, 6, 15);

date.Year        // 2024
date.Month       // 6
date.Day         // 15
date.DayOfWeek   // DayOfWeek.Saturday
date.DayOfYear   // 167
date.IsWeekend   // true
date.IsWeekday   // false

Arithmetic

var date = new LocalDate(2024, 6, 15);

date.AddDays(7)      // 2024-06-22
date.AddMonths(1)    // 2024-07-15
date.AddYears(1)     // 2025-06-15

date.DaysBetween(other)  // Days between dates

Navigation

var date = new LocalDate(2024, 6, 15);

date.StartOfMonth()  // 2024-06-01
date.EndOfMonth()    // 2024-06-30
date.StartOfYear()   // 2024-01-01
date.EndOfYear()     // 2024-12-31

Combining with Time

var date = new LocalDate(2024, 6, 15);
var time = new LocalTime(14, 30);

var dateTime = date.At(time);  // LocalDateTime

LocalTime

Represents a time of day without date or timezone.

Creation

// From components
var time = new LocalTime(14, 30);           // 14:30:00
var withSeconds = new LocalTime(14, 30, 45); // 14:30:45

// From TimeOnly
var fromTimeOnly = new LocalTime(TimeOnly.Now);

// From DateTime (extracts time part)
var fromDt = LocalTime.FromDateTime(DateTime.Now);

Properties

var time = new LocalTime(14, 30, 45);

time.Hour    // 14
time.Minute  // 30
time.Second  // 45

Arithmetic

var time = new LocalTime(14, 30);

time.AddHours(2)     // 16:30
time.AddMinutes(30)  // 15:00

LocalDateTime

Represents a date and time without timezone. Use for wall clock times.

Creation

// From components
var dt = new LocalDateTime(2024, 6, 15, 14, 30);

// From LocalDate and LocalTime
var date = new LocalDate(2024, 6, 15);
var time = new LocalTime(14, 30);
var dt2 = date.At(time);

// From DateTime
var fromDt = LocalDateTime.FromDateTime(DateTime.Now);

Properties

var dt = new LocalDateTime(2024, 6, 15, 14, 30);

dt.Date  // LocalDate
dt.Time  // LocalTime
dt.Year, dt.Month, dt.Day
dt.Hour, dt.Minute, dt.Second

Conversion to ZonedDateTime

var local = new LocalDateTime(2024, 6, 15, 14, 30);

// Interpret as a specific timezone
var zoned = local.InZone("Europe/Rome");

ZonedDateTime

Represents a specific instant in time with full timezone awareness.

Creation

// From UTC
var zoned = ZonedDateTime.FromUtc(DateTimeOffset.UtcNow, "Europe/Rome");

// From local datetime in a zone
var local = new LocalDateTime(2024, 6, 15, 14, 30);
var zoned2 = ZonedDateTime.FromLocal(local, "America/New_York");

// Now in a timezone
var nowInRome = ZonedDateTime.NowIn("Europe/Rome");

Properties

var zoned = ZonedDateTime.FromUtc(DateTimeOffset.UtcNow, "Europe/Rome");

zoned.DateTime  // DateTimeOffset (UTC)
zoned.Zone      // "Europe/Rome"
zoned.Offset    // Current UTC offset (e.g., +02:00)
zoned.LocalDateTime  // LocalDateTime in that zone

Timezone Conversion

var rome = ZonedDateTime.NowIn("Europe/Rome");
var tokyo = rome.InZone("Asia/Tokyo");
var utc = rome.ToUtc();

Duration

Represents a time span. Similar to TimeSpan but with better factory methods.

Creation

var d1 = Duration.FromHours(2);
var d2 = Duration.FromMinutes(30);
var d3 = Duration.FromSeconds(45);
var d4 = Duration.FromDays(7);

// Combined
var d5 = Duration.FromHours(2) + Duration.FromMinutes(30);

Properties

var duration = Duration.FromHours(2.5);

duration.TotalHours    // 2.5
duration.TotalMinutes  // 150
duration.TotalSeconds  // 9000

Arithmetic

var d1 = Duration.FromHours(1);
var d2 = Duration.FromMinutes(30);

var sum = d1 + d2;       // 1:30:00
var diff = d1 - d2;      // 0:30:00
var scaled = d1 * 2;     // 2:00:00

CronExpression

Represents a cron schedule for recurring events.

Factory Methods

// Common patterns
var hourly = CronExpression.Hourly();
var daily = CronExpression.Daily(new TimeOnly(9, 0));
var weekly = CronExpression.Weekly(DayOfWeek.Monday, new TimeOnly(8, 0));
var monthly = CronExpression.Monthly(1, new TimeOnly(0, 0)); // First of month

// Custom expression
var custom = CronExpression.Parse("0 */15 9-17 * * 1-5");

Getting Occurrences

var cron = CronExpression.Daily(new TimeOnly(9, 0));

// Next occurrence
var next = cron.GetNextOccurrence(DateTimeOffset.UtcNow);

// Multiple occurrences
var nextFive = cron.GetNextOccurrences(DateTimeOffset.UtcNow, 5);

Type Comparison

Type	Has Date	Has Time	Has Timezone	Use Case
LocalDate	✅	❌	❌	Birthdays, holidays
LocalTime	❌	✅	❌	Store hours, schedules
LocalDateTime	✅	✅	❌	Wall clock appointments
ZonedDateTime	✅	✅	✅	Flight times, global events
Duration	❌	✅	❌	Time intervals, durations