SmartDateTime 1.0.0

SmartDateTimeLib

SmartDateTimeLib is a C# library for intelligent date and time handling.
It provides fuzzy parsing, safe time zone conversions, relative date strings, rounding, and utility functions — all powered by NodaTime for accurate and robust time zone support.

Features

• Fuzzy date parsing: "now", "today", "tomorrow", "yesterday", "next Friday", "3 days ago", "in 5 days"
• Time zone aware: works with TZDB names like "America/New_York", "Asia/Tokyo"
• Fluent date arithmetic: add days, hours, minutes, or seconds
• Rounding & checks: round to nearest hour, check if weekend
• Custom formatting: output dates in any string format
• Extension methods: helpers for regular DateTime objects

Installation

Via NuGet:

Install-Package SmartDateTimeLib


### .NET CLI

```bash
dotnet add package SmartDateTimeLib

Dependencies
Automatically installs:

• NodaTime (≥ 3.1.0)

Quick Start

using SmartDateTimeLib;
using System;

var dt = SmartDateTime.ParseSafe("next Friday at 3pm", "America/New_York");

Console.WriteLine(dt);                           // → 2026-02-06 15:00:00 -05:00 (America/New_York)
Console.WriteLine(dt.ToUtc());                   // → 2026-02-06 20:00:00Z
Console.WriteLine(dt.ToRelativeString());        // → "in 3 days"   (assuming today = 2026-02-03)
Console.WriteLine(dt.ToFormattedString("ddd MMM d 'at' h:mm tt"));  // → "Fri Feb 6 at 3:00 PM"
Console.WriteLine(dt.IsWeekend());               // → true
Console.WriteLine(dt.RoundToNearestHour());      // → 2026-02-06 15:00:00 -05:00

// Chain operations fluently
var future = dt
    .AddBusinessDays(10)
    .AddHours(4)
    .ToTimeZone("Asia/Tokyo");

Console.WriteLine(future);                       // → 2026-02-20 12:00:00 +09:00 (Asia/Tokyo)

Parsing Examples (as of February 03, 2026)

string[] tests = {
    "now",
    "today",
    "tomorrow",
    "yesterday",
    "next monday",
    "last friday",
    "in 2 hours",
    "3 days ago",
    "2 weeks from now",
    "end of month",
    "start of next month",
    "black friday 2026"
};

foreach (var text in tests)
{
    var parsed = SmartDateTime.ParseSafe(text, "America/New_York");
    Console.WriteLine($"{text,-20} → {parsed:yyyy-MM-dd HH:mm} ({parsed.TimeZoneId})");
}

Sample output (on 2026-02-03):

now                  → 2026-02-03 14:30 (America/New_York)
today                → 2026-02-03 00:00 (America/New_York)
tomorrow             → 2026-02-04 00:00 (America/New_York)
yesterday            → 2026-02-02 00:00 (America/New_York)
next monday          → 2026-02-09 00:00 (America/New_York)
last friday          → 2026-01-30 00:00 (America/New_York)
in 2 hours           → 2026-02-03 16:30 (America/New_York)
3 days ago           → 2026-01-31 14:30 (America/New_York)
2 weeks from now     → 2026-02-17 14:30 (America/New_York)
end of month         → 2026-02-28 23:59 (America/New_York)
start of next month  → 2026-03-01 00:00 (America/New_York)
black friday 2026    → 2026-11-27 00:00 (America/New_York)

Fluent API Examples

// Starting from a fuzzy string
SmartDateTime.ParseSafe("tomorrow 9am", "Europe/London")
    .AddDays(7)
    .AddBusinessDays(5)
    .RoundToNearestQuarterHour()
    .ToTimeZone("Asia/Singapore")
    .ToFormattedString("yyyy-MM-dd HH:mm zzz");    // → "2026-02-17 17:00 +08:00"

// From existing DateTime
DateTime.Now
    .ToSmart("America/Chicago")
    .AddHoursSafe(36)
    .RoundToNearestHour()
    .IsBusinessDay();   // false if lands on weekend

Extension Methods Cheat Sheet

DateTime dt = DateTime.Now;

// Time zone helpers
dt.ToUtcSafe("Europe/Berlin")
dt.ConvertTimeZone("America/Los_Angeles", "UTC")
dt.ToSmart("Asia/Tokyo")               // → SmartDateTime wrapper

// Arithmetic with safe zone context
dt.AddDaysSafe(10,   "America/New_York")
dt.AddHoursSafe(8,   "Europe/Paris")
dt.AddMinutesSafe(45,"Asia/Dubai")

// Convenience checks
dt.IsWeekend()
dt.IsBusinessDay()
dt.IsDaylightSavingTime("America/New_York")

// Rounding
dt.RoundToNearestMinute(15)     // quarter hour
dt.RoundToNearestHour()
dt.RoundToStartOfDay()
dt.RoundToEndOfMonth()

Time Zone Behavior

• Invalid / empty zone → falls back to DateTimeZoneProviders.Tzdb["UTC"] or system default (configurable)
• All DST rules and historical changes handled automatically by NodaTime
• Parsing "now" / "today" respects the target time zone’s current offset

Contributing

Pull requests welcome! Especially interested in:

• More natural language patterns (support for other languages?)
• Additional rounding granularities
• Business-day / holiday awareness
• Better relative string localization

License

MIT License
Free for personal, educational, and commercial use.

Happy date & time coding! 🗓️