Constructing a DateTime, DateOnly, or TimeOnly

Summary#

⚠ There is no DateOnly.Today (nor a TimeOnly.Now) — DateOnly/TimeOnly have no member that reads the clock. For today's date as a DateOnly, take the date part off the current instant instead: DateOnly.FromDateTime(DateTime.UtcNow) (see Current time (DateTime.UtcNow, DurableClock.Now) for DateTime.UtcNow/DurableClock.UtcNow).

When you have the components rather than a string, these build the value directly. DateTime.New(y, m, d) makes a date at midnight, and DateTime.New(y, m, d, h, mi, s) includes the time. DateOnly.New(y, m, d) makes a bare calendar date, and TimeOnly.New(h, m) / TimeOnly.New(h, m, s) makes a bare time of day. DateOnly.FromDateTime(dt) / TimeOnly.FromDateTime(dt) split a DateTime into its date or time half — the way to get "today"/"now" as a bare DateOnly/TimeOnly, since neither has its own clock read.

Signature#

DateTime.New(<int> year, <int> month, <int> day)                          -> DateTime  // 00:00:00
DateTime.New(<int> year, <int> month, <int> day, <int> hour, <int> minute, <int> second) -> DateTime
DateOnly.New(<int> year, <int> month, <int> day)                          -> DateOnly
TimeOnly.New(<int> hour, <int> minute)                                    -> TimeOnly   // seconds = 0
TimeOnly.New(<int> hour, <int> minute, <int> second)                      -> TimeOnly
DateOnly.FromDateTime(<DateTime> dt)                                      -> DateOnly   // no DateOnly.Today — this is "today"
TimeOnly.FromDateTime(<DateTime> dt)                                      -> TimeOnly   // no TimeOnly.Now — this is "now"

Description#

DateTime.New builds a DateTime from whole components. With three arguments the time is midnight; the six-argument form sets the time explicitly. The result is a UTC instant, consistent with the rest of the date surface (Current time (DateTime.UtcNow, DurableClock.Now) explains why a DateTime here is always UTC).

DateOnly.New and TimeOnly.New build the two "half" values — a date with no time, and a time with no date (TimeSpan, DateOnly, TimeOnly). TimeOnly.New defaults the seconds to 0 when you pass only hours and minutes.

Constructing vs parsing. Use New when you have the numeric components; use DateTime.Parse(s) (and DateOnly.Parse / TimeOnly.Parse) when you have a string — for example an ISO timestamp from an API. The parsing side lives with the current-time surface, Current time (DateTime.UtcNow, DurableClock.Now).

These are pure, so they run in the browser with no round trip (Reading a date — Year, Month, Day, Hour, Minute, Second, DayOfWeek, Date reads the components back off the value you build).

Examples#

DateTime MonthStart(int year, int month) {
  return DateTime.New(year, month, 1);      // day 1, midnight
}

[Test]
void Datetime_construct() {
  // three args → midnight
  var midnight = DateTime.New(2024, 3, 15);
  Assert.Equal(15, midnight.Day);
  Assert.Equal(0, midnight.Hour);
  Assert.Equal(1, MonthStart(2024, 3).Day);

  // six args → explicit time
  var full = DateTime.New(2024, 3, 15, 13, 45, 30);
  Assert.Equal(13, full.Hour);
  Assert.Equal(30, full.Second);

  // the half values
  Assert.Equal(29, DateOnly.New(2024, 2, 29).Day);    // a valid leap day
  Assert.Equal(45, TimeOnly.New(13, 45).Minute);
  Assert.Equal(0, TimeOnly.New(13, 45).Second);        // seconds default to 0
  Assert.Equal(30, TimeOnly.New(13, 45, 30).Second);

  // "today" as a bare DateOnly — there is no `DateOnly.Today`; split it off the current instant instead
  var today = DateOnly.FromDateTime(DateTime.UtcNow);
  Assert.Equal(DateTime.UtcNow.Year, today.Year);
}

See also#

• Current time (DateTime.UtcNow, DurableClock.Now) — the current instant, and DateTime.Parse for building from a string
• Reading a date — Year, Month, Day, Hour, Minute, Second, DayOfWeek, Date — reading the components back off a value
• TimeSpan, DateOnly, TimeOnly — the DateOnly and TimeOnly types