feat: implementation of the stdlib_datetime module

[JAi-SATHVIK]

#1147

[codecov]

Codecov Report

❌ Patch coverage is 81.47590% with 123 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.66%. Comparing base (c016c6d) to head (82a249f).
⚠️ Report is 44 commits behind head on master.

Files with missing lines	Patch %	Lines
src/datetime/stdlib_datetime.f90	75.41%	74 Missing ⚠️
example/datetime/example_datetime_usage.f90	0.00%	46 Missing ⚠️
test/datetime/test_datetime.f90	99.05%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1148      +/-   ##
==========================================
+ Coverage   68.00%   68.66%   +0.66%     
==========================================
  Files         403      407       +4     
  Lines       12850    13599     +749     
  Branches     1383     1534     +151     
==========================================
+ Hits         8738     9338     +600     
- Misses       4112     4261     +149     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Implements an experimental stdlib_datetime module, along with build integration, documentation, examples, and a new test suite to validate date/time arithmetic, parsing/formatting, and calendar utilities.

Changes:

• Added src/datetime/stdlib_datetime.f90 providing datetime_type / timedelta_type, arithmetic/comparison operators, ISO8601 parsing/formatting, and helper utilities.
• Integrated the datetime component into the library build and added a datetime test target and example program.
• Added a new spec document describing the module API and supported behaviors.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
src/datetime/stdlib_datetime.f90	New datetime/timedelta types, operators, ISO parsing/formatting, and calendar utilities.
src/datetime/CMakeLists.txt	Adds the datetime library target and links it to core.
src/CMakeLists.txt	Adds datetime subdirectory and links it into the top-level stdlib target.
test/datetime/test_datetime.f90	New unit tests for leap years, parsing/formatting, arithmetic, comparisons, and rollovers.
test/datetime/CMakeLists.txt	Registers datetime as a test target.
test/CMakeLists.txt	Adds datetime tests to the test build.
example/datetime/example_datetime_usage.f90	New usage example demonstrating common API calls.
example/datetime/CMakeLists.txt	Registers datetime example target.
example/CMakeLists.txt	Adds datetime examples to the example build.
doc/specs/stdlib_datetime.md	New specification page describing the module API and formats.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[JAi-SATHVIK]

Hi @jalvesz, I have a few questions regarding the module implementation. Could you please walk me through them?

Should timestamps without a designator (YYYY-MM-DDTHH:MM:SS) default to UTC (0) or be treated as unspecified?
Should parse_datetime support variable precision (e.g., .5, .50) or only exactly 3 fractional digits?
Should the datetime() constructor validate its arguments (e.g., month=13) or trust the caller to provide valid ranges?

[JAi-SATHVIK]

Hi @jalvesz Just checking in to see if there's any additional information I can provide to help with the review process. Happy to make any necessary adjustments!

[jvdp1]

Thank you @JAi-SATHVIK for this PR. A very complete set of procedures to handle dates an times IMO.

[JAi-SATHVIK]

Hi @jvdp1, I've made the requested changes. can you please review the PR?

[jalvesz]

Should timestamps without a designator (YYYY-MM-DDTHH:MM:SS) default to UTC (0) or be treated as unspecified?

Having a documented and standard default is a valid option. Can the timestamp designator be retrived from the OS ? that might be the better default.

Should parse_datetime support variable precision (e.g., .5, .50) or only exactly 3 fractional digits?

I think users might want extra precision for seconds and miliseconds, and optional argument with a default ot 3 could be a good way of enabling user desired precision.

Should the datetime() constructor validate its arguments (e.g., month=13) or trust the caller to provide valid ranges?

Would you mind explaining ?

Just wondering, did you take some inspiration from the python datetime module https://docs.python.org/3/library/datetime.html ?

[JAi-SATHVIK]

Thanks for the feedback! I've updated the module to use to_string with string concatenation for safer formatting. I also added support for variable fractional second precision in parse_datetime. I've documented that we're defaulting to UTC when the offset is missing as it's the safest cross-platform coordinate and that the datetime() constructor intentionally skips full validation for performance reasons.

Having a documented and standard default is a valid option. Can the timestamp designator be retrived from the OS ? that might be the better default.

• Unspecified Timezones: Defaulting to UTC is the safest absolute coordinate, as resolving local offsets for historical/future dates would require a non-intrinsic timezone database.

I think users might want extra precision for seconds and miliseconds, and optional argument with a default ot 3 could be a good way of enabling user desired precision.

• Agreed! I've updated parse_datetime to dynamically scan digits (e.g, .5, .50) into milliseconds.

Should the datetime() constructor validate its arguments (e.g., month=13) or trust the caller to provide valid ranges?

• parse_datetime is strict for safety, but the datetime() constructor skips bounds checks for speed in tight loops. I’ve added a note to the spec.

Just wondering, did you take some inspiration from the python datetime module https://docs.python.org/3/library/datetime.html ?

Inspiration: The datetime vs timedelta split is heavily inspired by Python’s pattern.

[jalvesz]

LGTM @JAi-SATHVIK thanks for this nice new functionality!

[jvdp1]

Thank you @JAi-SATHVIK for this nice addition to stdlib!

[cyrilgandon]

Hi, thanks for the great work on this PR, it's really appreciated.

I noticed the mention of potential date_type and time_type sub-types:

"Smaller sub-types if separating only the calendar date from the clock time is deemed necessary."

Do you currently plan to introduce these types as part of a follow-up, or is the intention to keep a single datetime_type for now?

I'm asking because separating date and time can be quite useful in practice, but I understand it also comes with additional API complexity.

Thanks!

[JAi-SATHVIK]

Hi @cyrilgandon, thanks for the feedback!

I used a unified datetime_type for now to build a stable foundation with a simpler API. I do plan to add date_type and time_type in a follow up PR once the core logic is tested. Feel free to share any specific use cases you have in mind

[cyrilgandon]

Hi, thanks for the clarification!

One concrete use case on my side: I work on STICS, a crop modeling system with a daily time step. We only manipulate calendar dates (year, month, day), and time of day is irrelevant.

In that context, a dedicated date_type would make the code clearer and avoid carrying unused time fields around.

Looking forward to the follow-up PR 🙂