CalendarDate, a standard type

A day on the calendar, with no time or zone: 2026-10-25.

Use it for birthdays, due dates and anything else that is a day wherever you are. For a moment in time, use Instant. For a span of days, use DateRange.

Shape

One value, with no fields to fill in. As text it reads 2026-10-25.

Example

example

CalendarDate("2026-10-25")

text.parse(raw, as: CalendarDate) reads one from text that comes from outside. Text that isn't one at all fails malformed, such as 2026-02-30 or 25/10/2026.

These operations give one: temporal.add_days, temporal.add_months, temporal.add_years and temporal.date.

Good to know

temporal.add_days, temporal.add_months and temporal.add_years give another.
It checks the date is real, so 2026-02-30 is refused.
== tells you whether two are the same, and < and list.sort_by compare and sort them.

In JSON

A string, in a request, a response or json.write:

json

"2026-02-28""2026-10-25"

Details

Text form, storage, how it is shown, and operations

CalendarDate is in the group Time and calendar, and has been in Jadpo since 0.1.0.

Text form

text.from writes one standard text form, the same form text.parse reads back: 2026-02-28 and 2026-10-25.

How it is stored

It is stored in one column named for the field, of type date. 2026-10-25 is stored as '2026-10-25'::date.

How it is shown to people

text.format(value, locale:) shows it to people in their locale. A call also gives format:.

With locale: Locale.en_gb and format: TimeFormat.date_medium:

Value	Shown
`2026-02-28`	`28 Feb 2026`
`2026-10-25`	`25 Oct 2026`

Operations

temporal.add_days(value: T, days: Int, dst: Dst?) -> T: value moved by whole calendar days, the clock time kept.
temporal.add_months(value: T, months: Int, invalid_day: InvalidDay?, dst: Dst?) -> T: value moved by whole calendar months, the day and clock time kept.
temporal.add_years(value: T, years: Int, invalid_day: InvalidDay?, dst: Dst?) -> T: value moved by whole calendar years, the day and clock time kept.
temporal.date(value: ZonedTime) -> CalendarDate: A local time's date.
temporal.day(value: T) -> Int: The day of the month, from 1.
temporal.day_bounds(date: CalendarDate, zone: Zone) -> InstantRange: The instants date runs between in zone: 23, 24 or 25 hours.
temporal.month(value: T) -> Int: The month, from 1 for January.
temporal.month_bounds(date: CalendarDate, zone: Zone) -> InstantRange: The month holding date in zone.
temporal.occurrences(rule: RecurrenceRule, from: T, count: Int) -> List<ZonedTime>: The next count occurrences of rule at or after from, in its zone (RFC 5545): fewer when the rule ends first; count is from 1 to 1000, so an unbounded rule is never expanded without a bound. From a date, the days they fall on, List<CalendarDate>, which a rule on dates gives; from an Instant, a timed rule's local times.
temporal.period_between(start: CalendarDate, end: CalendarDate) -> CalendarPeriod: Whole years, months and days from start to end, so start plus the period is end; each part negative when end is earlier.
temporal.week_bounds(date: CalendarDate, zone: Zone, starts_on: Weekday) -> InstantRange: The week holding date in zone, starting on starts_on.
temporal.weekday(value: T) -> Weekday: The day of the week.
temporal.year(value: T) -> Int: The year of a date or of a local time's date.
temporal.year_bounds(date: CalendarDate, zone: Zone) -> InstantRange: The year holding date in zone.

It also takes text.parse, text.from, text.format, json.read, json.write and ==. How every standard type behaves says how they work.