Module temporal 

Cypher temporal-value construction, evaluated at lowering time.

The openCypher TCK constructs temporals from literal arguments — date('2015-W30-2'), date({year: 2015, month: 7, day: 21}) — and renders the result as a quoted canonical ISO string ('2015-07-21'). Because the argument is a constant, we can parse and canonicalise it during lowering (graphforge-rel) and emit a plain Utf8 literal, without a runtime UDF. Only the non-literal forms (rare in the corpus) fall back to DataFusion’s to_date/to_char.

This module currently covers date(<string>). The map form (date({year, month, day}) / ISO-week construction) and the time-bearing types (localtime/time/localdatetime/datetime) are follow-ups (#599).

Structs

DateOverrides

Component overrides for date-from-value projection (Temporal3). A field left None is taken from the base date. The active construction mode is selected by which override is present (week ▸ ordinal ▸ quarter ▸ calendar).

DurationValue

A Cypher duration: months and days are kept distinct (a month is not a fixed number of days), with everything finer than a day carried in nanos (integer nanoseconds — exact even for very large sub-day spans, unlike an f64 seconds count whose mantissa drops sub-second precision past ~1e15ns). A typed Cypher duration (ADR 0009 / #1011): signed months / days kept distinct (a month is not a fixed number of days), and the sub-day time split into whole seconds plus nanos-of-second. Splitting seconds from nanos lets a billion-year duration.inSeconds (~6.3e16 s) fit i64, where a single total-nanos field would overflow (~6.3e25 ns); months: i64 likewise holds the ~24e9-month spans duration.between can produce. nanos is in (-1e9, 1e9) and shares the sign of seconds (truncating split).

LocalTimeOverrides

Component overrides for localtime projection (localtime({time: base, …})): a field left None keeps the base’s value; the sub-second fields, if any are present, jointly replace the base fraction.

Enums

BetweenMode

Which duration.between-family function: the full split, or a single-unit total.

TemporalField

A temporal map-constructor field value, extracted from a literal map argument (date({year: 1984, …})) at lowering time. Variable references and other non-constant values can’t be extracted and make construction bail to the runtime path. (#599)

Functions

date_component

A date component value (openCypher Temporal5). ISO-8601 semantics for week/weekYear/weekDay; weekDay is 1 (Monday) … 7 (Sunday). None for an unknown accessor name.

date_from_map

Build a date (i64 days) from a literal map — the typed-value path (ADR 0009). None if the fields don’t form a valid date. (#1011)

date_plus_duration

date + duration (#920): only date-precision components apply — add the signed months then days. The duration’s sub-day time is ignored (a date has no time-of-day; openCypher does not carry it into days). Returns the date (i64 days), range-complete via crate::calendar (#1011).

date_to_epoch_days

i64 days since the Unix epoch (1970-01-01) for a chrono NaiveDate. No clamping — the full range round-trips (#1011).

datetime_plus_duration

localdatetime/datetime + duration (#920): add the signed months, then days, then the sub-day time (carrying whole-day overflow into the date). Returns the resulting (date, nanos_of_day).

datetime_value_from_map

Build a datetime from a literal field map (datetime({…, timezone})).

datetime_value_from_str

Parse a datetime(<string>) — offset form (…T…+01:00) or named-zone form (…T…[Europe/London], offset resolved at that instant). (ADR 0009)

duration_between

Compute duration.between/inMonths/inDays/inSeconds from a to b as a typed DurationValue (#920/#1011). Both operands dated → a calendar-aware month/day/time split (shifted to UTC instants only when both carry a zone offset); either operand time-only → just the time-of-day difference (no month/day span), offset-adjusted only when both are zoned.

duration_component

A duration component accessor (d.years, d.monthsOfQuarter, d.secondsOfMinute, d.nanosecondsOfSecond, …) over a typed duration. The *Of* forms give the component within the next-larger unit; the plain forms give the total in that unit (truncated toward zero). None for an unknown name. (#920)

duration_value_from_map

Build a duration({…}) DurationValue from a literal map. (#920/#1011)

duration_value_from_str

Parse duration(<string>) to a typed DurationValue. (#920/#1011)

epoch_component

A datetime epoch component (Temporal5): epochSeconds/epochMillis — the UTC instant of (date_days, nanos_of_day, offset_seconds). None for an unknown accessor name. (#920)

epoch_days_to_date

The chrono NaiveDate for an i64 days-since-epoch value — the in-range bridge for the date functions that keep chrono internals (projection, truncation, accessors, map construction). Returns None for a date outside chrono’s ±262k-year range; such extreme dates only occur on the parse→duration.between path, which uses crate::calendar directly. (#1011)

format_date

Canonical openCypher rendering of a date (i64 days): YYYY-MM-DD, signed for the expanded-year range (#1011). Delegates to crate::calendar.

is_date_accessor

Whether name is a date component accessor (d.year, d.weekDay, …).

is_duration_accessor

Whether name is a duration component accessor (see duration_component).

is_epoch_accessor

Whether name is a datetime epoch accessor (d.epochSeconds/ d.epochMillis). (#920)

is_time_accessor

Whether name is a time-of-day component accessor (d.hour, d.nanosecond, …) — valid on localtime/time/localdatetime/datetime. (#920)

is_zone_int_accessor

Whether name is a zone INT accessor (d.offsetMinutes/d.offsetSeconds) — valid on time/datetime. (#920)

is_zone_str_accessor

Whether name is a zone STRING accessor (d.timezone/d.offset) — valid on time/datetime. (#920)

localdatetime_parts_from_map

Build a localdatetime (date + nanoseconds-of-day) from a literal field map. (ADR 0009)

localdatetime_parts_from_str

Parse a localdatetime(<string>) (YYYY-…T HH:MM…) to (date-days, nanoseconds- of-day) — a date and time with NO offset (an offset is rejected, matching render_local_date_time).

localtime_nanos_from_map

Build a localtime (nanoseconds-of-day) from a literal field map. (ADR 0009)

localtime_nanos_from_str

Parse a strict localtime(<string>) to nanoseconds-of-day — a time of day with NO offset (an offset is rejected, matching render_local_time).

localtime_plus_duration

localtime/time + duration (#920): only the sub-day time applies (months/days are irrelevant to a time-of-day), wrapping mod 24h.

parse_date_or_datetime_prefix

The date component (i64 days) of a runtime temporal value for projection — a date is taken directly; a string is parsed as a date or the date part of a datetime (2015-07-21T…). (#920/#1011)

parse_date_string

Parse a Cypher ISO-8601 date string into a NaiveDate.

parse_offset_seconds

Parse a UTC offset designator (Z, ±HH, ±HH:MM, …) to signed seconds — the public entry point for a time/datetime timezone override. (ADR 0009)

project_date

Project a base date (i64 days) through component overrides (openCypher date({date: base, …}) select-semantics): take base, replace the named components, keep the rest. Range-complete via calendar (#920/#1011).

project_datetime

Project a datetime (Temporal3 [8]-[11]): apply the source’s zone to the local (date, nanos) after component overrides. With a new timezone: a numeric offset or named zone SHIFTS the instant when the source already had an offset (time/datetime), else ATTACHES (interpreting the local time as being in that zone). Without one, the source offset/zone (or UTC) is kept. (ADR 0009)

project_localtime

Project a base localtime through component overrides (select-semantics: replace the named components, keep the rest). None for an out-of-range component. (ADR 0009)

project_time

Apply a time projection’s zone semantics. With a new offset: if the base already had one (time/datetime), the wall-clock time SHIFTS to preserve the instant; otherwise (localtime/localdatetime) the offset is simply ATTACHED. Without a new offset, the base offset (or UTC) is kept. (ADR 0009)

render_date

Canonical openCypher rendering of date(<string>), or None if the string is not a recognised ISO date form.

render_date_time

Canonical openCypher rendering of datetime(<string>) — a date and time with a zone — or None. Handles both the offset form (…T21:40:32+01:00) and the named-zone form (…T21:40:32[Europe/London], whose offset is resolved from the IANA tz database at that instant, including historical LMT offsets like +00:53:28).

render_datetime_value

Canonical openCypher rendering of a datetime: YYYY-MM-DDTHH:MM…±HH:MM (Z for UTC), plus a trailing [Zone] for a named zone. (ADR 0009)

render_duration

Canonical openCypher rendering of duration(<string>), or None if the string is not a recognised ISO-8601 duration. Handles the designator form (P14DT16H12M, with decimal components like P0.75M/P2.5W spilling into smaller units) and the alternative date-time form (P2012-02-02T14:37:21.545).

render_duration_value

Canonical openCypher rendering of a typed DurationValue (reuses the same designator formatter as the string path; the integer seconds/nanos are preserved exactly, so a very large span renders without f64 precision loss). (#920)

render_from_epoch

datetime.fromepoch(seconds, nanoseconds) — a UTC datetime from a Unix epoch offset.

render_from_epoch_millis

datetime.fromepochmillis(milliseconds) — a UTC datetime from Unix epoch milliseconds.

render_local_date_time

Canonical openCypher rendering of localdatetime(<string>) — a date and time with no zone — or None.

render_local_time

Canonical openCypher rendering of localtime(<string>) — a time of day with no zone — or None.

render_localdatetime

Canonical openCypher rendering of a localdatetime (date-days + nanoseconds- of-day): YYYY-MM-DDTHH:MM[:SS[.fff…]], time precision derived from the value.

render_localtime_nanos

Canonical openCypher rendering of an Arrow Time64(Nanosecond) localtime (HH:MM / HH:MM:SS / HH:MM:SS.fff…, trailing-zero subseconds trimmed).

render_temporal_map

Canonical rendering of a temporal constructor called with a literal map argument (date({year: 1984, month: 10, day: 11})), or None if the fields don’t form a valid value for name. (#599)

render_time

Canonical openCypher rendering of time(<string>) — a time of day with a zone offset — or None. The offset is required.

render_time_value

Canonical openCypher rendering of a time value (nanoseconds-of-day + offset-seconds): time-of-day + offset (Z for UTC). (ADR 0009)

scale_duration

duration * factor / duration / factor (#920 Temporal8 [7]). Scales each component by factor, then normalises with the openCypher “approximate” rule: a fractional month overflows into days (× the Gregorian average month length, MONTH_SECS / DAY_SECS = 30.436875 days), a fractional day overflows into the sub-day time, each level truncated toward zero. factor is the multiplier (* n) or 1/n is applied by the caller for division — here we take the already-resolved factor as num with divide selecting 1/num component-wise to preserve precision.

time_component

A time-of-day component value (openCypher Temporal5) from a nanoseconds-of-day. millisecond/microsecond/nanosecond are the CUMULATIVE sub-second value at that resolution (645 / 645876 / 645876123), not the digits of a single place. None for an unknown accessor name. (#920)

time_of_day_nanos_any

Extract the time-of-day (nanoseconds-of-day) from ANY temporal string — localtime, time (offset dropped), or localdatetime/datetime (date prefix and any zone dropped) — for projecting a localtime out of another value (localtime({time: other})). (ADR 0009)

time_of_day_with_offset

Extract a time-of-day and (optional) offset from ANY temporal string for time projection: localtime/localdatetime → offset None (the new zone is attached); time/datetime → Some(offset) (a new zone shifts the instant). Drops a named-zone suffix and a date prefix. (ADR 0009)

time_offset_zone

Extract (nanoseconds-of-day, optional offset-seconds, optional zone label) from ANY temporal string — localtime/localdatetime → offset/zone None; time → Some(offset), no zone; datetime → offset + optional zone. Used when projecting a datetime from another value. (ADR 0009)

time_value_from_map

Build a time (nanoseconds-of-day, offset-seconds) from a literal field map (time({hour, …, timezone}); default zone is UTC). (ADR 0009)

time_value_from_str

Parse a time(<string>) to (nanoseconds-of-day, offset-seconds). The offset is REQUIRED (a time carries a zone). (ADR 0009)

truncate_date

Truncate a date to the start of a unit (openCypher date.truncate(unit, …)): millennium/century/decade round the year down; year/month/quarter → the first day of that period; weekYear → the Monday of ISO week 1; week → the Monday of the date’s week; day → the date itself. The optional override map is applied afterwards via project_date. None for an unknown unit. (#920)

truncate_time_nanos

Truncate a time-of-day (nanoseconds since midnight) to the start of a unit (openCypher localtime.truncate(unit, …) and the time component of the other *.truncate): hour/minute/second/millisecond/microsecond floor to that boundary; any unit coarser than a time-of-day (day and up) → midnight (0). None for an unknown unit. (#920)

zone_int_component

A zone INT component (Temporal5): offsetMinutes/offsetSeconds from a UTC offset in seconds. None for an unknown accessor name. (#920)

zone_str_component

A zone STRING component (Temporal5): offset (the ±HH:MM designator) or timezone (the named IANA zone if present, else the offset designator). None for an unknown accessor name. (#920)

Type Aliases

BetweenOperand

A reduced temporal operand for duration_between: an optional date (None for a time-only localtime/time), a time-of-day in nanoseconds, an optional zone offset in seconds (None for an unzoned value), and an optional named IANA zone (Some only for a datetime constructed with a zone name — needed to re-resolve the offset across a DST transition). (#920/#1007)