parquet_temporal Module

Independent, self-contained module providing the element-level Parquet date/time value types.

Provides three public types, each holding ONE element (not a whole column -- unlike parquet_string_column in the parquet_strings module):

• parquet_date -- a calendar date, stored as days since 1970-01-01 (identical to the physical value of Parquet's DATE / Arrow's date32 type).
• parquet_time -- a time of day, stored as nanoseconds since midnight (holds any Parquet TIME unit -- seconds/millis/micros/nanos -- exactly).
• parquet_timestamp -- an instant, stored losslessly as seconds since 1970-01-01T00:00:00 plus a nanosecond-of-second part (holds any Parquet TIMESTAMP unit, including legacy INT96 files, exactly).

All three are plain value types with an internal null state; a default-initialized element is null ("no value yet"). Element access follows a two-tier rule: semantic accessors (get, year, to_string, to_mjd, to_unix, comparison operators, ...) abort on a null element (guard with is_null), interop accessors (raw/set_raw/get_raw) never abort (they return 0 for a null element -- validity travels separately via is_null), and type-to-type conversions (get_date/get_time, set(date, time)) propagate null instead of aborting. Most procedures are elemental, so they apply directly to whole arrays (mask = ts%is_null(), call dates%set(years, months, days)).

Calendar math uses the proleptic Gregorian calendar (Howard Hinnant's exact-integer days_from_civil/civil_from_days algorithms). Timezone interpretation is deliberately out of scope: a parquet_timestamp always holds the stored epoch offset verbatim, and a column's timezone metadata is a column-level property of the read/write layer, not of the element. This module depends only on intrinsic modules (iso_fortran_env, ieee_arithmetic); it has no dependency on any other module in this library (the read/write integration layer depends on it, never the reverse).

Why the setters take intent(inout) rather than intent(out), and the obligation that creates. A POLYMORPHIC intent(out) dummy is not free: the compiler default-initialises the element through the runtime on entry, and a type-bound procedure's passed-object dummy has to be polymorphic, so an elemental setter pays that per element. Measured on a 4M-row whole-column read: the construction loop cost 12.3 ms with intent(out) and 3.4 ms with intent(inout) (3.6x), taking the whole date-column read from 23.5 ms to 14.5 ms. The same change on the timestamp setters took its loop from 17.2 ms to 5.7 ms.

The cost of that is an obligation moved from the compiler to this source: intent(out) reset EVERY component for free, whereas under intent(inout) a component a setter does not assign keeps whatever the element held before. So every intent(inout) setter here must assign every component of its type, and adding a component to one of these types means revisiting all of them. tools/check_source_conventions.py's check_temporal_setters_assign_all enforces exactly that, deriving both the component list and the setter list from this file so a new component or a new setter is covered without editing the check.

The converse is equally load-bearing and is enforced too: a setter with a caught-failure path that RETURNS without assigning self -- %parse with a success argument, and ts_set_date_time's null propagation -- must KEEP intent(out), because that is precisely what makes a failed or null-propagating call yield a null element rather than a stale one.