Provide a representation of an interval of time.
More...
Namespaces |
| namespace | bdlt |
Detailed Description
- Outline
-
-
- Purpose:
- Provide a representation of an interval of time.
-
- Classes:
-
- 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: Then, set the value of i1 to -5 days, and then add 16 hours to that value: 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());
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);
i1 in one step by using the addInterval method, and confirm that i1 now has the same value as i2: Finally, write the value of i2 to stdout: bsl::cout << i2 << bsl::endl;
stdout:
