Component bdlt_timeutil [Package bdlt]

Provide common non-primitive operations on bdlt::Time. More...

Namespaces
namespace	bdlt

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Converting from Seconds-from-Midnight to bdlt::Datetime
  • Usage
    • Example 1
    • Example 2

Purpose:

Provide common non-primitive operations on bdlt::Time.

Classes:

bdlt::TimeUtil

namespace for static functions operating on bdlt::Time

See also:

Component bdlt_time

Description:

This component provides non-primitive operations on bdlt::Time objects. In particular, the bdlt::TimeUtil namespace defined in this component provides conversions among bdlt::Time values and their corresponding non-negative integral values (e.g., convertFromHHMM, convertToHHMMSSmmm), and methods to validate such integral values (e.g., isValidHHMMSS) before passing them to the corresponding "convertFrom" method.

Converting from Seconds-from-Midnight to bdlt::Datetime:

Seconds-from-midnight is a date-time representation used in some financial applications. Seconds-from-midnight is a lossy representation (using heuristics to determine the date), and conversions for that representation are provided in a higher-level package that is not part of the BDE open-source libraries (see bsitzo_secondsfrommidnightutil).

Usage:

Following are examples illustrating basic use of this component.

Example 1:

First, we demonstrate how to use bdlt::TimeUtil to convert from an integer representation of time in "HHMMSSmmm" format to a bdlt::Time. Our first time will be around 3:45 pm.

  //      format: HHMMSSmmm
  int timeValue = 154502789;

  bdlt::Time result = bdlt::TimeUtil::convertFromHHMMSSmmm(timeValue);

  bsl::cout << result << bsl::endl;

The code above produces the following on stdout:

  15:45:02.789

Then, we demonstrate a different time, 3:32:24.832 am. Note that we do not lead the integer value with 0:

  //  format: HHMMSSmmm
  timeValue =  33224832;      // Do not start with leading '0' as that would
                              // make the value octal and incorrect.

  result = bdlt::TimeUtil::convertFromHHMMSSmmm(timeValue);

  bsl::cout << result << bsl::endl;

The code above produces the following on stdout:

  03:32:24.832

Now, we demonstrate how bdlt::TimeUtil provides methods that can be used to validate integral time values before passing them to the various "convert" methods. For example:

  assert( bdlt::TimeUtil::isValidHHMMSSmmm(timeValue));

Finally, we demonstrate catching an invalid time value, 12:61:02.789 pm:

  //         format: HHMMSSmmm
  int badTimeValue = 126102789;

  assert(!bdlt::TimeUtil::isValidHHMMSSmmm(badTimeValue));

Example 2:

The following snippet of code demonstrates how to use bdlt::TimeUtil to convert from a bdlt::Time to an integer representation of time in "HHMM", "HHMMSS", and "HHMMSSmmm" formats:

  bdlt::Time time(12, 45, 2, 789);
  int        timeHHMM      = bdlt::TimeUtil::convertToHHMM(time);
  int        timeHHMMSS    = bdlt::TimeUtil::convertToHHMMSS(time);
  int        timeHHMMSSmmm = bdlt::TimeUtil::convertToHHMMSSmmm(time);

  bsl::cout << "Time in HHMM:      " << timeHHMM      << bsl::endl;
  bsl::cout << "Time in HHMMSS:    " << timeHHMMSS    << bsl::endl;
  bsl::cout << "Time in HHMMSSmmm: " << timeHHMMSSmmm << bsl::endl;

The code above produces the following on stdout:

  Time in HHMM:      1245
  Time in HHMMSS:    124502
  Time in HHMMSSmmm: 124502789

Note that the millisecond and/or second fields of bdlt::Time are ignored depending on the conversion method that is called.