DateTime Module

Date and time operations with UTC timezone support.

The DateTime module provides functions for creating, parsing, formatting, and manipulating date and time values. All operations use UTC timezone. DateTimes are opaque native objects backed by the chrono crate.

Common patterns

import DateTime

-- Get current time
DateTime.now () |> DateTime.format |> IO.println
-- "2024-02-20T14:30:45Z"

-- Parse and manipulate
"2024-01-15T10:00:00Z"
    |> DateTime.parse
    |> Maybe.map (DateTime.addDays 7)
    |> Maybe.map (DateTime.addHours 2)
    |> Maybe.map DateTime.format
-- Just "2024-01-22T12:00:00Z"

-- Create from components
DateTime.fromDate 2024 6 15
    |> Maybe.map DateTime.format
-- Just "2024-06-15T00:00:00Z"

-- Custom formatting
DateTime.now ()
    |> DateTime.formatCustom "%Y-%m-%d %H:%M"
-- "2024-02-20 14:30"

-- Calendar operations
DateTime.now ()
    |> DateTime.startOfMonth
    |> DateTime.addMonths 1
    |> DateTime.format
-- "2024-03-01T00:00:00Z"

-- Time differences
let dt1 = DateTime.fromDate 2024 1 1
let dt2 = DateTime.fromDate 2024 12 31
DateTime.diffDays dt1 dt2  -- 365

Return types

Functions that can fail return Maybe DateTime:

parse : String -> Maybe DateTime
fromParts : Int -> Int -> Int -> Int -> Int -> Int -> Maybe DateTime
fromDate : Int -> Int -> Int -> Maybe DateTime

Security

Variable	Effect
`KEEL_DATETIME_DISABLED=1`	Disable all DateTime operations

Functions

Creation

`DateTime.now`

() -> DateTime

Get the current UTC time.

Example:

import DateTime

DateTime.now ()

Try it

Notes: Takes Unit argument to trigger execution.

See also: DateTime.fromTimestamp, DateTime.format

`DateTime.fromParts`

Int -> Int -> Int -> Int -> Int -> Int -> Maybe DateTime

Create a DateTime from year, month, day, hour, minute, second (returns Maybe DateTime).

Example:

import DateTime

DateTime.fromParts 2024 1 15 10 30 0

Try it

Notes: Returns Nothing for invalid dates (e.g., month 13, day 32).

`DateTime.fromDate`

Int -> Int -> Int -> Maybe DateTime

Create a DateTime from year, month, day at 00:00:00 (returns Maybe DateTime).

Example:

import DateTime

DateTime.fromDate 2024 1 15

Try it

Notes: Returns Nothing for invalid dates.

`DateTime.fromTimestamp`

Int -> DateTime

Create a DateTime from a Unix timestamp in seconds.

Example:

import DateTime

DateTime.fromTimestamp 1700000000

Try it

`DateTime.fromTimestampMillis`

Int -> DateTime

Create a DateTime from a Unix timestamp in milliseconds.

Example:

import DateTime

DateTime.fromTimestampMillis 1700000000000

Try it

`DateTime.toTimestamp`

DateTime -> Int

Convert a DateTime to a Unix timestamp in seconds.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.toTimestamp

Try it

`DateTime.toTimestampMillis`

DateTime -> Int

Convert a DateTime to a Unix timestamp in milliseconds.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.toTimestampMillis

Try it

Parsing

`DateTime.parse`

String -> Maybe DateTime

Parse an ISO8601 or RFC3339 datetime string (returns Maybe DateTime).

Example:

import DateTime

DateTime.parse "2024-01-15T10:30:00Z"

Try it

Notes: Accepts both ISO8601 and RFC3339 formats.

`DateTime.parseIso8601`

String -> Maybe DateTime

Parse a strict ISO8601 datetime string (returns Maybe DateTime).

Example:

import DateTime

DateTime.parseIso8601 "2024-01-15T10:30:00Z"

Try it

See also: DateTime.parse, DateTime.parseRfc3339

`DateTime.parseRfc3339`

String -> Maybe DateTime

Parse a strict RFC3339 datetime string (returns Maybe DateTime).

Example:

import DateTime

DateTime.parseRfc3339 "2024-01-15T10:30:00+00:00"

Try it

See also: DateTime.parse, DateTime.parseIso8601

`DateTime.parseFormat`

String -> String -> Maybe DateTime

Parse a datetime string using a custom strftime format (returns Maybe DateTime).

Example:

import DateTime

DateTime.parseFormat "%Y-%m-%d" "2024-01-15"

Try it

Notes: First argument is the format string, second is the datetime string.

See also: DateTime.parse, DateTime.formatCustom

Formatting

`DateTime.format`

DateTime -> String

Format a DateTime as an ISO8601 string.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.format

Try it

`DateTime.formatRfc3339`

DateTime -> String

Format a DateTime as an RFC3339 string.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.formatRfc3339

Try it

See also: DateTime.format, DateTime.formatCustom

`DateTime.formatCustom`

String -> DateTime -> String

Format a DateTime using a custom strftime format.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.formatCustom "%Y-%m-%d"

Try it

Notes: Uses strftime format specifiers (e.g., %Y for year, %m for month, %d for day).

See also: DateTime.format, DateTime.parseFormat

Components

`DateTime.year`

DateTime -> Int

Get the year component (e.g., 2024).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.year

Try it

See also: DateTime.month, DateTime.day

`DateTime.month`

DateTime -> Int

Get the month component (1-12).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.month

Try it

See also: DateTime.year, DateTime.day

`DateTime.day`

DateTime -> Int

Get the day component (1-31).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.day

Try it

See also: DateTime.year, DateTime.month

`DateTime.hour`

DateTime -> Int

Get the hour component (0-23).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.hour

Try it

See also: DateTime.minute, DateTime.second

`DateTime.minute`

DateTime -> Int

Get the minute component (0-59).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.minute

Try it

See also: DateTime.hour, DateTime.second

`DateTime.second`

DateTime -> Int

Get the second component (0-59).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.second

Try it

See also: DateTime.hour, DateTime.minute

`DateTime.weekday`

DateTime -> Int

Get the weekday (1=Monday, 7=Sunday).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.weekday

Try it

Notes: Uses ISO weekday numbering: 1=Monday through 7=Sunday.

See also: DateTime.dayOfYear, DateTime.weekNumber

`DateTime.dayOfYear`

DateTime -> Int

Get the day of year (1-366).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.dayOfYear

Try it

See also: DateTime.weekday, DateTime.weekNumber

`DateTime.weekNumber`

DateTime -> Int

Get the ISO week number (1-53).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.weekNumber

Try it

See also: DateTime.weekday, DateTime.dayOfYear

Manipulation

`DateTime.addMillis`

Int -> DateTime -> DateTime

Add milliseconds to a DateTime.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.addMillis 5000

Try it

`DateTime.addSeconds`

Int -> DateTime -> DateTime

Add seconds to a DateTime.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.addSeconds 60

Try it

`DateTime.addMinutes`

Int -> DateTime -> DateTime

Add minutes to a DateTime.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.addMinutes 30

Try it

See also: DateTime.addHours, DateTime.diffMinutes

`DateTime.addHours`

Int -> DateTime -> DateTime

Add hours to a DateTime.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.addHours 2

Try it

See also: DateTime.addDays, DateTime.diffHours

`DateTime.addDays`

Int -> DateTime -> DateTime

Add days to a DateTime.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.addDays 7

Try it

See also: DateTime.addWeeks, DateTime.diffDays

`DateTime.addWeeks`

Int -> DateTime -> DateTime

Add weeks to a DateTime.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.addWeeks 2

Try it

See also: DateTime.addDays, DateTime.addMonths

`DateTime.addMonths`

Int -> DateTime -> DateTime

Add months to a DateTime (handles month-end overflow).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.addMonths 3

Try it

Notes: If the result day exceeds the target month's length, it clamps to the last day.

See also: DateTime.addYears, DateTime.addWeeks

`DateTime.addYears`

Int -> DateTime -> DateTime

Add years to a DateTime (handles leap year Feb 29).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.addYears 1

Try it

Notes: If the source date is Feb 29, adding a non-leap year clamps to Feb 28.

See also: DateTime.addMonths

Comparison

`DateTime.isBefore`

DateTime -> DateTime -> Bool

Check if the first DateTime is before the second.

Example:

import DateTime

DateTime.isBefore (DateTime.fromTimestamp 1000) (DateTime.fromTimestamp 2000)

Try it

`DateTime.isAfter`

DateTime -> DateTime -> Bool

Check if the first DateTime is after the second.

Example:

import DateTime

DateTime.isAfter (DateTime.fromTimestamp 2000) (DateTime.fromTimestamp 1000)

Try it

`DateTime.isEqual`

DateTime -> DateTime -> Bool

Check if two DateTimes are equal.

Example:

import DateTime

DateTime.isEqual (DateTime.fromTimestamp 1000) (DateTime.fromTimestamp 1000)

Try it

`DateTime.compare`

DateTime -> DateTime -> Int

Compare two DateTimes (-1 if before, 0 if equal, 1 if after).

Example:

import DateTime

DateTime.compare (DateTime.fromTimestamp 1000) (DateTime.fromTimestamp 2000)

Try it

Duration

`DateTime.diffMillis`

DateTime -> DateTime -> Int

Calculate the difference in milliseconds between two DateTimes.

Example:

import DateTime

let dt1 = DateTime.fromTimestamp 1700000000

let dt2 = DateTime.fromTimestamp 1700000060

DateTime.diffMillis dt1 dt2

Try it

`DateTime.diffSeconds`

DateTime -> DateTime -> Int

Calculate the difference in seconds between two DateTimes.

Example:

import DateTime

let dt1 = DateTime.fromTimestamp 1700000000

let dt2 = DateTime.fromTimestamp 1700000060

DateTime.diffSeconds dt1 dt2

Try it

`DateTime.diffMinutes`

DateTime -> DateTime -> Int

Calculate the difference in minutes between two DateTimes.

Example:

import DateTime

let dt1 = DateTime.fromTimestamp 1700000000

let dt2 = DateTime.fromTimestamp 1700003600

DateTime.diffMinutes dt1 dt2

Try it

See also: DateTime.diffHours, DateTime.addMinutes

`DateTime.diffHours`

DateTime -> DateTime -> Int

Calculate the difference in hours between two DateTimes.

Example:

import DateTime

let dt1 = DateTime.fromTimestamp 1700000000

let dt2 = DateTime.fromTimestamp 1700086400

DateTime.diffHours dt1 dt2

Try it

See also: DateTime.diffDays, DateTime.addHours

`DateTime.diffDays`

DateTime -> DateTime -> Int

Calculate the difference in days between two DateTimes.

Example:

import DateTime

let dt1 = DateTime.fromTimestamp 1700000000

let dt2 = DateTime.fromTimestamp 1700086400

DateTime.diffDays dt1 dt2

Try it

See also: DateTime.diffHours, DateTime.addDays

Calendar

`DateTime.startOfDay`

DateTime -> DateTime

Get the start of the day (00:00:00).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.startOfDay

Try it

See also: DateTime.endOfDay

`DateTime.endOfDay`

DateTime -> DateTime

Get the end of the day (23:59:59).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.endOfDay

Try it

See also: DateTime.startOfDay

`DateTime.startOfWeek`

DateTime -> DateTime

Get the start of the week (Monday 00:00:00).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.startOfWeek

Try it

Notes: Week starts on Monday (ISO 8601).

See also: DateTime.endOfWeek

`DateTime.endOfWeek`

DateTime -> DateTime

Get the end of the week (Sunday 23:59:59).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.endOfWeek

Try it

Notes: Week ends on Sunday (ISO 8601).

See also: DateTime.startOfWeek

`DateTime.startOfMonth`

DateTime -> DateTime

Get the start of the month (1st day 00:00:00).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.startOfMonth

Try it

See also: DateTime.endOfMonth

`DateTime.endOfMonth`

DateTime -> DateTime

Get the end of the month (last day 23:59:59).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.endOfMonth

Try it

See also: DateTime.startOfMonth

`DateTime.startOfYear`

DateTime -> DateTime

Get the start of the year (Jan 1 00:00:00).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.startOfYear

Try it

See also: DateTime.endOfYear

`DateTime.endOfYear`

DateTime -> DateTime

Get the end of the year (Dec 31 23:59:59).

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.endOfYear

Try it

See also: DateTime.startOfYear

Other

`DateTime.combine`

Date -> Time -> DateTime

Combine a Date and Time into a DateTime (UTC).

Example:

import Date
import Time
import DateTime

case Date.fromYmd 2024 6 15 of
    Ok date -> case Time.fromHms 14 30 0 of
        Ok time -> DateTime.combine date time
        Err _ -> DateTime.fromTimestamp 0
    Err _ -> DateTime.fromTimestamp 0

Try it

Notes: Creates a UTC DateTime from the given Date and Time.

`DateTime.fromDateType`

Date -> DateTime

Convert a Date to a DateTime at midnight UTC.

Example:

import Date
import DateTime

case Date.fromYmd 2024 6 15 of
    Ok date -> DateTime.fromDateType date
    Err _ -> DateTime.fromTimestamp 0

Try it

Notes: Sets time to 00:00:00 UTC.

See also: DateTime.combine, DateTime.getDate

`DateTime.getDate`

DateTime -> Date

Extract the Date component from a DateTime.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.getDate

Try it

`DateTime.getTime`

DateTime -> Time

Extract the Time component from a DateTime.

Example:

import DateTime

DateTime.fromTimestamp 1700000000
    |> DateTime.getTime

Try it