[libc++] Clarify clock behavior before epoch (LWG 3318)

[benedekaibas]

This patch resolves LWG issue 3318
by clarifying in the <chrono> header whether each clock supports time
before its epoch (i.e., negative time points).

The clocks with signed rep (e.g., system_clock, utc_clock) now
explicitly state they support time before their epoch. Clocks with
unspecified signedness clarify that behavior before epoch is unspecified.

This is a documentation-only change. No runtime behavior is modified.

Fixes #100430

[github-actions]

Thank you for submitting a Pull Request (PR) to the LLVM Project!

This PR will be automatically labeled and the relevant teams will be notified.

If you wish to, you can add reviewers by using the "Reviewers" section on this page.

If this is not working for you, it is probably because you do not have write permissions for the repository. In which case you can instead tag reviewers by name in a comment by using @ followed by their GitHub username.

If you have received no comments on your PR for a week, you can request a review by "ping"ing the PR by adding a comment “Ping”. The common courtesy "ping" rate is once a week. Please remember that you are asking for valuable time from other developers.

If you have further questions, they may be answered by the LLVM GitHub User Guide.

You can also ask questions in a comment on this PR, on the LLVM Discord or on the forums.

[llvmbot]

@llvm/pr-subscribers-libcxx

Author: Benedek Kaibas (benedekaibas)

Changes

This patch resolves LWG issue 3318
by clarifying in the <chrono> header whether each clock supports time
before its epoch (i.e., negative time points).

The clocks with signed rep (e.g., system_clock, utc_clock) now
explicitly state they support time before their epoch. Clocks with
unspecified signedness clarify that behavior before epoch is unspecified.

This is a documentation-only change. No runtime behavior is modified.

Fixes #100430

---

Full diff: https://github.com/llvm/llvm-project/pull/144697.diff

1 Files Affected:

• (modified) libcxx/include/chrono (+14-2)

diff --git a/libcxx/include/chrono b/libcxx/include/chrono
index 82e99a31bcc9f..fd6689c81c0c1 100644
--- a/libcxx/include/chrono
+++ b/libcxx/include/chrono
@@ -277,7 +277,9 @@ template <class Rep, class Period>
     constexpr duration<Rep, Period> abs(duration<Rep, Period> d);  // C++17
 
 // Clocks
-
+/// The system_clock represents wall-clock time based on the system-wide realtime clock.
+/// The representation for it is a signed representation, so it can express times before and after the epoch
+/// like: (1970-01-01 00:00:00 UTC).
 class system_clock
 {
 public:
@@ -306,6 +308,8 @@ template<class charT, class traits>                    // C++20
     operator<<(basic_ostream<charT, traits>& os, const sys_days& dp);
 
 // [time.clock.utc], class utc_clock
+/// The utc_clock represents Coordinated Universal Time (UTC)
+/// It uses a signed representation just like system_clock and represents time before and after its epoch
 class utc_clock {                                      // C++20
 public:
     using rep                       = a signed arithmetic type;
@@ -342,6 +346,8 @@ template<class Duration>                                // C++20
 
 
 // [time.clock.tai], class tai_clock
+/// The tai_clock uses Coordinated Universal Time (UTC).
+/// It uses a signed representation and can express time both before and after its epoch.
 class tai_clock {                                      // C++20
 public:
     using rep                       = a signed arithmetic type;
@@ -369,6 +375,8 @@ template<class charT, class traits, class Duration>     // C++20
     operator<<(basic_ostream<charT, traits>& os, const tai_time<Duration>& t);
 
 // [time.clock.gps], class gps_clock
+/// The gps_clock represents International Atomic Time (TAI). It uses a signed
+/// representation and can express time both before and after its epoch.    
 class gps_clock {                                      // C++20
 public:
     using rep                       = a signed arithmetic type;
@@ -395,6 +403,8 @@ template<class charT, class traits, class Duration>     // C++20
   basic_ostream<charT, traits>&
     operator<<(basic_ostream<charT, traits>& os, const gps_time<Duration>& t);
 
+/// The class file_clock is used for file timestamps. It uses a signed representation
+/// and can express time both before and after its epoch.
 class file_clock                                        // C++20
 {
 public:
@@ -420,6 +430,8 @@ template<class charT, class traits, class Duration>     // C++20
   basic_ostream<charT, traits>&
     operator<<(basic_ostream<charT, traits>& os, const file_time<Duration>& tp);
 
+/// The class steady_clock is monotonic and it does not support negative time points.
+/// Wheter it supports time before its epoch is unspecified.
 class steady_clock
 {
 public:
@@ -431,7 +443,7 @@ public:
 
     static time_point now() noexcept;
 };
-
+// high_resolution_clock is an alias for the steady_clock and has the same behavior.
 typedef steady_clock high_resolution_clock;
 
 // [time.clock.local] local time           // C++20

[frederick-vs-ja]

I believe we need to update https://github.com/llvm/llvm-project/blob/main/libcxx/docs/Status/Cxx20Issues.csv.

libc++'s duration::rep is nanoseconds so I think it can represent negative time points. According to the list in LWG3318, I think we don't need to mention signedness except for steady_clock and high_resolution_clock.

Also, it's also possibly redundant for steady_clock and high_resolution_clock. The standard says that the rep types are unspecified, and users can check the signedness by rep::min() < rep::zero(). Note that libc++ is already saying nanoseconds is the duration type of steady_clock in the comments.

[benedekaibas]

Thank you! I'll make the changes based on your suggestions!