bdlt_datetimeutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Converting Between bsl::tm and bdlt::Datetime

Purpose

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

Classes

• bdlt::DatetimeUtil: non-primitive functions on bdlt::Datetime

See also

bdlt_datetime, bdlt_datetimeinterval, bdlt_epochutil

Description

This component provides non-primitive operations on bdlt::Datetime objects. In particular, bdlt::DatetimeUtil supplies conversions of universal time to and from the C-standard struct tm (which we alias as bsl::tm) representations.

This utility component provides the following (static) methods:

 int convertFromTm(bdlt::Datetime *result, const tm& timeStruct);
 bsl::tm convertToTm(const bdlt::Datetime& datetime);

Usage

This section illustrates intended use of this component.

Example 1: Converting Between bsl::tm and bdlt::Datetime

When interfacing with legacy systems, we may encounter calls that represent date/time information using the standard bsl::tm. In such cases, we have to be able to convert that information to/from a bdlt::Datetime object in order to interface with the rest of our systems.

Suppose we have a legacy system that tracks last-access times in terms of bsl::tm. We can use the convertToTm and convertFromTm routines from this component to convert that information.

First, we define a class, MyAccessTracker, that the legacy system uses to manage last-access times (eliding the implementation for brevity):

/// This class provides a facility for tracking last access times
/// associated with usernames.
class MyAccessTracker {
 
    // LOCAL TYPE
    typedef bsl::map<bsl::string, bsl::tm>  TStringTmMap;
 
    // DATA
    TStringTmMap                            m_accesses; // map names to
                                                        // accesses
 
  public:
    // TRAITS
    BSLMF_NESTED_TRAIT_DECLARATION(MyAccessTracker,
                                   bslma::UsesBslmaAllocator);
 
    // CREATORS
 
    /// Create an object which will track the last access time ...
    explicit MyAccessTracker(bslma::Allocator *basicAllocator = 0);
 
    // MANIPULATORS
 
    /// Update the last access time for the specified `username` with
    /// the specified `accessTime`.
    void updateLastAccess(const bsl::string&  username,
                          const bsl::tm&      accessTime);
 
    // ACCESSORS
 
    /// Load into the specified `result` the last access time associated
    /// with the specified `username`, if any.  Return 0 on success, and
    /// non-0 (with no effect on `result`) if there's no access time
    /// associated with `username`.
    int getLastAccess(bsl::tm *result, const bsl::string& username) const;
};

Next, we define a utility to allow us to use bdlt::Datetime with our legacy access tracker:

class MyAccessTrackerUtil {
  public:
 
    /// Load into the specified `result` the last access time associated
    /// with the specified `username` in the specified `tracker`, if
    /// any.  Returns 0 on success, and non-0 (with no effect on
    /// `result`) if there's no access time associated with `username`
    /// or the associated access time cannot be converted to
    /// `bdlt::Datetime`.
    static int getLastAccess(bdlt::Datetime         *result,
                             const MyAccessTracker&  tracker,
                             const bsl::string&      username);
 
    /// Update the instance pointed to by the specified `tracker` by
    /// adding the specified `username` with its associated specified
    /// `accessTime`.
    static void updateLastAccess(MyAccessTracker       *tracker,
                                 const bsl::string&     username,
                                 const bdlt::Datetime&  accessTime);
};

Then, we implement getLastAccess:

                        // -------------------------
                        // class MyAccessTrackerUtil
                        // -------------------------
 
int MyAccessTrackerUtil::getLastAccess(bdlt::Datetime         *result,
                                       const MyAccessTracker&  tracker,
                                       const bsl::string&      username)
{
    BSLS_ASSERT(result);
 
    bsl::tm legacyAccessTime;
 
    int rc = tracker.getLastAccess(&legacyAccessTime, username);
 
    if (rc) {
        return rc;                                                // RETURN
    }
 
    return bdlt::DatetimeUtil::convertFromTm(result, legacyAccessTime);
}

Next, we implement updateLastAccess:

void MyAccessTrackerUtil::updateLastAccess(
                                         MyAccessTracker       *tracker,
                                         const bsl::string&     username,
                                         const bdlt::Datetime&  accessTime)
{
    BSLS_ASSERT(tracker);
 
    bsl::tm legacyAccessTime;
 
    legacyAccessTime = bdlt::DatetimeUtil::convertToTm(accessTime);
 
    tracker->updateLastAccess(username, legacyAccessTime);
}

Finally, we create an access tracker then interact with it using bdlt::Datetime times.

/// Exercise `MyAccessTracker` for pedagogical purposes.
void exerciseTracker()
{
    MyAccessTracker accessTracker; // Datetime each user last accessed a
                                   // resource.
 
    bsl::string    richtofenName = "Baron von Richtofen";
    bdlt::Datetime richtofenDate(1918, 4, 21, 11, 0, 0);
    MyAccessTrackerUtil::updateLastAccess(&accessTracker,
                                           richtofenName,
                                           richtofenDate);
 
    // ... some time later ....
 
    bdlt::Datetime lastAccessTime;
    int rc = MyAccessTrackerUtil::getLastAccess(&lastAccessTime,
                                                 accessTracker,
                                                 richtofenName);
    assert(0 == rc);
    assert(lastAccessTime == richtofenDate);
 
    // Do something with the retrieved date...
}