LocalDateTime

LocalDateTime :: # (opaque)

A dated local label. A zone occurrence has not been selected or resolved.

Example

Combine a calendar date with a wall-clock label before choosing a timezone. Construction alone does not resolve daylight-saving gaps or folds.

import time.GregorianDate
import time.Calendar.Date
import time.ClockTime
import time.LocalDateTime

expect {
    date = GregorianDate.from_fields({ year: 2025, month: 6, day: 12 })?
    clock = ClockTime.from_fields({
        hour: 9,
        minute: 30,
        second: 0,
        microsecond: 0,
    })?
    local = LocalDateTime.new(Calendar.Date.from_gregorian(date), clock)
    ClockTime.to_fields(LocalDateTime.clock(local)).hour == 9
}

An explicitly Gregorian form field can also be read directly. A local label still needs separately supplied rules and an occurrence policy to resolve it. This text profile rejects offsets and preserves microseconds, but does not retain supplied-field resolution or serialize non-Gregorian calendars.

import time.LocalDateTime

expect {
    appointment = LocalDateTime.parse_gregorian("2026-09-07T09:30")?
    LocalDateTime.to_gregorian_text(appointment) == Ok("2026-09-07T09:30:00")
}

Examples assume a package dependency named time.

from_calendar_value : Value -> LocalDateTime

Canonical start of a civil selection, without changing its supplied precision. This label alone does not describe the selection's extent or choose a zone.

calendar_value_bounds : Value -> Try({ start : LocalDateTime, end : LocalDateTime }, [OutOfRange, ..])

Compose checked half-open civil bounds from selection components in O(1). An exclusive upper bound beyond the provider range returns OutOfRange.

parse_gregorian : Str -> Try(LocalDateTime, TextError)

Parse an explicitly Gregorian local label: date, uppercase T, then clock. The date and clock use GregorianDate.parse and ClockTime.parse profiles. At most 64 UTF-8 bytes; omitted clock seconds become zero. No offset, zone, occurrence or supplied-field resolution is inferred. This native profile does not claim all ISO 8601 forms. Julian values require explicit construction; their fields are never silently treated as Gregorian.

to_gregorian_text : LocalDateTime -> Try(Str, [UnsupportedCalendar(Calendar), ..])

Canonical Gregorian date/clock text preserves the local position. It is neither a resolved timestamp nor a persistence format for every calendar. Reject other calendars; callers can explicitly convert with in_calendar.

new : Date, ClockTime -> LocalDateTime

Combine a validated calendar date and clock label without choosing an offset or timezone. Resolve the result explicitly before timeline computation.

date : LocalDateTime -> Date

Read the calendar date as described, retaining its calendar identity.

clock : LocalDateTime -> ClockTime

Read the local clock label without resolving it to a timeline.

in_calendar : LocalDateTime, Calendar -> Try(LocalDateTime, [OutOfRange, ..])

Describe the same civil-day and clock position in another supported calendar. The clock is unchanged; an unsupported destination date returns OutOfRange.

compare_position : LocalDateTime, LocalDateTime -> [LT, EQ, GT]

Compare local positions, not timeline occurrences or descriptions.

same_position : LocalDateTime, LocalDateTime -> Bool

Whether both labels have the same civil-day coordinate and clock position. Different calendar descriptions can match; no timezone is involved.

is_eq : LocalDateTime, LocalDateTime -> Bool

Description equality preserves the calendar as well as the clock label.

to_hash : LocalDateTime, Hasher -> Hasher

Hash description identity, including the calendar and clock, consistently with is_eq. Use explicit conversion when keys should ignore calendar identity.

to_inspect : LocalDateTime -> Str

Describe the calendar date and local clock for diagnostics, without choosing a zone or resolving an occurrence.

TextError : [TooLarge, Incomplete, Malformed, InvalidDate(Error), InvalidTime(Error)]

Errors from the native Gregorian local-label parser, including invalid date or clock fields, incomplete/malformed input and unsupported precision.