parquet_timestamp Derived Type

type, public :: parquet_timestamp

An instant, stored losslessly as whole seconds since 1970-01-01T00:00:00 plus a normalized nanosecond-of-second part (always 0..999999999, also for pre-epoch instants). Holds any Parquet TIMESTAMP unit exactly over the full int64 range of the stored value. Timezone-agnostic: holds the stored epoch offset verbatim. A default-initialized element is null.


Constructor

public interface parquet_timestamp

Constructs a valid parquet_timestamp, either from full civil fields (year, month, day, hour, minute, second[, nanosecond]) -- aborting on invalid fields -- or from a (parquet_date, parquet_time) pair, where a null input propagates to a null result.

  • private impure elemental function ts_new_civil(year, month, day, hour, minute, second, nanosecond) result(res)

    Civil-fields constructor specific for the parquet_timestamp generic; aborts on invalid fields.

    Arguments

    Type IntentOptional Attributes Name
    integer(kind=int32), intent(in) :: year

    calendar year.
    integer(kind=int32), intent(in) :: month

    month, 1..12.
    integer(kind=int32), intent(in) :: day

    day of month.
    integer(kind=int32), intent(in) :: hour

    hour, 0..23.
    integer(kind=int32), intent(in) :: minute

    minute, 0..59.
    integer(kind=int32), intent(in) :: second

    second, 0..59.
    integer(kind=int32), intent(in), optional :: nanosecond

    sub-second part, 0..999999999 (default 0).

    Return Value type(parquet_timestamp)

    the constructed element (valid).

  • private impure elemental function ts_new_date_time(date, time) result(res)

    Date-plus-time constructor specific for the parquet_timestamp generic; a null input propagates to a null result (never aborts).

    Arguments

    Type IntentOptional Attributes Name
    type(parquet_date), intent(in) :: date

    the calendar-date part.
    type(parquet_time), intent(in) :: time

    the time-of-day part.

    Return Value type(parquet_timestamp)

    the constructed element (null if an input is null).


Type-Bound Procedures

generic, public :: set => ts_set_civil, ts_set_date_time

Sets from civil fields or a date + time pair.

  • private impure elemental subroutine ts_set_civil(self, year, month, day, hour, minute, second, nanosecond)

    Civil-fields specific of the set generic: sets the element from (year, month, day, hour, minute, second[, nanosecond]), validated; marks it valid.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(inout) :: self

    receives the instant (marked valid).
    integer(kind=int32), intent(in) :: year

    calendar year.
    integer(kind=int32), intent(in) :: month

    month, 1..12.
    integer(kind=int32), intent(in) :: day

    day of month.
    integer(kind=int32), intent(in) :: hour

    hour, 0..23.
    integer(kind=int32), intent(in) :: minute

    minute, 0..59.
    integer(kind=int32), intent(in) :: second

    second, 0..59.
    integer(kind=int32), intent(in), optional :: nanosecond

    sub-second part, 0..999999999 (default 0).

  • private impure elemental subroutine ts_set_date_time(self, date, time)

    Date-plus-time specific of the set generic: combines a parquet_date and a parquet_time into an instant. A null input propagates: the result is null (never aborts).

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(out) :: self

    receives the instant (or null if an input is null).
    type(parquet_date), intent(in) :: date

    the calendar-date part.
    type(parquet_time), intent(in) :: time

    the time-of-day part.

procedure, public :: get => ts_get

Returns all civil fields (aborts on null).

  • private elemental subroutine ts_get(self, year, month, day, hour, minute, second, nanosecond)

    Returns all civil fields of the element; aborts on a null element, and on a year outside the integer(int32) range (practically unreachable for real data).

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the element.
    integer(kind=int32), intent(out) :: year

    calendar year.
    integer(kind=int32), intent(out) :: month

    month, 1..12.
    integer(kind=int32), intent(out) :: day

    day of month.
    integer(kind=int32), intent(out) :: hour

    hour, 0..23.
    integer(kind=int32), intent(out) :: minute

    minute, 0..59.
    integer(kind=int32), intent(out) :: second

    second, 0..59.
    integer(kind=int32), intent(out), optional :: nanosecond

    sub-second part, 0..999999999.

procedure, public :: get_date => ts_get_date

The date part; null propagates (never aborts).

  • private elemental function ts_get_date(self) result(res)

    Returns the calendar-date part as a parquet_date. A null element propagates to a null result (never aborts on null); aborts only if the date falls outside parquet_date's representable range (practically unreachable for real data).

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the element.

    Return Value type(parquet_date)

    the date part (null if the element is null).

procedure, public :: get_time => ts_get_time

The time-of-day part; null propagates (never aborts).

  • private elemental function ts_get_time(self) result(res)

    Returns the time-of-day part as a parquet_time. A null element propagates to a null result (never aborts).

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the element.

    Return Value type(parquet_time)

    the time-of-day part (null if the element is null).

procedure, public :: is_null => ts_is_null

Whether the element is null (never aborts).

  • private elemental function ts_is_null(self) result(res)

    Returns whether the element is null (the primary null guard; never aborts).

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the element.

    Return Value logical

procedure, public :: set_null => ts_set_null

Marks the element null.

  • private impure elemental subroutine ts_set_null(self)

    Marks the element null.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(inout) :: self

    the element (reset to the null state).

procedure, public :: set_raw => ts_set_raw

Sets the raw (seconds, nanoseconds) pair (interop).

  • private impure elemental subroutine ts_set_raw(self, seconds, nanoseconds)

    Sets the raw (seconds, nanoseconds) pair directly (interop/advanced accessor; marks the element valid); aborts on a nanosecond part outside the normalized 0..999999999 range.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(inout) :: self

    receives the value (marked valid).
    integer(kind=int64), intent(in) :: seconds

    whole seconds since 1970-01-01T00:00:00.
    integer(kind=int32), intent(in) :: nanoseconds

    nanosecond-of-second part, 0..999999999.

procedure, public :: get_raw => ts_get_raw

Raw (seconds, nanoseconds); zeros when null (interop).

  • private elemental subroutine ts_get_raw(self, seconds, nanoseconds)

    Returns the raw (seconds, nanoseconds) pair, or zeros for a null element (interop/advanced accessor; never aborts -- validity travels separately via is_null).

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the element.
    integer(kind=int64), intent(out) :: seconds

    whole seconds since 1970-01-01T00:00:00 (0 when null).
    integer(kind=int32), intent(out) :: nanoseconds

    nanosecond-of-second part (0 when null).

generic, public :: set_unix => ts_set_unix_i32, ts_set_unix_i64

Sets from a Unix-time value in a given unit.

  • private impure elemental subroutine ts_set_unix_i32(self, value, unit)

    int32 specific of set_unix; see ts_set_unix_i64.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(inout) :: self

    receives the value (marked valid).
    integer(kind=int32), intent(in) :: value

    Unix time in unit.
    integer, intent(in) :: unit

    one of the parquet_unit_* constants.

  • private impure elemental subroutine ts_set_unix_i64(self, value, unit)

    int64 specific of set_unix: sets the element from a Unix-time value -- value counts time since 1970-01-01T00:00:00 in unit. The unit is a conversion parameter only; it is not stored (the internal representation is always the canonical seconds+nanoseconds pair). Always exact; marks the element valid.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(inout) :: self

    receives the value (marked valid).
    integer(kind=int64), intent(in) :: value

    Unix time in unit.
    integer, intent(in) :: unit

    one of the parquet_unit_* constants.

procedure, public :: to_unix => ts_to_unix

Unix-time value in a given unit (aborts on null/loss).

  • private elemental function ts_to_unix(self, unit, exact) result(res)

    Returns the element as a single Unix-time integer in unit -- a pure query, never modifying the element. Aborts on a null element, on int64 overflow in the requested unit, and on precision loss (the value carries sub-unit precision) unless exact=.false., which floors toward negative infinity instead (floor, not truncation, so ordering is preserved across the epoch).

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the element (unchanged).
    integer, intent(in) :: unit

    one of the parquet_unit_* constants.
    logical, intent(in), optional :: exact

    default .true.; .false. => floor instead of abort.

    Return Value integer(kind=int64)

procedure, public :: set_mjd => ts_set_mjd

Sets from a real64 Modified Julian Date.

  • private impure elemental subroutine ts_set_mjd(self, mjd)

    Sets the element from a real64 Modified Julian Date (MJD 0 = 1858-11-17T00:00:00), rounding to the nearest nanosecond; marks it valid. Aborts on NaN or a magnitude beyond the representable range. real64 only by design -- real32 would silently lose precision (consecutive real32 values around a present-day MJD are ~340 s apart) and is deliberately not accepted.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(inout) :: self

    receives the instant (marked valid).
    real(kind=real64), intent(in) :: mjd

    Modified Julian Date (fractional days).

procedure, public :: to_mjd => ts_to_mjd

real64 Modified Julian Date (aborts on null).

  • private elemental function ts_to_mjd(self) result(res)

    Returns the element as a real64 Modified Julian Date; aborts on a null element. Resolution is limited by real64: ~1 microsecond in the current era -- for exact nanosecond round-trips use the civil fields or set_unix/to_unix instead.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the element.

    Return Value real(kind=real64)

procedure, public :: set_jd => ts_set_jd

Sets from a real64 Julian Date.

  • private impure elemental subroutine ts_set_jd(self, jd)

    Sets the element from a real64 Julian Date (JD = MJD + 2400000.5); same rounding, range and real64-only rationale as set_mjd. Note the coarser real64 resolution at JD magnitudes (~50 microseconds in the current era).

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(inout) :: self

    receives the instant (marked valid).
    real(kind=real64), intent(in) :: jd

    Julian Date (fractional days).

procedure, public :: to_jd => ts_to_jd

real64 Julian Date (aborts on null).

  • private elemental function ts_to_jd(self) result(res)

    Returns the element as a real64 Julian Date (JD = MJD + 2400000.5); aborts on a null element. Resolution ~50 microseconds in the current era (real64 at JD magnitudes) -- prefer to_mjd, the civil fields, or to_unix when that matters.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the element.

    Return Value real(kind=real64)

procedure, public :: to_string => ts_to_string

ISO-8601 "YYYY-MM-DDTHH:MM:SS[.fraction]" (aborts on null).

  • private subroutine ts_to_string(self, str)

    Writes the element as ISO-8601 "YYYY-MM-DDTHH:MM:SS[.fraction]" (year formatting as in parquet_date%to_string; fraction as in parquet_time%to_string); aborts on a null element. A subroutine for the same reason as parquet_date%to_string.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the element.
    character(len=:), intent(out), allocatable :: str

    receives the formatted date-time.

procedure, public :: parse => ts_parse

Sets from an ISO-8601 date-time string.

  • private impure elemental subroutine ts_parse(self, str, success)

    Sets the element from an ISO-8601 date-time string "[-]YYYY-MM-DD{T or space}HH:MM:SS[.fraction][Z]" (an optional trailing 'Z' is accepted and ignored -- values are stored as epoch offsets regardless). Failure handling matches parquet_date%parse: abort by default, or report via the optional success (leaving the element null).

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(out) :: self

    receives the parsed instant (or null on caught failure).
    character(len=*), intent(in) :: str

    ISO-8601 date-time string.
    logical, intent(out), optional :: success

    .true. on success; absent => abort on failure.

generic, public :: operator(==) => ts_eq

Equality (aborts on a null operand).

  • private elemental function ts_eq(a, b) result(res)

    Equality specific; see the operator(==) generic. Aborts on a null operand.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: a

    left operand.
    class(parquet_timestamp), intent(in) :: b

    right operand.

    Return Value logical

generic, public :: operator(/=) => ts_ne

Inequality (aborts on a null operand).

  • private elemental function ts_ne(a, b) result(res)

    Inequality specific; see the operator(/=) generic. Aborts on a null operand.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: a

    left operand.
    class(parquet_timestamp), intent(in) :: b

    right operand.

    Return Value logical

generic, public :: operator(<) => ts_lt

Ordering (aborts on a null operand).

  • private elemental function ts_lt(a, b) result(res)

    Less-than specific; see the operator(<) generic. Aborts on a null operand.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: a

    left operand.
    class(parquet_timestamp), intent(in) :: b

    right operand.

    Return Value logical

generic, public :: operator(<=) => ts_le

Ordering (aborts on a null operand).

  • private elemental function ts_le(a, b) result(res)

    Less-or-equal specific; see the operator(<=) generic. Aborts on a null operand.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: a

    left operand.
    class(parquet_timestamp), intent(in) :: b

    right operand.

    Return Value logical

generic, public :: operator(>) => ts_gt

Ordering (aborts on a null operand).

  • private elemental function ts_gt(a, b) result(res)

    Greater-than specific; see the operator(>) generic. Aborts on a null operand.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: a

    left operand.
    class(parquet_timestamp), intent(in) :: b

    right operand.

    Return Value logical

generic, public :: operator(>=) => ts_ge

Ordering (aborts on a null operand).

  • private elemental function ts_ge(a, b) result(res)

    Greater-or-equal specific; see the operator(>=) generic. Aborts on a null operand.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: a

    left operand.
    class(parquet_timestamp), intent(in) :: b

    right operand.

    Return Value logical

procedure, public :: diff_seconds => ts_diff_seconds

Real64-seconds difference (ts, ts); never aborts on magnitude.

  • private elemental function ts_diff_seconds(a, b) result(res)

    Type-bound diff_seconds: real64-seconds difference between two instants. Unlike operator(-) (ts_diff_ns), this never aborts on magnitude -- only precision is lost at extreme elapsed times, matching real64's own resolution. Aborts on a null operand. Each operand's seconds component is converted to real64 before subtracting (rather than subtracting as int64 first) -- two instants near opposite ends of the int64 range would overflow an int64 subtraction, whereas real64 subtraction only loses precision, matching this function's own "never aborts on magnitude" contract.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: a

    left (later) operand.
    class(parquet_timestamp), intent(in) :: b

    right (earlier) operand.

    Return Value real(kind=real64)

generic, public :: operator(-) => ts_diff_ns, ts_sub_ns_i32, ts_sub_ns_i64

Difference or ns offset (aborts on a null operand or int64 overflow).

  • private elemental function ts_diff_ns(a, b) result(res)

    Difference specific; see the operator(-) generic. Nanoseconds, exact; aborts on a null operand and when the elapsed time exceeds ~292.3 years (TS_DIFF_NS_BOUND_SECONDS) -- the bound is checked on the seconds component alone, without ever forming an intermediate value that could itself overflow int64, so the "too far apart to represent" case is detected before any arithmetic that could silently wrap.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: a

    left (later) operand.
    class(parquet_timestamp), intent(in) :: b

    right (earlier) operand.

    Return Value integer(kind=int64)

  • private impure elemental function ts_sub_ns_i32(self, n) result(res)

    int32 specific of operator(-); see ts_offset_ns_impl.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the instant to shift.
    integer(kind=int32), intent(in) :: n

    ns to subtract.

    Return Value type(parquet_timestamp)

    self shifted back by n ns.

  • private impure elemental function ts_sub_ns_i64(self, n) result(res)

    int64 specific of operator(-); see ts_offset_ns_impl.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the instant to shift.
    integer(kind=int64), intent(in) :: n

    ns to subtract.

    Return Value type(parquet_timestamp)

    self shifted back by n ns.

generic, public :: operator(+) => ts_add_ns_i32, ts_add_ns_i64

Ns offset (aborts on a null operand or int64 overflow).

  • private impure elemental function ts_add_ns_i32(self, n) result(res)

    int32 specific of operator(+); see ts_offset_ns_impl.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the instant to shift.
    integer(kind=int32), intent(in) :: n

    ns to add.

    Return Value type(parquet_timestamp)

    self shifted forward by n ns.

  • private impure elemental function ts_add_ns_i64(self, n) result(res)

    int64 specific of operator(+); see ts_offset_ns_impl.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_timestamp), intent(in) :: self

    the instant to shift.
    integer(kind=int64), intent(in) :: n

    ns to add.

    Return Value type(parquet_timestamp)

    self shifted forward by n ns.

Source Code

    type :: parquet_timestamp
        private
        integer(int64) :: seconds = 0_int64     !! whole seconds since 1970-01-01T00:00:00.
        integer(int32) :: nanoseconds = 0_int32 !! nanosecond-of-second part, always 0..999999999.
        logical :: valid = .false.              !! .false. = null element (the default state).
    contains
        procedure, private :: ts_set_civil        !! (year, month, day, hour, minute, second[, ns]) specific.
        procedure, private :: ts_set_date_time    !! (parquet_date, parquet_time) specific; null propagates.
        generic :: set => ts_set_civil, ts_set_date_time !! Sets from civil fields or a date + time pair.
        procedure :: get => ts_get                !! Returns all civil fields (aborts on null).
        procedure :: get_date => ts_get_date      !! The date part; null propagates (never aborts).
        procedure :: get_time => ts_get_time      !! The time-of-day part; null propagates (never aborts).
        procedure :: is_null => ts_is_null        !! Whether the element is null (never aborts).
        procedure :: set_null => ts_set_null      !! Marks the element null.
        procedure :: set_raw => ts_set_raw        !! Sets the raw (seconds, nanoseconds) pair (interop).
        procedure :: get_raw => ts_get_raw        !! Raw (seconds, nanoseconds); zeros when null (interop).
        procedure, private :: ts_set_unix_i32     !! int32 specific of set_unix.
        procedure, private :: ts_set_unix_i64     !! int64 specific of set_unix.
        generic :: set_unix => ts_set_unix_i32, ts_set_unix_i64 !! Sets from a Unix-time value in a given unit.
        procedure :: to_unix => ts_to_unix        !! Unix-time value in a given unit (aborts on null/loss).
        procedure :: set_mjd => ts_set_mjd        !! Sets from a real64 Modified Julian Date.
        procedure :: to_mjd => ts_to_mjd          !! real64 Modified Julian Date (aborts on null).
        procedure :: set_jd => ts_set_jd          !! Sets from a real64 Julian Date.
        procedure :: to_jd => ts_to_jd            !! real64 Julian Date (aborts on null).
        procedure :: to_string => ts_to_string    !! ISO-8601 "YYYY-MM-DDTHH:MM:SS[.fraction]" (aborts on null).
        procedure :: parse => ts_parse            !! Sets from an ISO-8601 date-time string.
        procedure, private :: ts_eq               !! == specific.
        procedure, private :: ts_ne               !! /= specific.
        procedure, private :: ts_lt               !! <  specific.
        procedure, private :: ts_le               !! <= specific.
        procedure, private :: ts_gt               !! >  specific.
        procedure, private :: ts_ge               !! >= specific.
        generic :: operator(==) => ts_eq          !! Equality (aborts on a null operand).
        generic :: operator(/=) => ts_ne          !! Inequality (aborts on a null operand).
        generic :: operator(<) => ts_lt           !! Ordering (aborts on a null operand).
        generic :: operator(<=) => ts_le          !! Ordering (aborts on a null operand).
        generic :: operator(>) => ts_gt           !! Ordering (aborts on a null operand).
        generic :: operator(>=) => ts_ge          !! Ordering (aborts on a null operand).
        procedure, private :: ts_diff_ns          !! (ts, ts) specific of operator(-): ns difference.
        procedure :: diff_seconds => ts_diff_seconds !! Real64-seconds difference (ts, ts); never aborts on magnitude.
        procedure, private :: ts_sub_ns_i32       !! (ts, integer(int32)) specific of operator(-).
        procedure, private :: ts_sub_ns_i64       !! (ts, integer(int64)) specific of operator(-).
        procedure, private :: ts_add_ns_i32       !! (ts, integer(int32)) specific of operator(+).
        procedure, private :: ts_add_ns_i64       !! (ts, integer(int64)) specific of operator(+).
        generic :: operator(-) => ts_diff_ns, ts_sub_ns_i32, ts_sub_ns_i64
        !! Difference or ns offset (aborts on a null operand or int64 overflow).
        generic :: operator(+) => ts_add_ns_i32, ts_add_ns_i64 !! Ns offset (aborts on a null operand or int64 overflow).
    end type parquet_timestamp