Component bdlt_time [Package bdlt]

Provide a value-semantic type representing time-of-day. More...

Namespaces
namespace	bdlt

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • ISO Standard Text Representation
  • Usage
    • Example 1: Basic bdlt::Time Usage

Purpose:

Provide a value-semantic type representing time-of-day.

Classes:

bdlt::Time

time-of-day type (with microsecond resolution)

Description:

This component implements a value-semantic time class, bdlt::Time, that can represent the time of day to a resolution of one microsecond (using a 24-hour clock). Valid time values range from 00:00:00.000000 (i.e., midnight) through 23:59:59.999999 (i.e., one microsecond before midnight). A time value can be specified via five separate integer attribute values denoting hours [0 .. 23], minutes [0 .. 59], seconds [0 .. 59], milliseconds [0 .. 999], and microseconds [0 .. 999]. In addition, the bdlt::Time type has one more valid value, 24:00:00.000000, that can be set explicitly and accessed. The value 24:00:00.000000 behaves, in most cases, as if it were the value 00:00:00.000000; however, for all relational comparison operators, 24:00:00.000000 is not a valid argument and, therefore, would result in undefined behavior. Each of the add manipulators, along with modifying the value of the object, return the (signed) number of times that the 23:59:59.999999 - 00:00:00.000000 boundary was crossed in performing the addition.

ISO Standard Text Representation:

A common standard text representation of a date and time value is described by ISO 8601. BDE provides the bdlt_iso8601util component for conversion to and from the standard ISO8601 format.

Usage:

This section illustrates intended use of this component.

Example 1: Basic bdlt::Time Usage:

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

First, create an object t1 having the default value, and then verify that it represents the value 24:00:00.000000:

  bdlt::Time t1;               assert(24 == t1.hour());
                               assert( 0 == t1.minute());
                               assert( 0 == t1.second());
                               assert( 0 == t1.millisecond());
                               assert( 0 == t1.microsecond());

Then, set t1 to the value 2:34pm (14:34:00.000000):

  t1.setTime(14, 34);          assert(14 == t1.hour());
                               assert(34 == t1.minute());
                               assert( 0 == t1.second());
                               assert( 0 == t1.millisecond());
                               assert( 0 == t1.microsecond());

Next, use setTimeIfValid to attempt to assign the invalid value 24:15 to t1, then verify the method returns an error status and the value of t1 is unmodified:

  int ret = t1.setTimeIfValid(24, 15);
                               assert( 0 != ret);          // 24:15 is not
                                                           // valid

                               assert(14 == t1.hour());    // no effect
                               assert(34 == t1.minute());  // on the
                               assert( 0 == t1.second());  // object
                               assert( 0 == t1.millisecond());
                               assert( 0 == t1.microsecond());

Then, create t2 as a copy of t1:

  bdlt::Time t2(t1);            assert(t1 == t2);

Next, add 5 minutes and 7 seconds to the value of t2 (in two steps), and confirm the value of t2:

  t2.addMinutes(5);
  t2.addSeconds(7);
                               assert(14 == t2.hour());
                               assert(39 == t2.minute());
                               assert( 7 == t2.second());
                               assert( 0 == t2.millisecond());
                               assert( 0 == t2.microsecond());

Then, subtract t1 from t2 to yield a bdlt::DatetimeInterval dt representing the time-interval between those two times, and verify the value of dt is 5 minutes and 7 seconds (or 307 seconds):

  bdlt::DatetimeInterval dt = t2 - t1;
                               assert(307 == dt.totalSeconds());

Finally, stream the value of t2 to stdout:

  bsl::cout << t2 << bsl::endl;

The streaming operator produces the following output on stdout:

  14:39:07.000000