Tracking Issue for Duration saturating operations

[marmeladema]

This is a tracking issue for Duration saturating operations.
The feature gate for the issue is #![feature(duration_saturating_ops)].

        impl Duration {
            pub const fn saturating_add(self, rhs: Duration) -> Duration {}
            pub const fn saturating_sub(self, rhs: Duration) -> Duration {}
            pub const fn saturating_mul(self, rhs: u32) -> Duration {}
        }

Steps

• Implement the proposal: Add saturating methods for Duration #76114
• FCP
• Stabilization PR: Stabilize feature duration_saturating_ops #84090

Unresolved Questions

• Do we want associated constants similar to the ones that already exist for integer types or associated methods? (ie: Duration::MIN or Duration::min()?
• Should Duration::MIN be replaced by Duration::zero()? They are currently equivalent but one can image a future where Duration is able to hold negative duration and thus making MIN different from zero().

[matklad]

Just needed saturating_sub when dealing with time intervals.

Also, unresloved questions seem to be from another tracking issue?

[m-ou-se]

@rfcbot merge

[rfcbot]

Team member @m-ou-se has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se
• @sfackler

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

The RFC will be merged soon.

[marmeladema]

I am very happy to see this stabilized. One thing I wanted to discuss is the documentation: it currently mentions two associated constants:

• https://doc.rust-lang.org/nightly/std/time/struct.Duration.html#associatedconstant.ZERO
• https://doc.rust-lang.org/nightly/std/time/struct.Duration.html#associatedconstant.MAX

But both are currently unstable. Should they be stabilized at the same time? Or should the documentation updated? It seems a bit weird that the documentation for stable methods is mentioning unstable features and therefore the code examples cannot be executed and verified on stable. This is really a newbie question, I don't know what is the correct approach here. I am pretty sure such circumstances have happened before?

Also, once that question is resolved, I would be very glad to do the stabilization PR. It's my first tracking issue and it would kind of be a personal accomplishment 👍

[m-ou-se]

ZERO is being stabilized at the same time: #73544 (comment)

MAX still needs to be stabilized. Here it's suggested that that constant should probably not be part of the same tracking issue as the other constants there (SECOND, etc.). Feel free to send a PR that stabilizes just MAX, then we can do an FCP on that PR and we'll remove it from that tracking issue.

Also, once that question is resolved, I would be very glad to do the stabilization PR.

Feel free to make that PR without waiting for MAX. In this specific case I don't think it's a problem if this gets stabilized while the docs still refer to something unstable. MAX is pretty clear and uncontroversial. Even if it's unstable, it's still the best way we have to refer to the maximum value of a Duration. (And it'll probably be stable anyway in ~two weeks.)