OffsetTimestamp

OffsetTimestamp :: # (opaque)

Complete offset-bearing timestamps, rfc3339-microseconds-rfc9557-base-v1. RFC 3339 sections 5.6–5.8 with RFC 9557 section 2 offset semantics. Four-digit astronomical Gregorian years 0000–9999, required seconds and zero through six supplied fractional digits. This is an instant declaration, not a calendar selection of the supplied precision's width.

Z and -00:00 both mean UTC is known without asserting a local offset; canonical output uses Z. Numeric +00:00 retains its assertion. Lowercase t/z are accepted and emitted uppercase. Fractional width is preserved: .12 and .120 denote the same position but are distinct declarations.

Incomplete prefixes have valid completed fields; unfinished digit fields are checked syntactically. A trailing [ after a complete base timestamp recognizes excluded annotations without validating their grammar. Leap seconds, fractions beyond six digits and IXDTF annotations are explicitly unsupported. No rounding, zone lookup, implicit clock or full ISO claim. Parsing checks a 256-byte limit before streaming into scalar fields, without materializing a byte list. Construction, conversion and formatting have constant bounded work. Canonical standard text can be stored directly.

parser_for : encoding -> (state -> Try({ value : OffsetTimestamp, rest : state }, [InvalidOffsetTimestamp(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 -> (OffsetTimestamp, 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(OffsetTimestamp, [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.

new : Parts -> Try(OffsetTimestamp, Error)

Checks a four-digit Gregorian timestamp declaration, exact fractional width 0–6, and whole-minute numeric offset within +/-23:59. Precision loss is rejected.

parts : OffsetTimestamp -> Parts

Returns the retained date, clock, fractional width and offset assertion for inspection or checked editing through new.

local_label : OffsetTimestamp -> LocalDateTime

Returns the supplied Gregorian clock label without applying its offset. Use boundary for a resolved POSIX coordinate.

boundary : OffsetTimestamp -> Try(PosixBoundary, [OutOfRange, ..])

This source label is UTC for UnassertedUtc and offset-local otherwise.

from_boundary : PosixBoundary, Offset, U8 -> Try(OffsetTimestamp, Error)

Explicit projection for canonical timestamp output. The requested width must represent the position exactly; this operation never rounds.

parse : Str -> Try(OffsetTimestamp, Error)

Parses the supported RFC timestamp profile, retaining fractional width and offset assertion. Valid incomplete prefixes remain errors; unsupported precision is never rounded.

to_text : OffsetTimestamp -> Str

Validated fields need at most 32 ASCII bytes: 19 fixed, 7 fractional, and 6 for an asserted offset. Build one owned buffer rather than padded temporary strings. Formatting preserves supplied width and offset intent.

is_eq : OffsetTimestamp, OffsetTimestamp -> Bool

Compares the retained declaration, including fractional width and offset assertion. Use boundary when comparing resolved positions.

to_hash : OffsetTimestamp, Hasher -> Hasher

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

fact_count : OffsetTimestamp -> U64

One bounded semantic fact, retaining supplied decimal width and offset assertion. Reading facts never resolves a zone or materializes coverage.

fact_at : OffsetTimestamp, 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 : OffsetTimestamp -> Str

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

Offset : [UnassertedUtc, Asserted(FixedOffset)]

UnassertedUtc represents Z or -00:00 without an asserted local offset. Asserted retains a numeric offset, including explicit +00:00.

Parts : { date : GregorianDate, clock : ClockTime, fraction_digits : U8, offset : Offset }

Validated Gregorian date and clock, supplied fractional width, and offset assertion. Use new to validate an edited record.

Error : [Malformed, Incomplete, InvalidDate, InvalidTime, InvalidOffset, OutOfRange, TooLarge, UnsupportedPrecision, UnsupportedLeapSecond, UnsupportedAnnotations]

Separates malformed/incomplete input, invalid date/time/offset, size/range limits, and unsupported precision, leap seconds or annotations.