bdlt_timeunitratio.h

Go to the documentation of this file.

/// @file bdlt_timeunitratio.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bdlt_timeunitratio.h                                               -*-C++-*-
#ifndef INCLUDED_BDLT_TIMEUNITRATIO
#define INCLUDED_BDLT_TIMEUNITRATIO
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bdlt_timeunitratio bdlt_timeunitratio
/// @brief  Provide constants characterizing ratios between common time units.
/// @addtogroup bdl
/// @{
/// @addtogroup bdlt
/// @{
/// @addtogroup bdlt_timeunitratio
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bdlt_timeunitratio-purpose"> Purpose</a>
/// * <a href="#bdlt_timeunitratio-classes"> Classes </a>
/// * <a href="#bdlt_timeunitratio-description"> Description </a>
///   * <a href="#bdlt_timeunitratio-usage"> Usage </a>
///     * <a href="#bdlt_timeunitratio-example-1-breaking-a-time-interval-into-component-parts"> Example 1: Breaking a Time Interval Into Component Parts </a>
///
/// # Purpose {#bdlt_timeunitratio-purpose}
/// Provide constants characterizing ratios between common time units.
///
/// # Classes {#bdlt_timeunitratio-classes}
///
/// -  bdlt::TimeUnitRatio: namespace for common time-unit-ratio constants
///
/// # Description {#bdlt_timeunitratio-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:
/// @code
/// bdlt::TimeUnitRatio::k_SMALLUNITS_PER_LARGEUNIT
/// bdlt::TimeUnitRatio::k_SU_PER_LU
/// @endcode
/// Where `SMALLUNIT` and `LARGEUNIT` are members of the following group:
/// @code
/// NANOSECOND
/// MICROSECOND
/// MILLISECOND
/// SECOND
/// MINUTE
/// HOUR
/// DAY
/// @endcode
/// and `SU` and `LU` are abbreviations in the following group:
/// @code
/// 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`
/// @endcode
/// 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:
/// @code
/// bdlt::TimeUnitRatio::k_MICROSECONDS_PER_HOUR
/// bdlt::TimeUnitRatio::k_US_PER_H
/// @endcode
/// 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:
/// @code
/// 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
/// @endcode
/// 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 {#bdlt_timeunitratio-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Breaking a Time Interval Into Component Parts {#bdlt_timeunitratio-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:
/// @code
/// bsls::Types::Int64 interval = 62003004005;  // nanoseconds since event
/// @endcode
/// Then, we extract the minutes part from the total, using the constant
/// `bdlt::TimeUnitRatio::k_NS_PER_M`:
/// @code
/// bsls::Types::Int64 minutesPart =
///                                 interval / bdlt::TimeUnitRatio::k_NS_PER_M;
/// @endcode
/// Next, we calculate the remaining nanoseconds using the same constant:
/// @code
/// bsls::Types::Int64 remainder = interval % bdlt::TimeUnitRatio::k_NS_PER_M;
/// @endcode
/// Then, we extract the seconds part from the remainder, using the constant
/// `bdlt::TimeUnitRatio::k_NS_PER_S`:
/// @code
/// bsls::Types::Int64 secondsPart =
///                                remainder / bdlt::TimeUnitRatio::k_NS_PER_S;
/// @endcode
/// Next, we calculate the remaining nanoseconds using the same constant:
/// @code
/// remainder %= bdlt::TimeUnitRatio::k_NS_PER_S;
/// @endcode
/// Then, we extract the milliseconds part from the remainder, using the
/// constant `bdlt::TimeUnitRatio::k_NS_PER_MS`:
/// @code
/// bsls::Types::Int64 millisecondsPart =
///                               remainder / bdlt::TimeUnitRatio::k_NS_PER_MS;
/// @endcode
/// Next, we calculate the remaining nanoseconds using the same constant:
/// @code
/// remainder %= bdlt::TimeUnitRatio::k_NS_PER_MS;
/// @endcode
/// Then, we extract the microseconds part from the remainder, using the
/// constant `bdlt::TimeUnitRatio::k_NS_PER_US`:
/// @code
/// bsls::Types::Int64 microsecondsPart =
///                               remainder / bdlt::TimeUnitRatio::k_NS_PER_US;
/// @endcode
/// Next, we calculate the remaining nanoseconds using the same constant:
/// @code
/// remainder %= bdlt::TimeUnitRatio::k_NS_PER_US;
/// @endcode
/// Now, we extract the nanoseconds part, which is exactly the remainder we
/// already have:
/// @code
/// bsls::Types::Int64 nanosecondsPart = remainder;
/// @endcode
/// Finally, we confirm that the parts we have extracted all have the correct
/// values:
/// @code
/// assert(1 == minutesPart);
/// assert(2 == secondsPart);
/// assert(3 == millisecondsPart);
/// assert(4 == microsecondsPart);
/// assert(5 == nanosecondsPart);
/// @endcode
/// 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.
/// @}
/** @} */
/** @} */
 
/** @addtogroup bdl
 * @{
 */
/** @addtogroup bdlt
 * @{
 */
/** @addtogroup bdlt_timeunitratio
 * @{
 */
 
#include <bdlscm_version.h>
 
#include <bsls_types.h>
 
 
namespace bdlt {
 
                            // ====================
                            // struct TimeUnitRatio
                            // ====================
 
/// This `struct` provides a namespace for constants characterizing ratios
/// between commonly-used time units.
///
/// See @ref bdlt_timeunitratio 
struct TimeUnitRatio {
 
    // CLASS DATA
 
                             // Fundamental ratios
 
    static const bsls::Types::Int64 k_NANOSECONDS_PER_MICROSECOND  = 1000;
    static const bsls::Types::Int64 k_MICROSECONDS_PER_MILLISECOND = 1000;
    static const bsls::Types::Int64 k_MILLISECONDS_PER_SECOND      = 1000;
    static const bsls::Types::Int64 k_SECONDS_PER_MINUTE           = 60;
    static const bsls::Types::Int64 k_MINUTES_PER_HOUR             = 60;
    static const bsls::Types::Int64 k_HOURS_PER_DAY                = 24;
 
                               // Derived ratios
 
    static const bsls::Types::Int64 k_NANOSECONDS_PER_MILLISECOND =
                k_NANOSECONDS_PER_MICROSECOND * k_MICROSECONDS_PER_MILLISECOND;
 
    static const bsls::Types::Int64 k_NANOSECONDS_PER_SECOND      =
                k_NANOSECONDS_PER_MILLISECOND * k_MILLISECONDS_PER_SECOND;
 
    static const bsls::Types::Int64 k_NANOSECONDS_PER_MINUTE      =
                k_NANOSECONDS_PER_SECOND * k_SECONDS_PER_MINUTE;
 
    static const bsls::Types::Int64 k_NANOSECONDS_PER_HOUR        =
                k_NANOSECONDS_PER_MINUTE * k_MINUTES_PER_HOUR;
 
    static const bsls::Types::Int64 k_NANOSECONDS_PER_DAY         =
                k_NANOSECONDS_PER_HOUR * k_HOURS_PER_DAY;
 
 
    static const bsls::Types::Int64 k_MICROSECONDS_PER_SECOND     =
                k_MICROSECONDS_PER_MILLISECOND * k_MILLISECONDS_PER_SECOND;
 
    static const bsls::Types::Int64 k_MICROSECONDS_PER_MINUTE     =
                k_MICROSECONDS_PER_SECOND * k_SECONDS_PER_MINUTE;
 
    static const bsls::Types::Int64 k_MICROSECONDS_PER_HOUR       =
                k_MICROSECONDS_PER_MINUTE * k_MINUTES_PER_HOUR;
 
    static const bsls::Types::Int64 k_MICROSECONDS_PER_DAY        =
                k_MICROSECONDS_PER_HOUR * k_HOURS_PER_DAY;
 
 
    static const bsls::Types::Int64 k_MILLISECONDS_PER_MINUTE     =
                k_MILLISECONDS_PER_SECOND * k_SECONDS_PER_MINUTE;
 
    static const bsls::Types::Int64 k_MILLISECONDS_PER_HOUR       =
                k_MILLISECONDS_PER_MINUTE * k_MINUTES_PER_HOUR;
 
    static const bsls::Types::Int64 k_MILLISECONDS_PER_DAY        =
                k_MILLISECONDS_PER_HOUR * k_HOURS_PER_DAY;
 
 
    static const bsls::Types::Int64 k_SECONDS_PER_HOUR            =
                k_MINUTES_PER_HOUR * k_SECONDS_PER_MINUTE;
 
    static const bsls::Types::Int64 k_SECONDS_PER_DAY             =
                k_HOURS_PER_DAY * k_SECONDS_PER_HOUR;
 
    static const bsls::Types::Int64 k_MINUTES_PER_DAY             =
                k_HOURS_PER_DAY * k_MINUTES_PER_HOUR;
 
                               // Abbreviations
 
    static const bsls::Types::Int64 k_NS_PER_US =
                                                 k_NANOSECONDS_PER_MICROSECOND;
    static const bsls::Types::Int64 k_NS_PER_MS =
                                                 k_NANOSECONDS_PER_MILLISECOND;
    static const bsls::Types::Int64 k_NS_PER_S  = k_NANOSECONDS_PER_SECOND;
    static const bsls::Types::Int64 k_NS_PER_M  = k_NANOSECONDS_PER_MINUTE;
    static const bsls::Types::Int64 k_NS_PER_H  = k_NANOSECONDS_PER_HOUR;
    static const bsls::Types::Int64 k_NS_PER_D  = k_NANOSECONDS_PER_DAY;
 
    static const bsls::Types::Int64 k_US_PER_MS =
                                                k_MICROSECONDS_PER_MILLISECOND;
    static const bsls::Types::Int64 k_US_PER_S  = k_MICROSECONDS_PER_SECOND;
    static const bsls::Types::Int64 k_US_PER_M  = k_MICROSECONDS_PER_MINUTE;
    static const bsls::Types::Int64 k_US_PER_H  = k_MICROSECONDS_PER_HOUR;
    static const bsls::Types::Int64 k_US_PER_D  = k_MICROSECONDS_PER_DAY;
 
    static const bsls::Types::Int64 k_MS_PER_S  = k_MILLISECONDS_PER_SECOND;
    static const bsls::Types::Int64 k_MS_PER_M  = k_MILLISECONDS_PER_MINUTE;
    static const bsls::Types::Int64 k_MS_PER_H  = k_MILLISECONDS_PER_HOUR;
    static const bsls::Types::Int64 k_MS_PER_D  = k_MILLISECONDS_PER_DAY;
 
    static const bsls::Types::Int64 k_S_PER_M   = k_SECONDS_PER_MINUTE;
    static const bsls::Types::Int64 k_S_PER_H   = k_SECONDS_PER_HOUR;
    static const bsls::Types::Int64 k_S_PER_D   = k_SECONDS_PER_DAY;
 
    static const bsls::Types::Int64 k_M_PER_H   = k_MINUTES_PER_HOUR;
    static const bsls::Types::Int64 k_M_PER_D   = k_MINUTES_PER_DAY;
 
    static const bsls::Types::Int64 k_H_PER_D   = k_HOURS_PER_DAY;
 
                             // 32-Bit Variations
 
    static const int k_NANOSECONDS_PER_MICROSECOND_32  =
                                                k_NANOSECONDS_PER_MICROSECOND;
    static const int k_NANOSECONDS_PER_MILLISECOND_32  =
                                                k_NANOSECONDS_PER_MILLISECOND;
    static const int k_NANOSECONDS_PER_SECOND_32       =
                                                k_NANOSECONDS_PER_SECOND;
 
    static const int k_MICROSECONDS_PER_MILLISECOND_32 =
                                                k_MICROSECONDS_PER_MILLISECOND;
    static const int k_MICROSECONDS_PER_SECOND_32      =
                                                k_MICROSECONDS_PER_SECOND;
    static const int k_MICROSECONDS_PER_MINUTE_32      =
                                                k_MICROSECONDS_PER_MINUTE;
 
    static const int k_MILLISECONDS_PER_SECOND_32 = k_MILLISECONDS_PER_SECOND;
    static const int k_MILLISECONDS_PER_MINUTE_32 = k_MILLISECONDS_PER_MINUTE;
    static const int k_MILLISECONDS_PER_HOUR_32   = k_MILLISECONDS_PER_HOUR;
    static const int k_MILLISECONDS_PER_DAY_32    = k_MILLISECONDS_PER_DAY;
 
    static const int k_SECONDS_PER_MINUTE_32      = k_SECONDS_PER_MINUTE;
    static const int k_SECONDS_PER_HOUR_32        = k_SECONDS_PER_HOUR;
    static const int k_SECONDS_PER_DAY_32         = k_SECONDS_PER_DAY;
 
    static const int k_MINUTES_PER_HOUR_32        = k_MINUTES_PER_HOUR;
    static const int k_MINUTES_PER_DAY_32         = k_MINUTES_PER_DAY;
 
    static const int k_HOURS_PER_DAY_32 = k_HOURS_PER_DAY;
 
                       // Abbreviated 32-Bit Variations
 
    static const int k_NS_PER_US_32 = k_NANOSECONDS_PER_MICROSECOND;
    static const int k_NS_PER_MS_32 = k_NANOSECONDS_PER_MILLISECOND;
    static const int k_NS_PER_S_32  = k_NANOSECONDS_PER_SECOND;
 
    static const int k_US_PER_MS_32 = k_MICROSECONDS_PER_MILLISECOND;
    static const int k_US_PER_S_32  = k_MICROSECONDS_PER_SECOND;
    static const int k_US_PER_M_32  = k_MICROSECONDS_PER_MINUTE;
 
    static const int k_MS_PER_S_32  = k_MILLISECONDS_PER_SECOND;
    static const int k_MS_PER_M_32  = k_MILLISECONDS_PER_MINUTE;
    static const int k_MS_PER_H_32  = k_MILLISECONDS_PER_HOUR;
    static const int k_MS_PER_D_32  = k_MILLISECONDS_PER_DAY;
 
    static const int  k_S_PER_M_32  = k_SECONDS_PER_MINUTE;
    static const int  k_S_PER_H_32  = k_SECONDS_PER_HOUR;
    static const int  k_S_PER_D_32  = k_SECONDS_PER_DAY;
 
    static const int  k_M_PER_H_32  = k_MINUTES_PER_HOUR;
    static const int  k_M_PER_D_32  = k_MINUTES_PER_DAY;
 
    static const int  k_H_PER_D_32  = k_HOURS_PER_DAY;
};
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2014 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */