Component bdlt_datetimeutil [Package bdlt]

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

Namespaces
namespace	bdlt

---

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:

Component bdlt_datetime, Component bdlt_datetimeinterval, Component 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):

  class MyAccessTracker {
      // This class provides a facility for tracking last access times
      // associated with usernames.

      // 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
      explicit MyAccessTracker(bslma::Allocator *basicAllocator = 0);
          // Create an object which will track the last access time ...

      // MANIPULATORS
      void updateLastAccess(const bsl::string&  username,
                            const bsl::tm&      accessTime);
          // Update the last access time for the specified 'username' with
          // the specified 'accessTime'.

      // ACCESSORS
      int getLastAccess(bsl::tm *result, const bsl::string& username) const;
          // 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'.
  };

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

  class MyAccessTrackerUtil {
    public:
      static int getLastAccess(bdlt::Datetime         *result,
                               const MyAccessTracker&  tracker,
                               const bsl::string&      username);
          // 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 void updateLastAccess(MyAccessTracker       *tracker,
                                   const bsl::string&     username,
                                   const bdlt::Datetime&  accessTime);
          // Update the instance pointed to by the specified 'tracker' by
          // adding the specified 'username' with its associated specified
          // '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.

  void exerciseTracker()
      // Exercise 'MyAccessTracker' for pedagogical purposes.
  {
      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...
  }