Development · Native API migration preview · Coverage validation in progress Published release →

API Browser

Module

System.Time

module System.Time

Dates, clocks and time zones

Date, TimeOfDay and LocalDateTime represent calendar and local-clock values; Instant and Duration represent timeline positions and elapsed amounts. Clock and SystemClock supply time, while calendars, TimeOffset, TimeZone and ZonedDateTime support the implemented calendar and zone operations.

See dates and clocks, the DateTime union and local-time mappings. Local time can be ambiguous or skipped at a zone transition; inspect the mapping result rather than assuming there is always one instant.

Civil parsing

Date, TimeOfDay and LocalDateTime now provide Parse(value) and Parse(value, culture), returning Result<T, DateTimeParseError>. Use Culture.Invariant explicitly for portable input. The default overload follows Culture.Current, matching the existing formatting convention.

Invariant forms are yyyy-MM-dd, HH:mm:ss[.fffffff] and their combination with T. Fractions may contain one through seven digits. Swedish uses a fractional comma and a space between date and time; HebrewIsrael uses dd.MM.yyyy and a space. All use Gregorian dates. InvalidFormat and OutOfRange are recoverable cases. No whitespace trimming, timezone suffixes, extra fractional precision, general format patterns or Hebrew-calendar parsing are supported in this slice.

Duration and offset parsing

Duration.Parse(value) returns Result<Duration, DateTimeParseError> for invariant [-][d.]hh:mm:ss[.fraction], with 1–8 day digits and 1–7 fractional digits. Clock fields require two digits; hours are 0–23 and minutes/seconds 0–59. The full signed 64-bit tick range is accepted; overflow returns OutOfRange. TimeOffset.Parse(value) returns Result<TimeOffset, DateTimeParseError> for Z or ±HH:mm[:ss], using the existing inclusive ±18-hour range and whole seconds. Negative zero means zero. Both reject whitespace and incomplete/non-ASCII fields. Unsupported syntax returns InvalidFormat. General parsing patterns and inline zone identifiers remain development gaps; see the contract and offset reference.

Explicit-offset instant parsing

Instant.Parse(value) returns Result<Instant, DateTimeParseError> for yyyy-MM-ddTHH:mm:ss[.fraction] followed by Z or ±HH:mm[:ss]. It preserves 1–7 fractional digits and uses whole-second offsets within ±18 hours. Input must be complete ASCII with uppercase T/Z; omitted offsets never select the host zone. Local years are 1–9999. Offset conversion may place UTC outside those civil bounds, within Instant's wider signed tick domain. The source offset is not retained. Unsupported syntax returns InvalidFormat; invalid fields/ranges return OutOfRange. Instant.Parse reference.

Zoned parsing with an explicit zone

ZonedDateTime.Parse(value, zone) returns Result<ZonedDateTime, DateTimeParseError>. The input uses Instant.Parse's explicit-offset grammar; resolve a named zone with TimeZone.Find and supply it separately. The stated offset must match its rule at the parsed instant. OffsetMismatch rejects skipped local times and incorrect offsets; matching offsets select either overlap candidate. UTC and local years must be 1900–2099. No inline zone identifier or host-zone inference is performed. ZonedDateTime.Parse reference.

Types

17 items
Calendar Immutable calendar selection. Values retain Date's absolute day identity.
Clock An injectable source of the current instant.
Date A Gregorian calendar date from year 1 through 9999, without a time or time zone.
DateTime A civil value without a zone, or a resolved value retaining named zone rules.
DateTimeParseError A failure to parse a supported numeric date/time, duration or offset representation.
Duration A signed elapsed duration represented by 100-nanosecond ticks.
Instant An instant represented by signed 100-nanosecond ticks since the Unix epoch.
InvalidDateError An error indicating invalid Gregorian date components or an unsupported day number.
InvalidTimeError An error indicating time components or ticks outside a single day.
LocalDateTime A date and time expressed in the host local time zone, without retaining a zone identifier.
LocalTimeMapping A civil time can identify zero, one or two instants in a named zone.
SystemClock Reads the current instant from the host wall clock.
TimeOfDay A time of day with 100-nanosecond precision, without a date or time zone.
TimeOffset A fixed UTC displacement in whole seconds, independent of zone rules.
TimeZone Named IANA rules, separate from culture, calendar and the system clock.
TimeZoneError Lookup/discovery and bounded timezone conversion failures.
ZonedDateTime An immutable resolved instant and its projection under a named zone's rules.