Implement stdlib_datetime - module for Dates, Times, and Time Deltas

[JAi-SATHVIK]

Motivation

Motivation

Working with dates, times, and time intervals is a fundamental requirement in almost all modern scientific computing disciplines (e.g., parsing climate datasets, writing logs, calculating intervals in financial models, astrophysical simulations).

Presently, Fortran provides the date_and_time() intrinsic subroutine, which returns an integer array values(1:8) containing components like year, month, day, hour, etc. However, performing any mathematical operations on these dates—such as adding 90 days to a timestamp or finding the total seconds between two events—forces the developer to write complex calendar logic from scratch to handle leap years, varying month lengths, and timezones.

I propose the addition of a comprehensive stdlib_datetime module to provide a high-level representation of Dates, Times, and Time Deltas (Intervals). This feature would bridge a significant gap with other modern languages like Python (datetime), C++ (std::chrono), and Java (java.time).

Proposed Interfaces and Derived Types

To provide robust time handling, the module would likely define three primary derived types:

1. datetime_type: Represents a specific point in time (Year, Month, Day, Hour, Minute, Second, Millisecond).
2. timedelta_type: Represents a duration or an interval of time (Days, Seconds, Milliseconds).
3. date_type / time_type: Smaller sub-types if separating only the calendar date from the clock time is deemed necessary.

Basic Usage Example:

use stdlib_datetime, only: datetime_type, timedelta_type, now, parse_date

type(datetime_type) :: t1, t2
type(timedelta_type) :: duration

! Get the current local time
t1 = now()

! Parse an ISO 8601 string easily
t2 = parse_date('2026-03-17T12:00:00Z')

! Calculate the difference between them
duration = t1 - t2

! Add an interval (e.g., 30 days) to a date
t2 = t2 + timedelta_type(days=30)

Required Functionality:

• Constructors: from year/month/day components, from intrinsic date_and_time arrays, and from ISO 8601 strings.
• Overloaded Operators (+, -, ==, <, >): For adding timedelta_type to datetime_type, subtracting dates to get an interval, and comparing dates.
• Component Extraction: Helper functions to extract specific elements (e.g., t%year(), t%day_of_week(), t%is_leap_year()).
• Formatting: Easy output to strings ('YYYY-MM-DD HH:MM:SS').

Prior Art

• Python: The datetime module is universally used to structure Python time calculations.
• C++: The <chrono> library provides durations, clocks, and time points.
• MATLAB: The datetime and duration arrays.
• Fortran libraries: There are various custom implementations scattered across GitHub (e.g., M. Hirsch's datetime-fortran), proving the extreme community demand for a standardized, native approach.

Additional Information

Implementing this module requires no complex C-bindings and no parameterized derived types (PDTs) (meaning compiler support will be near 100%). It is purely mathematical (Julian day calculations) and string manipulation, meaning it is easy to implement yet incredibly high impact for anyone doing data-wrangling in Fortran.

[JAi-SATHVIK]

I've raised a draft PR #1148 for the date time module implementation.