ICalDateTime

ICalDateTime :: # (opaque)

RFC 5545 section 3.3.5 extracted DATE-TIME values, profile datetime-values-v1. Accept YYYYMMDDTHHMMSS with optional Z, years 0001–9999, whole seconds. ASCII t/z are accepted and canonical output uses uppercase. Numeric offsets, fractions, lists, whitespace and content lines are malformed. Leap seconds are explicitly unsupported on this POSIX profile, never normalized to 59.

Local means the value has no Z. A surrounding property may supply TZID; this value parser does not invent, retain or validate a property parameter. Without TZID the RFC property is floating. source/local_label expose the validated fields for the shared recurrence and zone APIs with explicit context. Equality includes the UTC/local form; no cross-form total order is defined. These are timestamp labels, not second-wide calendar selections.

Parsing and formatting have constant work and bounded output. A syntactically valid truncated prefix returns Incomplete; malformed prefixes return Malformed. Source spelling and full ICS documents are outside this value profile.

import time.ICalDateTime
import time.PosixBoundary
expect {
    value = ICalDateTime.parse("19691231T235959Z")?
    ICalDateTime.utc_boundary(value) == Ok(PosixBoundary.from_microseconds(-1000000))
}

parser_for : encoding -> (state -> Try({ value : ICalDateTime, rest : state }, [InvalidICalDateTime(Error), Encoding(err), ..]))
    where [
        encoding.parse_str : encoding, state -> Try({ value : Str, rest : state }, err),
    ]

Decode one encoded string using this type's text parser. Encoding failures remain distinct from this profile's validation errors. The encoding owns framing and its work limits; parse bounds the decoded text.

encoder_for : encoding -> (ICalDateTime, state -> Try(state, err))
    where [
        encoding.encode_str : Str, state -> Try(state, err),
    ]

Encodes the canonical standard text as a string in the selected encoding; encoding failures pass through.

from_quote : Str -> Try(ICalDateTime, [BadQuotedBytes(Str)])

Typed quoted literals use the same checked profile at compile time. Runtime interpolation remains Str followed by an explicit parse call.

profile : Str

Identifier of the supported text profile described above; it does not imply support for the entire standard.

parse : Str -> Try(ICalDateTime, Error)

Parses YYYYMMDDTHHMMSS with optional Z, years 0001–9999 and whole seconds. Accepts lowercase t/z; rejects numeric offsets and fractions.

form : ICalDateTime -> Form

Returns whether the declaration carries explicit UTC Z or an unresolved local label.

source : ICalDateTime -> { date : GregorianDate, clock : ClockTime }

Returns validated Gregorian date and clock fields. Preserve form separately when choosing how to interpret them.

local_label : ICalDateTime -> LocalDateTime

A field label only; callers must preserve form when interpreting it.

utc_boundary : ICalDateTime -> Try(PosixBoundary, [NeedsContext, OutOfRange, ..])

Only explicit Z permits context-free POSIX conversion. A local value requires the caller's interpretation context, even if the fields are zero.

to_text : ICalDateTime -> Str

Canonical compact DATE-TIME value with uppercase T/Z and no fractional digits. Local values remain local.

is_eq : ICalDateTime, ICalDateTime -> Bool

Compares date, clock and UTC/local form; identical clock labels in different forms are distinct declarations.

to_hash : ICalDateTime, Hasher -> Hasher

Hashes the same declaration fields used by is_eq, so equal values are interchangeable as dictionary keys.

fact_count : ICalDateTime -> U64

Declaration facts retain local versus UTC form. A local value records its need for explicit zone context without choosing one or resolving it.

fact_at : ICalDateTime, U64 -> [End, Item(SemanticFact)]

Returns the zero-based semantic fact, or End when the index is outside fact_count. Facts describe meaning, not a serialized record.

to_inspect : ICalDateTime -> Str

A concise semantic summary for debugging. Use the standard text encoder for storage or interchange.

Form : [Local, Utc]

Utc requires a trailing Z. Local has no offset; its surrounding property determines floating versus named-zone interpretation.

Error : [Malformed, Incomplete, OutOfRange, InvalidDate, InvalidTime, UnsupportedLeapSecond]

Distinguishes incomplete/malformed syntax, invalid Gregorian fields or time, year range, and unsupported leap seconds.