Development documentation · Some APIs may be unreleased Published release →

Guides

Dates, times and time zones

Date and TimeOfDay describe civil fields. Instant identifies a point on the timeline, Duration an elapsed amount, and Clock supplies Now. Named-zone APIs are provisional.

The development API groups these constructs in System.Time: use import System.Time.*. TimeOfDay replaces the former System.Time struct. Rebuild consumers against the matching library bundle. Formatting policies remain in System.Globalization.

Choose a specific type

Prefer Date for a calendar date, TimeOfDay for a time of day, LocalDateTime for civil fields without a zone, and Instant for a point on the timeline. Use ZonedDateTime when a value must retain its Instant, Zone, LocalDateTime and Offset. TimeOffset is a fixed whole-second displacement from UTC; TimeZone contains rules that can change that displacement over time. No OffsetDateTime type is included.

Duration value equality (development)

Duration compares its complete signed tick count through typed, interface and Object calls. Equal values have equal hashes; null and unrelated types are unequal. It can be used in supported record fields and generic pairs. Hashes are not persistent IDs. See the API reference and validated consumer.

Mapping a local time

A local clock reading can occur once, twice or not at all. TimeZone.MapLocal returns Unique, Ambiguous or Skipped through LocalTimeMapping. Applications choose how to handle overlap candidates and gaps; the library does not silently choose or shift.

func Main() {
    let Ok(zone) = TimeZone.Find("Europe/Stockholm") else {
        Panic("Unknown zone")
    }
    let Ok(date) = Date.Create(2024, 10, 27) else {
        Panic("Invalid date")
    }
    let Ok(time) = TimeOfDay.Create(2, 30, 0) else {
        Panic("Invalid time")
    }
    let local = LocalDateTime.Create(date, time)
    let Ok(mapping) = zone.MapLocal(local) else {
        Panic("Date outside zone range")
    }
    match mapping {
        Unique(let value) => Describe(value)
        Ambiguous(let earlier, let later) => {
            WriteLine("This local time occurs twice:")
            Describe(earlier)
            Describe(later)
        }
        Skipped => WriteLine("This local time does not occur")
    }
}

For Stockholm on October 27, 2024, 02:30 occurs twice: first at UTC+02:00 and then at UTC+01:00. Both values retain the same local fields and different instants. TimeZone.AtInstant converts in the other direction without ambiguity.

Complete executable example →

Arithmetic and display

TimeOfDay.Add(Duration) wraps modulo one day. LocalDateTime.Add carries into the date, returning an error outside years 1–9999. Instant.Add advances elapsed ticks and checks overflow. Adding 24 elapsed hours can produce a different local hour across DST; civil addition does not apply zone rules.

TimeOfDay.ToString uses the current culture; an explicit culture gives repeatable output. Globalization covers culture, calendar selection and Hebrew/Latin rendering. Format a zoned value's LocalDateTime through those same formatters. The DateTime union's generated ToString is diagnostic, not a serialization format.

When an API accepts either local or zoned values

DateTime is an optional nominal union: DateTime(LocalDateTime | ZonedDateTime). Use it only when the contract intentionally accepts either form; prefer the specific civil or zoned type otherwise. Existing values convert directly, and type patterns extract them without wrapper cases or a .NET-style Kind flag. An uninitialized union is inactive, rather than an implicitly local date.

func Describe(value: DateTime) {
    match value {
        LocalDateTime local => WriteLine("A civil date and time without a zone")
        ZonedDateTime zoned => Show(zoned)
    }
}

Data and limits

Named conversions bundle IANA 2025b and support UTC/local years 1900–2099. DatabaseVersion exposes the version; updating it requires rebuilding the runtime. It is a pinned snapshot, not a promise of the latest government rule changes. Find accepts case-sensitive IANA identifiers and aliases. GetSystem discovers the host's IANA name without falling back silently to UTC. macOS discovery was exercised; Windows/Linux adapters remain unverified.

Fixed TimeOffset conversions support civil years 1–9999, offsets up to ±18 hours and second-level historical offsets. Precision is 100 ns; leap seconds are unsupported. .NET DateTimeOffset instead restricts offsets to whole minutes and ±14 hours, so interop needs validation. .NET TimeZoneInfo already handles rule conversions; this API makes the zero/one/two mapping explicit, following the distinction also used by Noda Time.

Parsing covers Date, TimeOfDay and LocalDateTime numeric culture formats, Duration's invariant day/clock form, and TimeOffset's signed numeric form or Z. Instant.Parse accepts an invariant numeric timestamp with an explicit offset or Z, without consulting the host timezone. Parsers return typed Result errors and preserve 100 ns precision where relevant. ZonedDateTime.Parse takes the timestamp and an explicitly resolved zone, validating the stated offset and rejecting gaps or mismatches. Matching offsets select either DST-overlap candidate. The native runtime supports pinned-zone lookup, offset queries and database version; native MapLocal and system-zone discovery remain gaps. Inline zone identifiers, serialization, richer resolvers, custom rule providers, broader zone ranges and scheduling remain future work. Resource localization remains separate from culture.

API reference → · Detailed contracts and evidence →

Standard formatting (development)

Date, TimeOfDay, LocalDateTime and Duration implement Formattable with an explicit Culture. String.Format(culture, format, ...) forwards that culture. Default composite calls resolve one current-culture snapshot when a formattable value is encountered.

Type Formats
Duration c (also empty/t/T): invariant constant; g: compact; G: days and seven fraction digits
Date empty/G/d: current numeric convention; O/o: invariant Gregorian
TimeOfDay empty/G: culture with seven fraction digits; O/o: invariant; t: hours/minutes; T: hours/minutes/seconds
LocalDateTime empty/G: culture; O/o: invariant roundtrip; s: invariant sortable seconds

Duration g/G uses a comma for Swedish. Constant formatting supports every signed 64-bit tick count. LocalDateTime never adds a timezone or offset. These are bounded formats over the current culture/calendar policies; custom patterns, general format providers and full .NET locale patterns are not implemented. Unsupported specifiers fault. Existing numeric civil G/d conventions retain their precision and do not claim .NET's complete culture-pattern behavior.

Development Date, TimeOfDay, Instant, TimeOffset and LocalDateTime now provide matching typed/Object equality and value hashes. LocalDateTime also implements EquatableTo and ComparableTo: it compares civil date first, then every tick of the time of day, without interpreting a timezone. These contracts apply to boxed values and supported record components as well. Hashes are execution-local, not persistent identifiers. Ordinary struct default value semantics remain a separate runtime gap.

Development TimeZone values compare by their case-sensitive IANA identifier within the fixed bundled rule database; aliases stay distinct. ZonedDateTime compares the same instant in the same named zone, with matching hashes through typed, Object and equality-interface calls. Compare its Instant when zone identity should be ignored. Zone display returns the identifier; zoned display remains diagnostic type text. See the API reference and qualified cases.

Development: culture formatting foundation

Culture now exposes immutable DateTimeFormat and NumberFormat policies and OptionalCalendars. Invariant, Swedish (sv-SE), Hebrew-Israel (he-IL), UK English (en-GB) and US English (en-US) have bounded built-in profiles. UK and US dates use day/month/year and month/day/year respectively. UK time uses a 24-hour clock; US time uses a twelve-hour clock with AM/PM, including midnight and noon. The time policy exposes its separators and supported short/long patterns; duration and time fractions share the numeric decimal convention.

Both Gregorian and Hebrew calendars can be selected independently of language. Returned calendar and grouping arrays are independent snapshots. These are foundational APIs: full locale patterns, custom providers and currency formatting remain gaps. Development Int32/Int64 formatting supports D, F and N with precision 0–99 and explicit cultures, including Swedish nonbreaking-space grouping. These also work through Formattable and composite formatting. Other numeric types and custom numeric patterns remain gaps. See the API references for Culture, DateTimeFormat and NumberFormat.

Numeric formatting and parsing (development)

All numeric primitives support ToString(format, culture) and Parse(text, culture). Integers support G/D/F/N; Single and Double support G/R/F/N/E. Precision is bounded to 0–99. Floating G/R output preserves round-trip identity, including negative zero; explicit precision rounds ties to even. N groups digits using the selected culture. Unsupported/custom formats fault.

Culture parsing validates groups of three and uses the profile's decimal separator. Swedish grouping uses U+00A0. Whitespace, mixed punctuation and malformed groups return parse errors. Integer parsing accepts grouped integers but no fractions; floating parsing also accepts exponents. The original one-argument Parse overloads remain invariant for protocol data. This is a bounded API, without NumberStyles, custom providers or the full .NET globalization catalog.