Document arithmetic operations on Instant

b3ea23d
Opened by bluss at 2022-05-15 17:16:06

Some questions that have come up about using Instants:

  1. What meaning does Instant -= Duration have?
  2. What are the preconditions on the instant and the duration, so that it does not panic or cause arithmetic overflow assertions? One user noticed that instant -= duration can trip this assertion (specifically on Windows).

  1. The zero point of Instant is not specified and could be any time before the start of the process. If you want to ensure that you do not get any underflow errors, then do not attempt to create an Instant representing a time before the process was spawned.

    Peter Atashian at 2017-10-24 03:02:56

  2. @rust-lang/libs: if you can articulate which aspects of this API are guaranteed, I'm happy to document them.

    Steve Klabnik at 2019-01-10 16:28:37

    1. What meaning does Instant -= Duration have?

    It causes Instant to have the value of an Instant created Duration time before its original value.

    1. What are the preconditions on the instant and the duration, so that it does not panic or cause arithmetic overflow assertions?

    Instant currently wraps the platform-specific monotonic time type, so the overflow bounds depend on the system. Some probably safe assumptions would be to not create Instants from before your process started or Instants more than a century or so in the future. I don't know what we specifically want to guarantee here though.

    Steven Fackler at 2019-01-10 16:41:26