ICalDuration

ICalDuration :: # (opaque)

Positive RFC 5545 duration values for events and PERIOD starts. Profile rfc5545-positive-duration-v1 implements section 3.3.6's week, day and hour/minute/second grammar, including optional plus and ASCII case. Calendar days remain distinct from coordinate seconds; leap seconds are not counted. Years, months, fractions, lists and content lines are malformed. Negative and zero durations return NonPositive; alarm durations are outside this positive profile. Source spelling is not retained.

Parsing visits at most 256 bytes. Days and the coordinate microsecond tail must each fit nonnegative I64. Interpretation may still exceed calendar, boundary or provider ranges. No rules are consulted during parsing.

import time.ICalDuration
expect {
    value = ICalDuration.parse("P15DT5H0M20S")?
    ICalDuration.components(value) == { days: 15.I64, seconds: 18020.I64 }
}

parser_for : encoding -> (state -> Try({ value : ICalDuration, rest : state }, [InvalidICalDuration(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 -> (ICalDuration, 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(ICalDuration, [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(ICalDuration, Error)

Parses a positive week/day/time duration. Days remain calendar quantities; hours, minutes and seconds form the coordinate tail. No zone is consulted.

is_eq : ICalDuration, ICalDuration -> Bool

Equality compares nominal days and coordinate seconds, without an anchor.

to_hash : ICalDuration, Hasher -> Hasher

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

components : ICalDuration -> { days : I64, seconds : I64 }

Returns calendar days and coordinate seconds separately. One day is not replaced by 86400 coordinate seconds.

to_duration : ICalDuration -> Duration

Converts to a duration for TimedOccurrence. Days advance the original source before the coordinate tail. The RFC timed policy selects the first fold occurrence and uses the offset before a gap (erratum 4271).

to_text : ICalDuration -> Str

Canonical RFC 5545 duration value text. Weeks become days; accurate time components become seconds.

fact_count : ICalDuration -> U64

Calendar days and accurate seconds remain separate components, without an invented anchor or conversion of calendar days to elapsed seconds.

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

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

Error : [Malformed, NonPositive, OutOfRange, TooLarge]

Reports malformed grammar, nonpositive duration, numerical range overflow or the input byte limit.