bdlt_timeunitratio

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Breaking a Time Interval Into Component Parts

Purpose

Provide constants characterizing ratios between common time units.

Classes

• bdlt::TimeUnitRatio: namespace for common time-unit-ratio constants

Description

This component provides a utility struct, bdlt::TimeUnitRatio, that defines a namespace for constants that characterize the ratios between commonly used time units. Ratios are provided for combinations of all time units from a nanosecond up through a day.

Each constant defined in this namespace has at least two forms, a full form and an abbreviated form following the patterns:

bdlt::TimeUnitRatio::k_SMALLUNITS_PER_LARGEUNIT
bdlt::TimeUnitRatio::k_SU_PER_LU

Where SMALLUNIT and LARGEUNIT are members of the following group:

NANOSECOND
MICROSECOND
MILLISECOND
SECOND
MINUTE
HOUR
DAY

and SU and LU are abbreviations in the following group:

NS // abbreviation for `NANOSECOND`
US // abbreviation for `MICROSECOND`
MS // abbreviation for `MILLISECOND`
S  // abbreviation for `SECOND`
M  // abbreviation for `MINUTE`
H  // abbreviation for `HOUR`
D  // abbreviation for `DAY`

Note that SMALLUNIT (SU) is always a smaller unit than LARGEUNIT (LU). Thus, the (whole) number of microseconds in an hour is characterized by the constants:

bdlt::TimeUnitRatio::k_MICROSECONDS_PER_HOUR
bdlt::TimeUnitRatio::k_US_PER_H

Additionally, ratios that can be represented by a 32-bit integer also have two corresponding 32-bit constants, having the same names as the constants described above, but incorporate a _32 suffix. Thus, the number of milliseconds per minute is characterized by four constants:

bdlt::TimeUnitRatio::k_MILLISECONDS_PER_MINUTE
bdlt::TimeUnitRatio::k_MS_PER_M
bdlt::TimeUnitRatio::k_MILLISECONDS_PER_MINUTE_32
bdlt::TimeUnitRatio::k_MS_PER_M_32

By providing both 64- and 32-bit versions of the constants, this component allows the programmer to minimize the use of casts in time unit calculations.

Usage

This section illustrates intended use of this component.

Example 1: Breaking a Time Interval Into Component Parts

Components that deal with time often need to convert between various units. Each component that needs to perform such conversions could derive the constants needed locally, but doing so would result in an inconsistent vocabulary across components, and multiple opportunities for bugs. bdlt::TimeUnitRatio achieves the desired consistency and avoids bugs by providing a single location for the constants used in such conversions.

Suppose we have a time interval described as an integral number of nanoseconds, and we need to break it down into its constituent second, millisecond, microsecond, and nanosecond parts.

First, we define a variable representing the number of nanoseconds that have elapsed since a particular event:

bsls::Types::Int64 interval = 62003004005;  // nanoseconds since event

Then, we extract the minutes part from the total, using the constant bdlt::TimeUnitRatio::k_NS_PER_M:

bsls::Types::Int64 minutesPart =
                                interval / bdlt::TimeUnitRatio::k_NS_PER_M;

Next, we calculate the remaining nanoseconds using the same constant:

bsls::Types::Int64 remainder = interval % bdlt::TimeUnitRatio::k_NS_PER_M;

Then, we extract the seconds part from the remainder, using the constant bdlt::TimeUnitRatio::k_NS_PER_S:

bsls::Types::Int64 secondsPart =
                               remainder / bdlt::TimeUnitRatio::k_NS_PER_S;

Next, we calculate the remaining nanoseconds using the same constant:

remainder %= bdlt::TimeUnitRatio::k_NS_PER_S;

Then, we extract the milliseconds part from the remainder, using the constant bdlt::TimeUnitRatio::k_NS_PER_MS:

bsls::Types::Int64 millisecondsPart =
                              remainder / bdlt::TimeUnitRatio::k_NS_PER_MS;

Next, we calculate the remaining nanoseconds using the same constant:

remainder %= bdlt::TimeUnitRatio::k_NS_PER_MS;

Then, we extract the microseconds part from the remainder, using the constant bdlt::TimeUnitRatio::k_NS_PER_US:

bsls::Types::Int64 microsecondsPart =
                              remainder / bdlt::TimeUnitRatio::k_NS_PER_US;

Next, we calculate the remaining nanoseconds using the same constant:

remainder %= bdlt::TimeUnitRatio::k_NS_PER_US;

Now, we extract the nanoseconds part, which is exactly the remainder we already have:

bsls::Types::Int64 nanosecondsPart = remainder;

Finally, we confirm that the parts we have extracted all have the correct values:

assert(1 == minutesPart);
assert(2 == secondsPart);
assert(3 == millisecondsPart);
assert(4 == microsecondsPart);
assert(5 == nanosecondsPart);

Note that in practice, the number of nanoseconds since the event would be provided by some system utility, and not a constant as was shown here for purposes of exposition.