InstantRange, a standard type

The moments from a start up to, but not including, an end.

Use it for a shift or a meeting slot. Because the end is left out, one slot can start exactly when the last one ends. For whole days, use DateRange.

Shape

Field	Type	Required?
`start`	`Instant`	Yes
`end`	`Instant`	Yes

Its parts keep these rules, and a value that breaks one fails with the rule's name:

start_not_after_end: start <= end

Example

example

InstantRange { start: "2026-10-25T09:00:00Z" end: "2026-10-25T17:00:00Z" }

text.parse(raw, as: InstantRange) reads one from text that comes from outside. Text that isn't one at all fails malformed, such as 2026-10-25T09:00:00Z or 2026-10-25T09:00:00Z/tomorrow.

These operations give one: range.intersection, temporal.day_bounds, temporal.month_bounds, temporal.week_bounds and temporal.year_bounds.

Good to know

start can't come after end.
temporal.day_bounds gives the range of a whole day in a Zone.
== tells you whether two are the same. < and list.sort_by don't take it, so sort by one of its parts instead.

In JSON

An object of its parts, in a request, a response or json.write:

json

{"start":"2026-10-25T09:00:00Z","end":"2026-10-25T17:00:00Z"}

Details

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

InstantRange 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-10-25T09:00:00Z/2026-10-25T17:00:00Z.

How it is stored

It is stored in one column named for the field, of type tstzrange. 2026-10-25T09:00:00Z/2026-10-25T17:00:00Z is stored as tstzrange('2026-10-25 09:00:00.000000+00'::timestamptz, '2026-10-25 17:00:00.000000+00'::timestamptz, '[)').

How it is shown to people

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

With locale: Locale.en_gb, zone: Zone.europe_london and format: TimeFormat.date_time_medium:

Value	Shown
`2026-10-25T09:00:00Z/2026-10-25T17:00:00Z`	`25 Oct 2026, 09:00:00 – 25 Oct 2026, 17:00:00`

Operations

range.contains(range: Range<T>, value: T) -> Bool: Whether value is inside range.
range.intersection(a: Range<T>, b: Range<T>) -> Range<T>?: The part a and b share; none when they don't overlap.
range.overlaps(a: Range<T>, b: Range<T>) -> Bool: Whether a and b share at least one value.
temporal.day_bounds(date: CalendarDate, zone: Zone) -> InstantRange: The instants date runs between in zone: 23, 24 or 25 hours.
temporal.month_bounds(date: CalendarDate, zone: Zone) -> InstantRange: The month holding date in zone.
temporal.week_bounds(date: CalendarDate, zone: Zone, starts_on: Weekday) -> InstantRange: The week holding date in zone, starting on starts_on.
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.