Skip to content

Docs for Duration are lacking #39949

Closed
Closed
@ghost

Description

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?

Activity

steveklabnik

steveklabnik commented on Feb 19, 2017

@steveklabnik
Member

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

ranma42

ranma42 commented on Feb 19, 2017

@ranma42
Contributor

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.

ghost

ghost commented on Feb 19, 2017

@ghost

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

ranma42 commented on Feb 19, 2017

@ranma42
Contributor

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

sfackler commented on Feb 19, 2017

@sfackler
Member

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.

added
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools
and removed
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools
on Mar 10, 2017
steveklabnik

steveklabnik commented on Mar 15, 2017

@steveklabnik
Member

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

added
T-libs-apiRelevant to the library API team, which will review and decide on the PR/issue.
and removed on Mar 24, 2017

12 remaining items

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsP-mediumMedium priorityT-libs-apiRelevant to the library API team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @steveklabnik@dhardy@frewsxcv@sfackler@ranma42

        Issue actions

          Docs for Duration are lacking · Issue #39949 · rust-lang/rust