bdlt_datetimeinterval

Detailed Description

Outline

• Purpose
• Classes
• Description
  • The Representation of a Time Interval
  • Usage
    • Example 1: Basic bdlt::DatetimeInterval Usage

Purpose

Provide a representation of an interval of time.

Classes

• bdlt::DatetimeInterval: time interval with microsecond resolution

See also

Description

This component implements a time interval class, bdlt::DatetimeInterval, capable of representing the (signed) difference between two arbitrary points in time. The time interval represented by a bdlt::DatetimeInterval object has microsecond resolution.

The Representation of a Time Interval

A time interval has a value that is independent of its representation. Conceptually, the interval between two points in time could be described using a (signed) real number of seconds (or minutes, or hours, etc.). A bdlt::DatetimeInterval represents this value as six fields: days, hours, minutes, seconds, milliseconds, and microseconds. In the "canonical representation" of a time interval, the days field may have any 32-bit signed integer value, with the hours, minutes, seconds, milliseconds, and microseconds fields limited to the respective ranges [-23 .. 23], [-59 .. 59], [-59 .. 59], [-999 .. 999], and [-999 .. 999], with the additional constraint that the six fields are either all non-negative or all non-positive. When setting the value of a time interval via its six-field representation, any integer value may be used in any field, with the constraint that the resulting number of days be representable as a 32-bit signed integer. Similarly, the field values may be accessed in the canonical representation using the days, hours, minutes, seconds, milliseconds, and microseconds methods.

The primary accessors for this type are days and fractionalDayInMicroseconds. In combination, these two methods provide complete and succinct access to the value of a DatetimeInterval. Furthermore, the total value of the interval may be accessed in the respective field units via the totalDays, totalHours, totalMinutes, totalSeconds, totalMilliseconds, and totalMicroseconds methods. Note that, with the exception of totalMicroseconds (which returns an exact result), the other "total" accessors round toward 0. Also note that the totalMicroseconds accessor can fail for extreme DatetimeInterval values.

The following summarizes the canonical representation of the value of a bdlt::DatetimeInterval:

Field Name     Max. Valid Range     Auxiliary Conditions Limiting Validity
----------     ------------------   --------------------------------------
days           any 32-bit integer    all fields non-pos. or all non-neg.
hours          [ -23 ..  23]         all fields non-pos. or all non-neg.
minutes        [ -59 ..  59]         all fields non-pos. or all non-neg.
seconds        [ -59 ..  59]         all fields non-pos. or all non-neg.
milliseconds   [-999 .. 999]         all fields non-pos. or all non-neg.
microseconds   [-999 .. 999]         all fields non-pos. or all non-neg.

Usage

This section illustrates intended use of this component.

Example 1: Basic bdlt::DatetimeInterval Usage

This example demonstrates how to create and use a bdlt::DatetimeInterval object.

First, create an object i1 having the default value:

bdlt::DatetimeInterval i1;         assert(  0 == i1.days());
                                   assert(  0 == i1.hours());
                                   assert(  0 == i1.minutes());
                                   assert(  0 == i1.seconds());
                                   assert(  0 == i1.milliseconds());
                                   assert(  0 == i1.microseconds());

Then, set the value of i1 to -5 days, and then add 16 hours to that value:

i1.setTotalDays(-5);
i1.addHours(16);                   assert( -4 == i1.days());
                                   assert( -8 == i1.hours());
                                   assert(  0 == i1.minutes());
                                   assert(  0 == i1.seconds());
                                   assert(  0 == i1.milliseconds());
                                   assert(  0 == i1.microseconds());

Next, create i2 as a copy of i1:

bdlt::DatetimeInterval i2(i1);     assert( -4 == i2.days());
                                   assert( -8 == i2.hours());
                                   assert(  0 == i2.minutes());
                                   assert(  0 == i2.seconds());
                                   assert(  0 == i2.milliseconds());
                                   assert(  0 == i2.microseconds());

Then, add 2 days and 4 seconds to the value of i2 (in two steps), and confirm that i2 has a value that is greater than that of i1:

i2.addDays(2);
i2.addSeconds(4);                  assert( -2 == i2.days());
                                   assert( -7 == i2.hours());
                                   assert(-59 == i2.minutes());
                                   assert(-56 == i2.seconds());
                                   assert(  0 == i2.milliseconds());
                                   assert(  0 == i2.microseconds());
                                   assert(i2 > i1);

Next, add 2 days and 4 seconds to the value of i1 in one step by using the addInterval method, and confirm that i1 now has the same value as i2:

i1.addInterval(2, 0, 0, 4);        assert(i2 == i1);

Finally, write the value of i2 to stdout:

bsl::cout << i2 << bsl::endl;

The output operator produces the following format on stdout:

-2_07:59:56.000000