Time v0.3 tracking issue

[jhpratt]

Time v0.2 was an outstanding learning experience, and by all accounts is a massive improvement over v0.1. However, a number of ill-informed decisions were made which led to some inconsistencies and many deprecated APIs.

All deprecated methods and structs have ready-to-use alternatives, which will be detailed before a release. As such, I would like to remove all deprecated APIs. This currently includes the following.

Deprecated APIs

• v0.1 APIs, currently behind a default feature flag
  • PreciseTime
  • SteadyTime
  • precise_time_ns
  • precise_time_s
  • Instant::to
  • Duration::num_weeks
  • Duration::num_days
  • Duration::num_hours
  • Duration::num_minutes
  • Duration::num_seconds
  • Duration::num_milliseconds
  • Duration::num_microseconds
  • Duration::num_nanoseconds
  • Duration::span
  • Duration::from_std
  • Duration::to_std
• Panicking APIs, currently behind a non-default feature flag
  • Date::from_ymd
  • Date::from_yo
  • Date::from_iso_ywd
  • Date::with_hms
  • Date::with_hms_milli
  • Date::with_hms_micro
  • Date::with_hms_nano
  • Time::from_hms
  • Time::from_hms_milli
  • Time::from_hms_micro
  • Time::from_hms_nano
• APIs that assume an offset of UTC, currently enabled unconditionally
  • Date::today
  • Time::now
  • PrimitiveDateTime::now
  • PrimitiveDateTime::unix_epoch
  • PrimitiveDateTime::from_unix_timestamp
  • PrimitiveDateTime::timestamp
  • OffsetDateTime::now
• Other APIs that were deprecated during the course of v0.2, currently enabled unconditionally
  • Sign
  • Duration::sign
  • PrimitiveDateTime::using_offset

---

Goals for v0.3:

• Remove all deprecated APIs
• Revamped parsing/formatting (Revamped parsing/formatting #236)
• un-constify is_leap_year and days_in_year for performance. On Rust ≥ 1.46, cfg_if_match and cfg_loop are stable, which allows re-enabling this without runtime performance loss. As a result, the only "loss" is un-constifying methods on older compilers.
• Place macros behind a feature flag.
• Change a number of methods to return Result, including all UtcOffset constructors.
• Rename try_from_* to just from_*.
• #![no_alloc] support
• Rename OffsetDateTime::timestamp and OffsetDateTime::timestamp_nanos to OffsetDateTime::unix_timestamp and OffsetDateTime::unix_timestamp_nanos respectively.
• Stabilize serde representations

Anything stricken on the above list is completed. Anything that was previously on the list but was removed was either done in 0.2 (if it's not a breaking change) or abandoned.

[jhpratt]

As a result of packing the Date struct into a single field, a number of structs have been reduced in size.

struct	bytes before	bytes now	reduction
Time	8	8	0%
Date	8	4	50%
UtcOffset	4	4	0%
PrimitiveDateTime	16	12	25%
OffsetDateTime	20	16	20%

A simple benchmark (not published) also shows a ~30% improvement in performance!

[SergioBenitez]

As a suggestion, I think it would be useful to have a release candidate for 0.3, when you feel it's ready, to work out any remaining issues in dependent crates. There are a few API nags in 0.2 that I'd love to see resolved in 0.3.

[jhpratt]

@SergioBenitez Definitely planning on a release candidate. Main thing I want to get done is the revamped formatting, as that's a major change.

Are there any APIs in particular you'd prefer changed that aren't addressed by the list above?

[jhpratt]

An update on no-alloc support:

Once revamped formatting/parsing is complete, I'll likely release an alpha for initial review.

While I'm designing the formatting/parsing with no-alloc support in mind, support for dynamic formatting strings seems unlikely, at least at first. The ability to have modifiers for the various specifiers would be quite inefficient (quadratic versus linear for checking in alloc environments). However, this doesn't preclude the possibility of statically known formats, namely those in the time::format mod or something procedurally generated via a macro).

I will investigate the possibility for no-alloc support for other operations. Given that error handling for constructors currently required Vec to be present (to store the year and month for whether a day is valid, for example), it seems unlikely no-alloc support will land in the initial 0.3.0 release.

I could use the arrayvec and/or heapless crates, but dependencies can't (currently) be disabled by enabling a feature flag (name alloc).

[SergioBenitez]

@jhpratt I'm not sure what's changed in 0.3 thus far, so these may be outdated, but, here are some notes:

1. Macros should be declarative, not procedural, where possible. At a first glance, this seems totally possible. This would remove the heavy syn, quote, proc-macro-hack, etc. dependencies.
2. Creating a constant date is very verbose. This is similar to OffsetDateTime::replace_time? #256. Why do I need to call assume_utc() and to_offset()? As far as I can see, there's no way to create an OffsetDateTime in one line. I should be able to do datetime!(2020-06-05 12:34pm GMT) or what-have-you.
3. Docs do a poor job of explaining the differences between PrimitiveDateTime and OffsetDateTime and how to move between the types. Why isn't there simply Date, Time, and DateTime, the latter of which could or couldn't have an offset? If the type difference is important, I'd still call it DateTime instead of PrimitiveDateTime; then OffsetDateTime, makes a bit more sense and establishes a more obvious hierarchy.
4. In general, the docs should describe common operations and why the types that exist do, and why we should care. Handling time correctly is hard which may lead to more complexity in a time handling library. When it does, you should explain this so we can appreciate it.
5. I'd encourage the use of modules. You currently have multiple structs whose names end with Error; these should all be in an error module without the Error suffix. Similarly, there are several free-standing functions that don't really seem to fit with the rest of the crate; should these be in a util module? In general, the catalog of top-level types and modules should already give me an idea of how the library is to be used.
6. I like this way of presenting features. It's easy to see which features exist.

[jhpratt]

1. I would love to be able to use macro_rules!. There are two things that can happen that would allow this to happen. Either would suffice.

   • Stabilization of const_if_match and const_panic. I'd have to check, but const_loop might also be necessary for some use cases. This would allow the macro to expand to Date::try_from_ymd($year, $month, $day).unwrap(), which would not compile if it was in a const context. I'm not sure on the semantics if it weren't in a const context — I presume it would continue to compile and panic at runtime, something that's undesirable.
     • const_if_match and const_loop are both well on their way to stabilization. const_panic is getting there, but it definitely won't land at the same time.
   • Re-interpretation of tokens inside of macro_rules! matchers. If this were possible, I'd be able to have one macro that verified a number is between 0 and 59, for example. A series of these could then be used to verify the full value.
     • I'm not aware of any plans for this to be allowed.

   Essentially, the reason it's a proc macro now is because it allows you to statically verify the validity of a value, allowing it to be used in const contexts.

2. When you call .assume_utc().to_offset(…), you are performing two logical operations. Once the aforementioned const features land on stable, .assume_offset() will be usable in const contexts. Going from a PrimitiveDateTime to an OffsetDateTime should require explicitly assuming an offset, even if it is UTC.

   I was planning on looking into a way to directly construct an OffsetDateTime. I'm not sure what form this would take, though. Macros would suffice for static values. I can look into whether a macro would be feasible, though I think it could work.

3. Funny you suggest merging them. I have actually looked into using typestate, but I believe the issue was the lack of ability to have const fn in traits. I can re-investigate this, though, as I may be misremembering things.

4. Any particular areas that could use improvement?

5. Modules is one thing I wanted to look into, but hadn't yet. Having a util module makes sense, at a minimum.

6. Can do! I knew the way I had it was a bit kludgey, but didn't have a better way.

[SergioBenitez]

I would love to be able to use macro_rules!. There are two things that can happen that would allow this to happen. Either would suffice.

I suppose I'm less concerned about the fact that it's a proc-macro and more concerned about the heavy-weight dependencies being pulled in. The macros are fairly straight-forward, so you should be able to accomplish the same thing without pulling in any dependencies whatsoever.

When you call .assume_utc().to_offset(…), you are performing two logical operations. Once the aforementioned const features land on stable, .assume_offset() will be usable in const contexts. Going from a PrimitiveDateTime to an OffsetDateTime should require explicitly assuming an offset, even if it is UTC.

I suppose I'm confused about calling assume_utc() on a PrimitiveDateTime. The "assume" part is odd; why isn't there simply a fn as_offset(..) -> OffsetDateTime? Presumably the entire point of PrimitiveDateTime is that there is no offset. Still, I'd really like a datetime!() macro where an offset can be specified to construct an OffsetDateTime directly.

Funny you suggest merging them. I have actually looked into using typestate, but I believe the issue was the lack of ability to have const fn in traits. I can re-investigate this, though, as I may be misremembering things.

I believe you're suggesting something like: DateTime<Raw> and DateTime<Offset>. This is easy enough to accomplish, but there's a trade-off here in terms of usability. I'm suggesting not disambiguating between a DateTime with and without an offset, or perhaps said differently, provide a default offset (of +/- 0) for a DateTime without an offset, and then allow it to be changed without it affecting the type. Thus, there would be a single DateTime, not two as it stands now. As mentioned before, this is only viable if the ability to disambiguate at the type-level isn't particularly important.

4. Any particular areas that could use improvement?

I've noted a few in my comment already. Each different date/time type needs to detail 1) why it exists, 2) how to create it, and 3) how it relates to the other types. There should also be a high-level overview of the library on common ways it's intended to be used.

[jhpratt]

I suppose I'm less concerned about the fact that it's a proc-macro and more concerned about the heavy-weight dependencies being pulled in. The macros are fairly straight-forward, so you should be able to accomplish the same thing without pulling in any dependencies whatsoever.

The original reason for pulling in the dependencies was proc-macro-hack. I can likely take a look at how that actually works and write the code myself (until the crate's MSRV allows for proc_macro_hygiene). The parsing isn't terribly difficult by itself (that was my original goal), though I do wish Rust provided something more than "literal" for parsing. Casting to a string and re-parsing just seems…stupid.

I suppose I'm confused about calling assume_utc() on a PrimitiveDateTime. The "assume" part is odd; why isn't there simply a fn as_offset(..) -> OffsetDateTime? Presumably the entire point of PrimitiveDateTime is that there is no offset. Still, I'd really like a datetime!() macro where an offset can be specified to construct an OffsetDateTime directly.

Something like PrimitiveDateTime::assume_offset? It's not const due to compiler limitations.

Also, turns out it was trivial to create a datetime! macro to construct a PrimitiveDateTime. It's now possible to do datetime!(2020-01-01 0:00).assume_offset(UtcOffset::UTC), though that does require the end user to add in the offset themselves. Expanding it to generate an OffsetDateTime would require additional code duplication in the macros crate. I'm not necessarily opposed to that, though it honestly isn't a priority.

I believe you're suggesting something like: DateTime<Raw> and DateTime<Offset>. This is easy enough to accomplish, but there's a trade-off here in terms of usability. I'm suggesting not disambiguating between a DateTime with and without an offset, or perhaps said differently, provide a default offset (of +/- 0) for a DateTime without an offset, and then allow it to be changed without it affecting the type. Thus, there would be a single DateTime, not two as it stands now. As mentioned before, this is only viable if the ability to disambiguate at the type-level isn't particularly important.

Yes, that's the sort of thing I was referring to. One major reason to keep the types separate is that a PrimitiveDateTime doesn't require the storage of an offset. I don't care for the idea of assuming a given offset (even UTC) when none is specified, as that can lead to surprising behavior, particularly while parsing, though I could likely be convinced.

With regard to renaming PrimitiveDateTime, @KodrAus expressed concern over this naming prior to the 0.2.0 release.

I've noted a few in my comment already. Each different date/time type needs to detail 1) why it exists, 2) how to create it, and 3) how it relates to the other types. There should also be a high-level overview of the library on common ways it's intended to be used.

👍

[Plecra]

In case it helps, here is a minimal implementation of proc-macro-hack using macro_rules. It doesn't implement support_nested or fake_call_site, neither of which should be needed here.