Module calendar 

A proleptic-Gregorian calendar on i64 days-since-epoch (#1011).

chrono’s NaiveDate caps near year ±262,143 and Arrow Date32 is i32 days (≈ year ±5.8M), but openCypher dates span years −999,999,999 … +999,999,999. This module does all DATE math on i64 days since the Unix epoch (1970-01-01), so the full range round-trips. It deliberately covers only the calendar (year/month/day/ordinal/ISO-week/weekday + day-precision arithmetic + ISO rendering); time-of-day stays nanoseconds-of-day and named zones stay chrono_tz (both year-independent).

The core conversions are Howard Hinnant’s days_from_civil / civil_from_days (http://howardhinnant.github.io/date_algorithms.html), exact for any year in the proleptic Gregorian calendar (which has a year 0). Cross-checked against chrono for in-range years in the unit tests.

Functions

add_months

Add a signed number of calendar months to (y, m, d), clamping the day to the target month’s length (e.g. Jan 31 + 1 month → Feb 28/29). Returns the resulting civil date.

add_months_to_days

Add months calendar months to a days count (day-clamped); convenience over add_months for the days representation.

civil_from_days

The civil date (year, month, day) for a days-since-epoch count (the inverse of days_from_civil). month is 1–12, day is 1–31.

days_from_civil

Days since 1970-01-01 for the civil date (year, month, day) in the proleptic Gregorian calendar. month is 1–12, day is 1–31 (not validated here — call ymd_to_days for the checked form). Exact for any i64 year in range.

days_in_month

Number of days in month (1–12) of year (28–31). month out of range → 0.

days_in_year

Days in year (365 or 366).

format_date

Canonical openCypher ISO rendering of a date (YYYY-MM-DD). Years 0000–9999 are zero-padded to four digits with no sign; outside that range the ISO-8601 expanded form applies — a leading + for years > 9999 and - for negative years (Neo4j: “a plus sign must prefix any year after 9999”). Matches chrono’s %Y for the years chrono can render, and extends past chrono’s ±262k cap.

format_year

Year formatting shared by date / localdatetime / datetime rendering.

from_iso_ywd

Days for the ISO (iso_year, week, weekday) (weekday 1 = Mon … 7 = Sun). None if week/weekday is out of range for that ISO year.

from_ordinal

Days for the ordinal-th day of year (1 = Jan 1). None if out of range.

is_leap

Whether year is a leap year in the proleptic Gregorian calendar.

iso_week

The ISO-8601 week-based year and week number (iso_year, week) for a days count. The ISO week-year can differ from the calendar year near Jan 1 / Dec 31.

iso_weekday

ISO weekday, 1 = Monday … 7 = Sunday.

iso_weeks_in_year

The number of ISO weeks in iso_year (52 or 53).

num_days_from_monday

Days from the Monday of the date’s week (0 = Monday … 6 = Sunday).

ordinal

The 1-based day-of-year (1–366) for a days count.

quarter_of_month

The 1-based quarter (1–4) of month (1–12).

ymd_to_days

Validated civil → days: None for an out-of-range month/day (e.g. 2025-02-30).