Docs for Duration are lacking

The most common use of Duration for me is benchmarking, and it's always a very unpleasant experience. This is what I typically write:

let now = Instant::now();
// Do something...
let elapsed = now.elapsed();
println!("{:?}", elapsed);

Output: Duration { secs: 1, nanos: 59219906 }
Wait, how much time has elapsed? That's terribly unreadable... :(

The docs for Duration are not very helpful either. When you first see it, Duration is pretty confusing, mostly because of the as_secs/subsec_nanos split.

Then I take a look at the docs for Instant, but the examples show how to print the seconds part only.

Anyways, all I want to do is just print how much time has elapsed without squinting to connect secs and nanos together. Finally, I arrive at this horrible solution:

println!("seconds: {:.3}", elapsed.as_secs() as f64 + elapsed.subsec_nanos() as f64 / 1e9);

Three ways of fixing this come to my mind:

1. Add a function to Duration that converts it to a (lossy) f64 format.
2. Add examples to the docs for Instant and Duration that demonstrate how to print the duration time in a human readable form (e.g. total seconds with precision to 3 decimals).
3. Change the Debug formatting for Duration and print it like this: Duration(secs.nanos: 1.059219906) (note the leading zero). Or maybe even Duration { secs: 1, nanos: 059219906 } (again, the leading zero).

What do you think?

[steveklabnik]

This seems like just as much a question for @rust-lang/libs as it does @rust-lang/docs

[ranma42]

See also #38475 (another call for solution 1).

As an alternative to 3, there were some attempts at implementing Display for Duration (see #29146), but they were rejected because is seems hard to have "one true way" to display Duration values across a wide range of values.

How about this non-lossy function?

fn as_nanos(&self) -> u128 {
    self.secs as u128 * 1_000_000_000 + self.nanos as u128
}

Printing:

println!("{:.3}", duration.as_nanos() as f64 / 1e9);

[ranma42]

The to_nanos function was discussed here #35868.

It looks like several Duration-related items were blocked because of the lack of i128 (see also #32515). Maybe this is a good time to discuss them again? Some experience has probably been gathered through the https://github.com/sfackler/rust-time2 crate.

[sfackler]

They were not blocked on i128, they're blocked on someone writing up a proposal for what specifically to do. i128 returns are on option.

[steveklabnik]

Docs team triage: adding p-medium for option 2.