Component bsls_timeinterval [Package bsls]

Provide a representation of a time interval. More...

Namespaces
namespace	bsls

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Representation
  • User-Defined Literals
  • Usage
    • Example 1: Creating and Modifying a bsls::TimeInterval

Purpose:

Provide a representation of a time interval.

Classes:

bsls::TimeInterval

time interval with nanosecond resolution

See also:

Component bdlt_time, Component bdlt_datetimeinterval

Description:

This component provides a value-semantic type, bsls::TimeInterval, that is capable of representing a signed time interval with nanosecond resolution.

Representation:

A time interval has a value that is independent of its representation. Conceptually, a time interval may be thought of as a signed, arbitrary-precision floating-point number denominated in seconds (or in days, or in fortnights, if one prefers). A bsls::TimeInterval represents this value as two fields: seconds and nanoseconds. In the "canonical representation" of a time interval, the seconds field may have any 64-bit signed integer value, with the nanoseconds field limited to the range [ -999,999,999..999,999,999 ], and with the additional constraint that the two fields are either both non-negative or both non-positive. When setting the value of a time interval via its two-field representation, any integer value may be used in either field, with the constraint that the resulting number of seconds be representable as a 64-bit signed integer. Similarly, the two field values may be accessed in the canonical representation using the seconds and nanoseconds methods.

Binary arithmetic and relational operators taking two bsls::TimeInterval objects, or a bsls::TimeInterval object and a double, are provided. A double operand, representing a real number of seconds, is first converted to a bsls::TimeInterval object before performing the operation. Under such circumstances, the fractional part of the double, if any, is rounded to the nearest whole number of nanoseconds.

User-Defined Literals:

The user-defined literal operator"" _h, operator"" _min, operator"" _s, operator"" _ms, operator"" _us and operator"" _ns are declared for the TimeInterval. These suffixes can be applied to integer literals and allow to create an object, representing the specified number of hours, minutes, seconds, milliseconds, microseconds or nanoseconds respectively:

  using namespace bsls::TimeIntervalLiterals;

  bsls::TimeInterval i0 = 10_h;
  assert(36000   == i0.seconds()    );
  assert(0       == i0.nanoseconds());

  bsls::TimeInterval i1 = 10001_ms;
  assert(10      == i1.seconds()    );
  assert(1000000 == i1.nanoseconds());

  bsls::TimeInterval i2 = 100_ns;
  assert(0       == i2.seconds()    );
  assert(100     == i2.nanoseconds());

The operators providing literals are available in the BloombergLP::bsls::literals::TimeIntervalLiterals namespace (where literals and TimeIntervalLiterals are both inline namespaces). Because of inline namespaces, there are several viable options for a using declaration, but we recommend using namespace bsls::TimeIntervalLiterals, which minimizes the scope of the using declaration.

Note that user defined literals can be used only if the compiler supports the C++11 standard.

Usage:

This section illustrates intended use of this component.

Example 1: Creating and Modifying a bsls::TimeInterval:

The following example demonstrates how to create and manipulate a bsls::TimeInterval object.

First, we default construct a TimeInterval object, interval:

  bsls::TimeInterval interval;

  assert(0 == interval.seconds());
  assert(0 == interval.nanoseconds());

Next, we set the value of interval to 1 second and 10 nanoseconds (a time interval of 1000000010 nanoseconds):

  interval.setInterval(1, 10);

  assert( 1 == interval.seconds());
  assert(10 == interval.nanoseconds());

Then, we add 3 seconds to interval:

  interval.addInterval(3, 0);

  assert( 4 == interval.seconds());
  assert(10 == interval.nanoseconds());

Next, we create a copy of interval, intervalPrime:

  bsls::TimeInterval intervalPrime(interval);

  assert(intervalPrime == interval);

Finally, we assign 3.14 seconds to intervalPrime, and then add 2.73 seconds more:

  intervalPrime =  3.14;
  intervalPrime += 2.73;

  assert(        5 == intervalPrime.seconds());
  assert(870000000 == intervalPrime.nanoseconds());