Document that SystemTime does not count leap seconds
Fixes#77994
This may not be entirely uncontroversial. I know that `@Ekleog` is going to disagree. However, in support of this docs change:
This documents the current behaviour. The alternative would be to plan to *change* the behaviour.
There are many programs which need to get a POSIX time (a `time_t`). Right now, `duration_since(UNIX_EPOCH)` is the only facility in std that does that. So, that is what programs use. Changing the behaviour would break[1] all of those programs. We would need to define a new API that can be used to get a POSIX time, and get everyone to use it. This seems highly unpalatable.
And, even if we wanted to do that, time with leap seconds is a lot less easy to work with. We would need to arrange to have a leap seconds table available to `std` somehow, and make sure that it was kept up to date. Currently we don't offer to do that for timezone data, which has similar needs. There are other complications. So it seems it would be awkwarrd to *implement* a facility that provides time including leap seconds, and the resulting value would be hard for applications to work with.
Therefore, I think it's clear that we don't want to plan to ever change `SystemTime`. We should plan to keep it the way it is. Providing TAI (for example) should be left to external crates, or additional APIs we may add in the future.
For more discussion see #77994 and in particular `@fanf2's` https://github.com/rust-lang/rust/issues/77994#issuecomment-1409448174
[1] Of course, by "break" we really only mean *future* breakage in the case where there is, in fact, ever another leap second. There may well not be: they are in the process of being abolished (although this is of course being contested). But if we decide that `SystemTime::now().duraton_since(UNIX_EPOCH)` counts leap seconds, it would start to return `Durations`s that are 27s different to the current answers. That's clearly unacceptable. And we can hardly change `UNIX_EPOCH` by 27s.
fb98f7adc3