ClockTime

ClockTime :: # (opaque)

A local clock label at microsecond precision, without a date, zone or scale.

Parse a time from an appointment form. Omitted seconds are zero; canonical output includes them. Typed quoted literals use the same validation.

import time.ClockTime

expect {
    opening : ClockTime
    opening = "09:30"
    ClockTime.parse("09:30:00") == Ok(opening) and
        ClockTime.to_text(opening) == "09:30:00"
}

Examples assume a package dependency named time.

profile : Str

Native boundary-label profile HH:MM[:SS[.fraction]], using ASCII digits and one through six fractional digits when a decimal point is present. Omitted seconds mean zero; supplied resolution and spelling are not retained. No date, offset, zone, leap second, 24:00 or rounding is inferred. Input is bounded to 64 UTF-8 bytes before decoding. Missing required tokens return Incomplete; invalid grammar returns Malformed; fields use constructor errors even when a later field is missing. Incomplete prefixes must admit a valid completion; impossible first digits retain the corresponding field error. More than six fractional digits always returns UnsupportedPrecision. The seconds form follows the field grammar in RFC 3339 section 5.6 (https://www.rfc-editor.org/rfc/rfc3339#section-5.6, July 2002). Optional seconds are a native extension, not RFC timestamp conformance.

parse : Str -> Try(ClockTime, Error)

Parse HH:MM, HH:MM:SS or HH:MM:SS.fraction with one to six fractional digits. Omitted seconds are zero. Reject leap seconds, 24:00, finer precision and text outside the declared profile with structured errors.

to_text : ClockTime -> Str

Canonical output includes seconds and the shortest exact decimal fraction.

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

Build a decoder for one encoded clock-label string. Return the clock and unconsumed state; distinguish InvalidClockTime from outer Encoding errors.

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

Build an encoder that writes the canonical clock string, including seconds, through the supplied string encoding.

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

Typed literals validate through parse; runtime interpolation requires parse.

from_fields : Fields -> Try(ClockTime, [InvalidHour, InvalidMinute, InvalidSecond, UnsupportedLeapSecond, InvalidMicrosecond, ..])

Validate a local clock label: hours 0..23, minutes/seconds 0..59 and microseconds 0..999999. A second of 60 returns UnsupportedLeapSecond. No date or timezone is attached.

from_microseconds_since_midnight : I64 -> Try(ClockTime, [OutOfRange, ..])

Construct a clock label from 0 through 86399999999 microseconds since nominal midnight. Other values return OutOfRange; the input does not wrap.

to_microseconds_since_midnight : ClockTime -> I64

Read microseconds since nominal midnight, in 0..86399999999. This clock coordinate does not account for timezone transitions.

to_fields : ClockTime -> Fields

Read the validated hour, minute, second and microsecond fields.

is_eq : ClockTime, ClockTime -> Bool

Equality of clock labels within the same nominal day; values of other temporal domains must be converted explicitly.

is_lt : ClockTime, ClockTime -> Bool

Whether the first of two clock labels within the same nominal day precedes the second in their numeric order.

is_lte : ClockTime, ClockTime -> Bool

Whether the first of two clock labels within the same nominal day precedes or equals the second.

is_gt : ClockTime, ClockTime -> Bool

Whether the first of two clock labels within the same nominal day follows the second in their numeric order.

is_gte : ClockTime, ClockTime -> Bool

Whether the first of two clock labels within the same nominal day follows or equals the second.

to_hash : ClockTime, Hasher -> Hasher

Hash clock labels within the same nominal day consistently with equality for dictionary and set keys. Hash values are not a stable serialization format.

to_inspect : ClockTime -> Str

Return a concise diagnostic description of these clock labels within the same nominal day. Use explicit conversions or text serialization when storing or exchanging data.

Fields : { hour : U8, minute : U8, second : U8, microsecond : U32 }

Clock fields: hour 0..23, minute and second 0..59, microsecond 0..999999. Pass the complete record to from_fields for validation.

Error : [Malformed, Incomplete, TooLarge, UnsupportedPrecision, InvalidHour, InvalidMinute, InvalidSecond, UnsupportedLeapSecond, InvalidMicrosecond]

Clock parsing failures distinguish incomplete or malformed text, profile limits, invalid fields and unsupported leap seconds or fractional precision.