feat: add date and time functionality

[algebraic-dev]

This PR introduces date and time functionality to the Lean 4 Std. It's not complete yet and I need to implement some these things:

• Implement parsing for various date and time formats (In the Format module so I can easily create a format for all the standard formats like ISO8601).
• Improve support for Timezone handling (add timezone Database by reading the Linux /usr/share/zoneinfo/ or using a hardcoded version).
• Introduce macros for date creation e.g %date 2000-01-01.
• Add some native code to retrieve system date and time information.
• Tests

[leanprover-community-mathlib4-bot]

Mathlib CI status (docs):

• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase a845a007ac07350824c0b7773a03302373d8e8f1 --onto 647a5e94925791f6a16b629b6c16ffad60a7f478. (2024-08-05 18:32:45)
• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase 63c4de5fea9e083ba09e4e243e04cdff428b7beb --onto 647a5e94925791f6a16b629b6c16ffad60a7f478. (2024-08-07 20:58:20)
• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase 63c4de5fea9e083ba09e4e243e04cdff428b7beb --onto dd6ed124baef64a26ef5860f49597fdcef371239. (2024-08-09 17:53:25)
• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase 63c4de5fea9e083ba09e4e243e04cdff428b7beb --onto f3e7b455bbd4ea39376e0928d0d6cb8d26bd0ba3. (2024-08-14 21:42:05)
• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase 63c4de5fea9e083ba09e4e243e04cdff428b7beb --onto 8c96d213f3089ac2352ed95e79645f4cdbd70ebf. (2024-08-15 19:34:28)
• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase 63c4de5fea9e083ba09e4e243e04cdff428b7beb --onto 0ecbcfdcc3785c155b8f394c655f48f4f7ed0e65. (2024-08-16 18:00:42)
• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase 63c4de5fea9e083ba09e4e243e04cdff428b7beb --onto b486c6748b153bda628575635baa28aeeb38b8c5. (2024-08-19 12:17:55)
• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase 63c4de5fea9e083ba09e4e243e04cdff428b7beb --onto 4aa74d9c0b0e9706b819af655dfe3f4954213102. (2024-08-20 15:33:01)
• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase c45a6a93f98b004d2e10574d25ee5898bdf0ee34 --onto 9305049f1ef7309842806c2a994a2020bb32a71f. (2024-08-26 22:45:51)
• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase c45a6a93f98b004d2e10574d25ee5898bdf0ee34 --onto 9ce15fb0c61e3a1bee17fd81647ed4d02b4f6c6d. (2024-08-28 12:18:02)
• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase c45a6a93f98b004d2e10574d25ee5898bdf0ee34 --onto d31066646dfa7389d818a2e2e1493be6a941924e. (2024-09-02 15:54:12)
• ❗ Batteries/Mathlib CI will not be attempted unless your PR branches off the nightly-with-mathlib branch. Try git rebase a6830f90ab365e14ccb7ca31201de37f8c1e978c --onto d8e0fa425b3225fc0c35c07247ecb11b49bb00ed. (2024-09-20 18:05:17)
• 💥 Mathlib branch lean-pr-testing-4904 build failed against this PR. (2024-09-26 02:55:14) View Log
• 💥 Mathlib branch lean-pr-testing-4904 build failed against this PR. (2024-10-11 22:38:12) View Log

[TwoFX]

Please add tests for the various conversion routines that catch all of the interesting cases.

It would be very nice to have a few examples of the library being used in practice to achieve some common things.

[kim-em]

A very minor suggestion for an in-Lean use case: have the @[deprecated (since := "2024-08-09")] attribute complain if the date is not formatting sensibly.

[TwoFX]

Gentle reminder that we will not be able to merge this until there are decent tests for much of the functionality.

[TwoFX]

I have been reading up on leap seconds a bit more and I am now no longer convinced that it is a good idea to handle leap seconds in our library at all.

It appears to me that currently the leap second handling in the library allows converting between what I'll call "Unix Timestamps" and "UTC Timestamps" (perhaps "TAI Timestamp" would be more accurate, I'm not sure). The former is the number of "seconds" since UNIX epoch pretending that every day has exactly 86400 seconds and the latter is the number of SI seconds that have elapsed since UNIX epoch. The former corresponds to the std::chrono sys_time and the latter corresponds to utc_time.

Due to the way Unix timestamps work (see Wikipedia), if I just take the current time according to sys_time (as you do in Timestamp.now) and naively add it to 1970-01-01 00:00:00, then I will get the correct time.

It doesn't appear to me to be the case that having to handle UTC timestamps is something that comes up in practice.

A theoretical advantage of having the leap second information around would be to correctly calculate the number of (SI) seconds between two wall-clock readings in a given location, but the current API doesn't make this easy and furthermore, neither java.time nor std::chrono nor the Rust chrono crate can do this, so it doesn't seem particularly important.

In summary, my suggestion would be to

• remove leap seconds from ZoneRules
• drop all of the conversion functions that use this data
• probably (?) keep the possibility to represent a leap second in PlainTime (though I have to admit that my previous comment here might have been misguided - it's not clear to me now that being dependent here is particularly helpful. Maybe it would be more helpful if PlainTime, PlainDateTime and ZonedDateTime were also dependent, but that seems quite excessive), but be very particular about how leap seconds are handled in the formatting and the arithmetic. After writing this comment I noticed that what I'm suggesting is quite close to this discussion.

What do you think about this suggestion? If we do keep the "UTC timestamps" around, then I would strongly suggest having them be a different type from Timestamp, which I would suggest should always refer to Unix time.

[algebraic-dev]

I agree that handling UTC timestamps may not be necessary. However, I think that it is important to keep the support for leap seconds just to try keep the support for ISO 8601 compliant dates. In the future, If someone requests (that will not be the case I guess given that a lot of libraries don't implement something like that), I think that we can consider deriving a specialized type from the Timestamp type to address these problems.

[TwoFX]

However, I think that it is important to keep the support for leap seconds just to try keep the support for ISO 8601 compliant dates.

If I'm understanding you correctly, this is compatible with my request above, i.e., not reading the leap second information from the time zone database but keeping leap second representation in PlainTime, right?