3.5 Duration

The Duration class is used to specify time intervals with nanosecond precision. Thanks to a 64 bit second size, durations up to 580 billion years can be specified with this class. Both positive and negative durations can be specified with 64 bit second size and nanosecond precision. The Duration class comes with various operators allowing to compare, add, and substract durations. Adding and substracting is done with saturation tests to avoid computation troubles known with native integers. For example adding one second to a duration with maximum second and nanosecond values will not wrap the number of seconds to zero, but keep it at maximum. The same happens for substractions in the minimum area (maximum negative values). The stored amount of nanoseconds is guaranteed to be in the range [0...999'999'999] (resp. [-999'999'999...0[ for negative durations). This range checking is also done in constructors, where if the given amount of nanoseconds is larger than 999’999’999, the number of seconds is increased accordingly, as far as this is possible without saturation, else the saturated values are stored.

Synopsis

Description

˜Duration ()

Destroys this duration. Releases all resources used by this duration.

Duration ()

Constructs this duration as a zero duration. Both the amount of seconds and nanoseconds are set to zero, and the sign is positive.

Duration (uint64 sec, uint32 nsec)

Constructs this duration from the given amount of seconds and nanoseconds.
If the given nsec is greater than the maximum 999’999’999, the number of stored seconds is increased by nsec / 1’000’000’000 (integer division), and nsec % 1’000’000’000 (modulo) is stored as the number of nanoseconds.

Duration (const Duration& duration)

Constructs this duration from the given duration. Data stored in duration are copied into this duration.

Duration operator - ()

Builds the negative duration of this and returns it. This duration remains unchanged.

Duration& operator = (const Duration& duration)

Assigns the given duration to this. Data stored in duration are copied into this duration.

bool operator == (const Duration& duration) const

Compares this left hande side duration with the right hand duration and returns true if both are equal, false if not.

bool operator != (const Duration& duration) const

Compares this left hande side duration with the right hand duration and returns true if they are not equal, false if they are.

bool operator < (const Duration& duration) const

Compares this left hand side duration with the right hand duration and returns true if this is smaller than duration, false if not.

bool operator > (const Duration& duration) const

Compares this left hand side duration with the right hand duration and returns true if this is larger than duration, false if not.

bool operator <= (const Duration& duration) const

Compares this left hand side duration with the right hand duration and returns true if this is smaller or equal than duration, false if not.

bool operator >= (const Duration& duration) const

Compares this left hand side duration with the right hand duration and returns true if this is larger or equal than duration, false if not.

Duration& operator += (const Duration& duration)

Adds the right hand side duration to this duration.
If the sum would exceed the storage capacity of this duration, this is saturated to the maximum amount of seconds and nanoseconds (Duration(0xffffffffffffffff, 999999999)).

Duration& operator -= (const Duration& duration)

Substracts the right hand side duration from this duration.
If the difference would exceed the storage capacity of this duration, this is saturated to the minimum amount of seconds and nanoseconds (-Duration(0xffffffffffffffff, 999999999)).

uint64 sec () const
uint64 second () const

Returns the unsigned number of seconds stored in this duration.

uint32 nsec () const
uint32 nanosec () const
uint32 nanosecond () const

Returns the unsigned number of nanoseconds stored in this duration. The returned value is guaranteed to be in the range [0...999'999'999].

Duration operator + (const Duration& dl, const Duration& dr)

Adds the left hand side dl and the right hand side dr durations and returns the resulting duration.
If the sum would exceed the storage capacity of a duration, the returned duration is saturated to the maximum amount of seconds and nanoseconds (Duration(0xffffffffffffffff, 999999999)).

Duration operator - (const Duration& dl, const Duration& dr)

Substracs the right hand side dr from the left hand side dl durations and returns the resulting duration.
If the difference would exceed the storage capacity of a duration, the returned duration is saturated to the minimum amount of seconds and nanoseconds (-Duration(0xffffffffffffffff, 999999999)).

Example

1. Test if a duration is negative:
   
   1  Duration duration;
   2  
   3  // Some computations with 'duration'
   4  if (duration < Duration(0, 0))
   5    // Handle negative duration
   6  else
   7    // Handle positive duration
2. Construct a negative duration:
   
   1  Duration duration(-Duration(5, 987));

   The duration stores -5.000000987 seconds (minus 5 seconds and 987 nanoseconds).