-
Notifications
You must be signed in to change notification settings - Fork 12.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Suggest less bug-prone construction of Duration in docs #119242
Conversation
(rustbot has picked a reviewer for you, use r? to override) |
You can also split the u128 with a division and modulo and feed that to |
That's exactly what as_secs() and subsecs_nanos() do, just with the possibility of getting it wrong, and also with suspicious casts. That's why I suggest as_secs() and subsecs_nanos(). :) |
This is certainly the right approach for if you need to round-trip Duration through numeric types. It'd help to clarify with something like "and you cannot copy the Duration itself". |
7f8264b
to
119eedf
Compare
I included your suggested rewording and rebased to current master. |
I wonder if this would be better phrased as an example? So you can show that |
My main point is to make sure that readers informed that and why the obvious approach is wrong. Playing it down as an example does not do it justice. However, I could certainly add an example. What does @joshtriplett think? |
Changes since last push:
|
119eedf
to
27ba1c1
Compare
@bors r+ This seems reasonable to me. Separate from this, it might make sense to add a |
@bors rollup |
…iaskrgr Rollup of 10 pull requests Successful merges: - rust-lang#117740 (Add some links and minor explanatory comments to `std::fmt`) - rust-lang#118307 (Remove an unneeded helper from the tuple library code) - rust-lang#119242 (Suggest less bug-prone construction of Duration in docs) - rust-lang#119449 (Fix `clippy::correctness` in the library) - rust-lang#120307 (core: add Duration constructors) - rust-lang#120459 (Document various I/O descriptor/handle conversions) - rust-lang#120729 (Update mdbook to 0.4.37) - rust-lang#120763 (Suggest pattern tests when modifying exhaustiveness) - rust-lang#120906 (Remove myself from some review rotations) - rust-lang#120916 (Subtree update of ` rust-analyzer`) r? `@ghost` `@rustbot` modify labels: rollup
|
…iaskrgr Rollup of 10 pull requests Successful merges: - rust-lang#117740 (Add some links and minor explanatory comments to `std::fmt`) - rust-lang#118307 (Remove an unneeded helper from the tuple library code) - rust-lang#119242 (Suggest less bug-prone construction of Duration in docs) - rust-lang#119449 (Fix `clippy::correctness` in the library) - rust-lang#120307 (core: add Duration constructors) - rust-lang#120459 (Document various I/O descriptor/handle conversions) - rust-lang#120729 (Update mdbook to 0.4.37) - rust-lang#120763 (Suggest pattern tests when modifying exhaustiveness) - rust-lang#120906 (Remove myself from some review rotations) - rust-lang#120916 (Subtree update of ` rust-analyzer`) r? `@ghost` `@rustbot` modify labels: rollup
Rollup merge of rust-lang#119242 - BenWiederhake:dev-from-nanos, r=joshtriplett Suggest less bug-prone construction of Duration in docs std::time::Duration has a well-known quirk: Duration::as_nanos() returns u128 [1], but Duration::from_nanos() takes u64 [2]. So these methods cannot easily roundtrip [3]. It is not possible to simply accept u128 in from_nanos [4], because it requires breaking other API [5]. It seems to me that callers have basically only two options: 1. `Duration::from_nanos(d.as_nanos() as u64)`, which is the "obvious" and buggy approach. 2. `Duration::new(d.as_secs(), d.subsecs_nanos())`, which only becomes apparent after reading and digesting the entire Duration struct documentation. I suggest that the documentation of `from_nanos` is changed to make option 2 more easily discoverable. There are two major usecases for this: - "Weird math" operations that should not be supported directly by `Duration`, like squaring. - "Disconnected roundtrips", where the u128 value is passed through various other stack frames, and perhaps reconstructed into a Duration on a different machine. In both cases, it seems like a good idea to not tempt people into thinking "Eh, u64 is good enough, what could possibly go wrong!". That's why I want to add a note that points out the similarly-easy and *safe* way to reconstruct a Duration. [1] https://doc.rust-lang.org/stable/std/time/struct.Duration.html#method.as_nanos [2] https://doc.rust-lang.org/stable/std/time/struct.Duration.html#method.from_nanos [3] https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=fa6bab2b6b72f20c14b5243610ea1dde [4] rust-lang#103332 [5] rust-lang#51107 (comment)
std::time::Duration has a well-known quirk: Duration::as_nanos() returns u128 [1], but Duration::from_nanos() takes u64 [2]. So these methods cannot easily roundtrip [3]. It is not possible to simply accept u128 in from_nanos [4], because it requires breaking other API [5].
It seems to me that callers have basically only two options:
Duration::from_nanos(d.as_nanos() as u64)
, which is the "obvious" and buggy approach.Duration::new(d.as_secs(), d.subsecs_nanos())
, which only becomes apparent after reading and digesting the entire Duration struct documentation.I suggest that the documentation of
from_nanos
is changed to make option 2 more easily discoverable.There are two major usecases for this:
Duration
, like squaring.In both cases, it seems like a good idea to not tempt people into thinking "Eh, u64 is good enough, what could possibly go wrong!". That's why I want to add a note that points out the similarly-easy and safe way to reconstruct a Duration.
[1] https://doc.rust-lang.org/stable/std/time/struct.Duration.html#method.as_nanos
[2] https://doc.rust-lang.org/stable/std/time/struct.Duration.html#method.from_nanos
[3] https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=fa6bab2b6b72f20c14b5243610ea1dde
[4] #103332
[5] #51107 (comment)