feat: implementation of the stdlib_datetime module

[JAi-SATHVIK]

#1147

[codecov]

Codecov Report

❌ Patch coverage is 81.41593% with 126 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.64%. Comparing base (c016c6d) to head (d02a595).
⚠️ Report is 14 commits behind head on master.

Files with missing lines	Patch %	Lines
src/datetime/stdlib_datetime.f90	75.55%	77 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.64%   +0.64%     
==========================================
  Files         403      407       +4     
  Lines       12850    13613     +763     
  Branches     1383     1536     +153     
==========================================
+ Hits         8738     9345     +607     
- Misses       4112     4268     +156     

☔ 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.

[jvdp1]

could this function be pure?

[JAi-SATHVIK]

This procedure cannot be PURE because the Fortran standard prohibits the use of internal WRITE statements within pure subprograms.

[jvdp1]

Internal write are allowed in pure procedures.
See an example here:

stdlib/src/strings/stdlib_strings_to_string.fypp

Line 20 in e33b3eb

write(buffer, '(' // optval(format, "g0") // ')', iostat=stat) value

Or does I miss something?

[JAi-SATHVIK]

my mistake! I've updated both format_datetime and format_timedelta to be pure. Thanks for the correction and the reference.