Reading a date — Year, Month, Day, Hour, Minute, Second, DayOfWeek, Date

Summary#

Given a DateTime, these read one component out of it: Year, Month, Day, Hour, Minute, Second (each an int), DayOfWeek (an int, with Sunday = 0), and Date (the same instant truncated to midnight). The same readers also work on a TimeSpan, DateOnly, TimeOnly DateOnly or TimeOnly.

Signature#

d.Year / d.Month / d.Day        -> int
d.Hour / d.Minute / d.Second    -> int
d.DayOfWeek                     -> int      // Sunday = 0, Monday = 1, … Saturday = 6
d.Date                          -> DateTime // same date, time set to 00:00:00

Description#

Each reader pulls a single field out of the value. Month is 1-based (January is 1, not 0 — unlike a JavaScript Date), and Day is the day of the month.

DayOfWeek counts from Sunday. Sunday is 0, Monday is 1, up to Saturday at 6 — so 2024-03-15, a Friday, gives 5.

Date truncates to midnight. It returns a DateTime on the same calendar day with the time cleared to 00:00:00, which is how you compare two timestamps "on the same day" or bucket by day.

The same readers work on a DateOnly and a TimeOnly. someDate.Month reads the month off a DateOnly; someTime.Hour reads the hour off a TimeOnly — the part-reader widens to whichever value you give it.

The member syntax d.Month is the everyday spelling; the compiler knows these readers as Date.Year, Date.Month, Date.Day, Date.Hour, Date.Minute, Date.Second, Date.DayOfWeek and Date.Date, and they can also be written in that call form (Date.Month(d)).

All of these are pure functions of the value, so they run in the browser with no round trip (execution side). For the current instant to read them off, see Current time (DateTime.UtcNow, DurableClock.Now).

The whole instant as one number — Date.Ticks#

When you want an instant as a single comparable/​storable number rather than as parts, Date.Ticks(d) answers it — one number that orders the same way the instants do. Use it for an ordering key or a compact stamp, not for arithmetic you could write with the date operators themselves:

```osy title="an instant as one orderable number — and it is a long" syntax long stamp = Date.Ticks(DateTime.UtcNow);

⚠ **It is a `long`, not an `int`** — the tick count passed `int`'s range in 1970, so a variable or a field holding
one must say `long`.

## Examples       {#examples}
```osy title="is a timestamp on a weekend?" test app=date-parts
bool IsWeekend(DateTime d) {
  return d.DayOfWeek == 0 || d.DayOfWeek == 6;   // Sunday is 0, Saturday is 6
}

[Test]
void Date_parts() {
  var d = DateTime.New(2024, 3, 15, 13, 45, 30);
  Assert.Equal(2024, d.Year);
  Assert.Equal(3, d.Month);             // 1-based
  Assert.Equal(15, d.Day);
  Assert.Equal(13, d.Hour);
  Assert.Equal(45, d.Minute);
  Assert.Equal(30, d.Second);
  Assert.Equal(5, d.DayOfWeek);         // Friday — Sunday is 0
  Assert.False(IsWeekend(d));           // Friday is not a weekend…
  Assert.True(IsWeekend(d.AddDays(2))); // …but the Sunday two days later is

  // .Date truncates the time to midnight, same calendar day
  Assert.Equal(0, d.Date.Hour);
  Assert.Equal(15, d.Date.Day);

  // the same readers widen to a DateOnly and a TimeOnly
  Assert.Equal(3, DateOnly.New(2024, 3, 15).Month);
  Assert.Equal(13, TimeOnly.New(13, 45, 30).Hour);
}

See also#

• Date arithmetic — AddDays, AddMonths, AddYears, AddHours, AddMinutes — adding days/months/years, and its calendar clamping
• Current time (DateTime.UtcNow, DurableClock.Now) — reading the current instant to pull parts from
• DateTime — the DateTime type and how it is stored