datetime: add compact timedelta formatting for zero-day durations

[14NGiestas]

Summary

This PR improves duration formatting in the datetime module by adding compact, human-friendly output for zero-day timedeltas while preserving the existing verbose format for nonzero-day values.

What changed

• Updated format_timedelta in src/datetime/stdlib_datetime.f90 to use compact zero-day formatting:
  • 5ms for sub-second durations
  • 1.500s or 42s for sub-minute durations
  • MM:SS when hours are zero
  • HH:MM:SS[.mmm] otherwise
• Preserved verbose formatting for nonzero-day durations: X days, HH:MM:SS[.mmm].
• Updated datetime spec text and examples in doc/specs/stdlib_datetime.md.
• Added example output cases in example/datetime/example_datetime_usage.f90.
• Expanded and registered unit tests in test/datetime/test_datetime.f90.
• (NEW) Added a optional compact, pass compact=.true. to the new behavior, the default is the old verbose.

Why

The prior formatting was always verbose, which made short durations harder to scan. Compact formatting improves readability for common short intervals while preserving the legacy representation where day-level context is meaningful.

Validation

• test_datetime includes new compact-format coverage and legacy-format checks.
• Local run passed for datetime tests after preprocessing/build setup.

Compatibility

• Backward compatible for nonzero-day durations (verbose format unchanged).
• Intentional output change for zero-day durations to compact formats.

[codecov]

Codecov Report

❌ Patch coverage is 95.83333% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 68.43%. Comparing base (9a15c77) to head (d233074).

Files with missing lines	Patch %	Lines
src/datetime/stdlib_datetime.f90	95.83%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1185      +/-   ##
==========================================
+ Coverage   68.20%   68.43%   +0.22%     
==========================================
  Files          19       19              
  Lines        2378     2395      +17     
==========================================
+ Hits         1622     1639      +17     
  Misses        756      756              

☔ View full report in Codecov by Harness.
📢 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.

[jvdp1]

Thank you @14NGiestas . Overall LGTM. O wonder if the compact format could be optional.

[jvdp1]

Should this format be optional, e.g.,

str = format_timedelta(compact=.true.)

[14NGiestas]

Thank you @14NGiestas . Overall LGTM. O wonder if the compact format could be optional.

That's a good idea, so it keeps backwards compatible just in case someone's workflow already depends on it (I can think of tests that might break if comparing the strings).

It would be nicer in the future a way of controlling it globally but just to streamline this PR, I will default compact as .false. and require users (me) to type compact=.true. in some wrapper.

Relevant XKCD: 1172

[Copilot]

Pull request overview

This PR extends stdlib_datetime’s format_timedelta to support an opt-in compact formatting mode for zero-day durations, while preserving the existing verbose representation by default.

Changes:

• Added optional compact argument to format_timedelta to enable compact formatting for zero-day timedeltas.
• Updated unit tests to cover both legacy formatting and the new compact mode.
• Updated documentation and example usage to describe/demonstrate the new behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
src/datetime/stdlib_datetime.f90	Adds compact optional argument and implements compact formatting branch for days==0.
test/datetime/test_datetime.f90	Adds compact-format test coverage and expands legacy-format assertions.
example/datetime/example_datetime_usage.f90	Adds a “Compact Duration Formatting” example section (currently missing compact=.true. in calls).
doc/specs/stdlib_datetime.md	Documents compact formatting option and updates syntax/return examples (currently missing .mmm note for MM:SS[.mmm]).

Suppressed comments (1)

example/datetime/example_datetime_usage.f90:78

• These example printouts are labeled as compact formatting but still use the default legacy formatting because compact=.true. is not passed.

    duration = timedelta(seconds=65)
    print '(A,T40,A)', 'timedelta(s=65):', format_timedelta(duration)
    duration = timedelta(hours=1, minutes=2, seconds=3)
    print '(A,T40,A)', 'timedelta(1h 2m 3s):', format_timedelta(duration)

---

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