Stabilize duration_checked_float

[lopopolo]

Stabilization Report

This stabilization report is for a stabilization of duration_checked_float, tracking issue: #83400.

Implementation History

• Add functions Duration::try_from_secs_{f32, f64} #82179
• Improve Duration::try_from_secs_f32/64 accuracy by directly processing exponent and mantissa #90247
• Use rounding in float to Duration conversion methods #96051
• Changed error type to FromFloatSecsError in Improve Duration::try_from_secs_f32/64 accuracy by directly processing exponent and mantissa #90247
• Use rounding in float to Duration conversion methods #96051 changes the rounding mode to round-to-nearest instead of truncate.

API Summary

This stabilization report proposes the following API to be stabilized in core, along with their re-exports in std:

// core::time

impl Duration {
    pub const fn try_from_secs_f32(secs: f32) -> Result<Duration, TryFromFloatSecsError>;
    pub const fn try_from_secs_f64(secs: f64) -> Result<Duration, TryFromFloatSecsError>;
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TryFromFloatSecsError { ... }

impl core::fmt::Display for TryFromFloatSecsError { ... }
impl core::error::Error for TryFromFloatSecsError { ... }

These functions are made const unstable under duration_consts_float, tracking issue #72440.

There is an open question in the tracking issue around what the error type should be called which I was hoping to resolve in the context of an FCP.

In this stabilization PR, I have altered the name of the error type to TryFromFloatSecsError. In my opinion, the error type shares the name of the method (adjusted to accommodate both types of floats), which is consistent with other error types in core, alloc and std like TryReserveError and TryFromIntError.

Experience Report

Code such as this is ready to be converted to a checked API to ensure it is panic free:

impl Time {
    pub fn checked_add_f64(&self, seconds: f64) -> Result<Self, TimeError> {
        // Fail safely during `f64` conversion to duration
        if seconds.is_nan() || seconds.is_infinite() {
            return Err(TzOutOfRangeError::new().into());
        }

        if seconds.is_sign_positive() {
            self.checked_add(Duration::from_secs_f64(seconds))
        } else {
            self.checked_sub(Duration::from_secs_f64(-seconds))
        }
    }
}

See: artichoke/artichoke#2194.

@rustbot label +T-libs-api -T-libs

cc @mbartlett21

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[rust-highfive]

r? @scottmcm

(rust-highfive has picked a reviewer for you, use r? to override)

[mbartlett21]

@lopopolo

Thanks for continuing along with this. The error changes lgtm.

[scottmcm]

Since it looks like this hasn't had an FCP,
@rustbot label +needs-fcp
r? @joshtriplett

[bors]

☔ The latest upstream changes (presumably #102051) made this pull request unmergeable. Please resolve the merge conflicts.

[lopopolo]

Pushed a rebase due to the std::error::Error changes being shuffled around with the new nightly.

[joshtriplett]

@rfcbot merge

[rfcbot]

Team member @joshtriplett 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
• @yaahc

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. 🔔

[bors]

☔ The latest upstream changes (presumably #103069) made this pull request unmergeable. Please resolve the merge conflicts.

[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.

This will be merged soon.

[lopopolo]

Pushed a rebase to address the merge conflict from #103059. It looks like the FCP is complete, so once CI passes I think this is ready for a stamp and merge.

[lopopolo]

@joshtriplett I believe this is ready to be merged since the FCP has concluded.

[lopopolo]

Did this miss the beta cutoff? 😢

[lopopolo]

@Amanieu @BurntSushi @dtolnay @joshtriplett @m-ou-se @yaahc can one of you r+ this PR to merge it? This FCP successfully completed 8 days ago.

[dtolnay]

@bors r+

[bors]

📌 Commit 95040a7 has been approved by dtolnay

It is now in the queue for this repository.