---
title: Std.DateTime
---

Date, time, and datetime types with formatting, parsing, and arithmetic.

## Types

### ParseError

```saga
type ParseError =
  | UnexpectedEnd
  | InvalidDigits String
  | UnexpectedChar (String, String)
  | UnknownSpecifier String
  | MissingField String
  deriving (Show, Debug, Eq)
```

Errors that can occur when parsing a datetime string.

### Date

```saga
record Date {
  year: Int,
  month: Int,
  day: Int
}
  deriving (Show, Debug, Eq)
```

A calendar date (year, month, day).

### Time

```saga
record Time {
  hour: Int,
  minute: Int,
  second: Int,
  microsecond: Int
}
  deriving (Show, Debug, Eq)
```

A time of day with microsecond precision.

### NaiveDateTime

```saga
record NaiveDateTime {
  year: Int,
  month: Int,
  day: Int,
  hour: Int,
  minute: Int,
  second: Int,
  microsecond: Int
}
  deriving (Show, Debug, Eq)
```

A date and time without timezone information.

## Effects

### Clock

```saga
effect Clock {
  fun now : Unit -> NaiveDateTime
  fun today : Unit -> Date
  fun time_of_day : Unit -> Time
}
```

Effect for accessing the current wall-clock time.

## Handlers

### system_clock

```saga
handler system_clock for Clock
```

Handler that reads the system clock in UTC.

## Functions

### from_date_time

```saga
fun from_date_time : Date -> Time -> NaiveDateTime
```

Combines a Date and Time into a NaiveDateTime.

### new

```saga
fun new : (year: Int) -> (month: Int) -> (day: Int) -> (hour: Int) -> (minute: Int) -> (second: Int) -> NaiveDateTime
```

Constructs a NaiveDateTime from individual components. Microsecond is set to 0.

### to_date

```saga
fun to_date : NaiveDateTime -> Date
```

Extracts the date portion of a NaiveDateTime.

### to_time

```saga
fun to_time : NaiveDateTime -> Time
```

Extracts the time portion of a NaiveDateTime.

### format

```saga
fun format : String -> NaiveDateTime -> String
```

Format a NaiveDateTime using strftime-style specifiers.
Supported: %Y (year), %m (month), %d (day), %H (hour), %M (minute),
%S (second), %f (microsecond, 6 digits), %T (%H:%M:%S),
%F (%Y-%m-%d), %b/%B (month name), %a/%A (weekday name), %% (literal %)

### to_iso8601

```saga
fun to_iso8601 : NaiveDateTime -> String
```

Formats a NaiveDateTime as an ISO 8601 string ("YYYY-MM-DDTHH:MM:SS").

### day_of_week

```saga
fun day_of_week : Date -> Int
```

Returns the day of the week (1 = Monday, 7 = Sunday).

### is_leap_year

```saga
fun is_leap_year : Int -> Bool
```

Returns True if the given year is a leap year.

### days_in_month

```saga
fun days_in_month : (year: Int) -> (month: Int) -> Int
```

Returns the number of days in the given month for the given year.

### valid_date

```saga
fun valid_date : Date -> Bool
```

Returns True if the date is a valid calendar date.

### add_seconds

```saga
fun add_seconds : Int -> NaiveDateTime -> NaiveDateTime
```

Adds the given number of seconds to a datetime.

### add_days

```saga
fun add_days : Int -> NaiveDateTime -> NaiveDateTime
```

Adds the given number of days to a datetime.

### add_hours

```saga
fun add_hours : Int -> NaiveDateTime -> NaiveDateTime
```

Adds the given number of hours to a datetime.

### add_minutes

```saga
fun add_minutes : Int -> NaiveDateTime -> NaiveDateTime
```

Adds the given number of minutes to a datetime.

### add_months

```saga
fun add_months : Int -> NaiveDateTime -> NaiveDateTime
```

Adds the given number of months to a datetime, clamping the day if needed.

### add_years

```saga
fun add_years : Int -> NaiveDateTime -> NaiveDateTime
```

Adds the given number of years to a datetime.

### diff_seconds

```saga
fun diff_seconds : NaiveDateTime -> NaiveDateTime -> Int
```

Returns the difference in seconds between two datetimes (a - b).

### parse

```saga
fun parse : String -> String -> Result NaiveDateTime ParseError
```

Parse a datetime string using a strftime-style format.
Supported: %Y, %m, %d, %H, %I, %p, %M, %S, %f (microseconds, 1-6 digits, right-padded),
%b, %B, %F (%Y-%m-%d), %T (%H:%M:%S), %% (literal %).
Numeric fields accept variable-width input (e.g. "%m" parses both "4" and "04").

### from_iso8601

```saga
fun from_iso8601 : String -> Result NaiveDateTime ParseError
```

Parse an ISO 8601 datetime string ("YYYY-MM-DDTHH:MM:SS").