GregorianDate

GregorianDate :: # (opaque)

Proleptic Gregorian day, with astronomical years (0 means 1 BCE). Valid years are -2147483648 through 2147483647, inclusive. No timezone or resolved timeline is implied by a date.

Example

Create a date and read its fields. Invalid leap days return InvalidDay; year zero and negative years use astronomical numbering.

import time.GregorianDate

expect {
    date = GregorianDate.from_fields({ year: 2024, month: 2, day: 29 })?
    GregorianDate.to_fields(date).day == 29
}
expect {
    invalid = GregorianDate.from_fields({ year: 2025, month: 2, day: 29 })
    invalid == Err(InvalidDay)
}

Parse a form field or validate a typed literal. Canonical output keeps the calendar date; use a description type when supplied resolution matters.

import time.GregorianDate

expect {
    due : GregorianDate
    due = "2026-09-07"
    GregorianDate.parse("2026-09-07") == Ok(due) and
        GregorianDate.to_text(due) == "2026-09-07"
}

Examples assume a package dependency named time. Week queries use the accounting date as supplied: for example, 2021-01-01 is Friday, ordinal day 1, in ISO week 53 of 2020. Group by both week_year and week; the Gregorian year alone does not identify an ISO week.

profile : Str

Native Gregorian full-date text, with no timezone or reduced resolution. Years 0..9999 have four digits; negative years have a minus and at least four magnitude digits; larger positive years have a plus and no padding. Signed expanded years are a library extension, not an RFC 3339 claim. Input longer than 64 UTF-8 bytes returns TooLarge; parsing work is bounded. Incomplete means a valid unfinished prefix. Completed invalid fields and impossible day prefixes (such as 1900-02-3) retain constructor errors.

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

Build a decoder for one encoded string containing a Gregorian full date. Return the validated date and unconsumed encoding state; distinguish InvalidGregorianDate from failures of the outer Encoding.

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

Build an encoder that writes this date as its canonical full-date string using the supplied string encoding. Propagate errors from that encoding.

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

Support validated quoted date literals when the expected type is GregorianDate. Invalid literals are rejected with BadQuotedBytes; use parse for runtime text.

parse : Str -> Try(GregorianDate, Error)

Parse a full Gregorian date using the declared native profile, such as 2026-09-07. Signed expanded years are supported within the provider range. Return structured errors for invalid dates, incomplete or malformed text, and inputs beyond the profile limits.

to_text : GregorianDate -> Str

Total canonical output across this provider's full signed-year range.

from_fields : Fields -> Try(GregorianDate, [OutOfRange, InvalidMonth, InvalidDay, ..])

Validate a proleptic Gregorian date with astronomical year numbering. Return OutOfRange outside the supported year range, InvalidMonth outside 1..12, or InvalidDay for a nonexistent day. No clamping is performed.

days_in_month : I64, U8 -> Try(U8, [OutOfRange, InvalidMonth, ..])

Return the number of days in a Gregorian month, including its leap-year rule. Reject unsupported years with OutOfRange and months outside 1..12 with InvalidMonth.

to_fields : GregorianDate -> Fields

Read the validated astronomical year and one-based month/day in the Gregorian calendar.

weekday : GregorianDate -> Weekday

Gregorian weekday, with the same seven tags as CalendarPattern.Weekday. This queries the supplied civil date without selecting a timezone.

ordinal_day : GregorianDate -> U16

One-based day within the Gregorian year: 1..365, or 1..366 in leap years. Total across the full supported year range, with constant bounded work.

iso_week_date : GregorianDate -> IsoWeekDate

ISO weeks start Monday; week 1 contains January 4. The week-numbering year can differ from the calendar year. Its I64 result can extend beyond this date provider: 2147483647-12-30 belongs to 2147483648-W01. Total, constant bounded scalar work; no adjacent date is constructed.

to_civil_day : GregorianDate -> CivilDay

Convert this date to the shared civil-day coordinate. Equal dates across calendars have equal coordinates; no timezone is chosen.

from_civil_day : CivilDay -> Try(GregorianDate, [OutOfRange, ..])

Describe a shared civil-day coordinate in the Gregorian calendar. Return OutOfRange if that day lies outside the supported year range.

to_hash : GregorianDate, Hasher -> Hasher

Hash Gregorian dates consistently with equality for dictionary and set keys. Hash values are not a stable serialization format.

to_inspect : GregorianDate -> Str

Return a concise diagnostic description of these Gregorian dates. Use explicit conversions or text serialization when storing or exchanging data.

is_lt : GregorianDate, GregorianDate -> Bool

Whether the first of two Gregorian dates precedes the second in their numeric order.

is_lte : GregorianDate, GregorianDate -> Bool

Whether the first of two Gregorian dates precedes or equals the second.

is_gt : GregorianDate, GregorianDate -> Bool

Whether the first of two Gregorian dates follows the second in their numeric order.

is_gte : GregorianDate, GregorianDate -> Bool

Whether the first of two Gregorian dates follows or equals the second.

is_eq : GregorianDate, GregorianDate -> Bool

Equality of Gregorian dates; values of other temporal domains must be converted explicitly.

Fields : { year : I64, month : U8, day : U8 }

Astronomical year and one-based month/day fields for a Gregorian date. Year zero means 1 BCE; from_fields validates combinations and provider range.

Error : [Malformed, Incomplete, OutOfRange, InvalidMonth, InvalidDay, TooLarge]

Parsing failures distinguish unfinished input, malformed text, invalid calendar fields, unsupported year range and input longer than the profile limit.

Weekday : [Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday]

Weekday names in Monday-through-Sunday order. They describe civil dates, without a timezone or an elapsed-duration interpretation.

IsoWeekDate : { week_year : I64, week : U8, weekday : Weekday }

ISO week-based year, week number (1..53) and weekday. The week_year may differ from the ordinary calendar year near New Year.