# DateTime

> A date and time. It is a wall-clock value, not an instant on a timeline, so it is never shifted by anybody's timezone. Reading its parts and doing calendar arithmetic on it work identically in the browser and on the server; reading the current time is a server operation.

<!-- id: types-datetime · area: types · stability: stable · html: https://osysharp.com/reference/types/datetime/ -->

## Summary        {#summary}
`DateTime` is a date and a time of day — `2024-03-15T13:45:30` — held exactly, to 100 nanoseconds. You read its parts
(`d.Year`, `d.DayOfWeek`), do calendar arithmetic on it (`d.AddMonths(1)`), and construct or parse one
(`new DateTime(2024, 3, 15)`, `DateTime.Parse(s)`).

## Signature      {#signature}
```osy syntax
new DateTime(<int> year, <int> month, <int> day)
new DateTime(<int> year, <int> month, <int> day, <int> hour, <int> minute, <int> second)
DateTime.Parse(<string> s) -> DateTime

DateTime.MinValue -> DateTime         // the earliest representable value
DateTime.MaxValue -> DateTime         // the latest representable value

d.Year · d.Month · d.Day · d.Hour · d.Minute · d.Second · d.DayOfWeek · d.Date
d.AddDays(n) · d.AddMonths(n) · d.AddYears(n) · d.AddHours(n) · d.AddMinutes(n)
```

## Description    {#description}

### What are `DateTime.MinValue` and `MaxValue`? {#range-endpoints}
`DateTime.MinValue` and `DateTime.MaxValue` are the earliest and latest values a `DateTime` can hold. They are
ordinary values, so they compare and sort like any other date — which is what makes them useful as a starting point
for a running comparison (`var earliest = DateTime.MaxValue;` then keep the smaller of each candidate).

⚠ **They are not a "no date" marker.** A `DateTime?` says "no date" precisely and reads as `null`; a sentinel says
it by convention and every reader has to know the convention. Prefer the nullable type — a `MinValue` that leaks
into a UI renders as a real date in the year 1, and a `MinValue` that reaches a comparison silently sorts first.

### It is a wall-clock value, not an instant   {#wall-clock}

`2024-03-15T13:45:30` means *that reading on a clock face*. It is not "a moment in time as seen from a timezone", and
nothing in the platform will shift it by one. A date you store is the date you get back — the same one, in the same
digits, whether it is read on a server in Frankfurt or in a browser in São Paulo.

That is worth stating plainly because most date libraries do the opposite, and quietly.

### Calendar arithmetic clamps the day   {#clamping}

`AddMonths` and `AddYears` move along the **calendar**, and clamp the day to the target month rather than overflowing
it:

```osy syntax
new DateTime(2024, 1, 31).AddMonths(1)     // 2024-02-29  — a leap year
new DateTime(2025, 1, 31).AddMonths(1)     // 2025-02-28
new DateTime(2024, 2, 29).AddYears(1)      // 2025-02-28
```

None of those becomes March 2nd. If you want exactly thirty days later, say `AddDays(30)`.

`AddDays`, `AddHours` and `AddMinutes` take a fractional amount and round it to the nearest millisecond, so
`AddDays(0.5)` is exactly twelve hours.

### DayOfWeek counts from Sunday   {#day-of-week}

`d.DayOfWeek` is `0` for Sunday through `6` for Saturday.

### Reading the current time   {#now}

`DurableClock.Now`, `DurableClock.UtcNow` and `DurableClock.Today` give the current instant, and they run **on the client** — reading
"now" costs no round trip. That is safe here for a reason worth knowing: a `DateTime` is a UTC *instant*, not a
wall-clock reading, so the browser and the server name the same value (9am in Frankfurt *is* 5pm in Tokyo). Test
pinning still applies, and a durable flow that pauses and resumes still sees the instant it saw before, because the
engine resumes from a saved point rather than re-running the body from the top.

⚠ **`DateTime.Now` and `DateTime.UtcNow` are the same instant**, because there is no local-time `DateTime` here for
them to differ by. Local is a question about a person, not a property of the platform — so when you want a wall
clock, name the zone: `DateTime.UtcNow.InZone(Zone.Of("Europe/Stockholm"))`.

Everything else about a date — its parts, its arithmetic, parsing and formatting it — runs wherever you are, with no
round trip.

## Examples       {#examples}
```osy title="a due date, and whether it has passed" test app=text-search
bool IsOverdue(DateTime due) {
  return due < DurableClock.UtcNow;
}

DateTime NextBillingDate(DateTime start) {
  return start.AddMonths(1);
}
// NextBillingDate(new DateTime(2024, 1, 31))  ->  2024-02-29
```

## See also       {#see-also}
- [decimal](https://osysharp.com/reference/types/decimal/) — the other exact value type, and the same reasoning behind it
- [format specifiers](https://osysharp.com/reference/function/format-specifiers/) — rendering a date or a number to a string
- [execution side](https://osysharp.com/reference/function/execution-side/) — why the clock is a server operation and the arithmetic is not