Component baltzo_loader [Package baltzo]

Provide a protocol for obtaining information about a time zone. More...

Namespaces
namespace	baltzo

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Properties of a Populated baltzo::Zoneinfo
  • Usage
    • Example 1: Implementing baltzo::Loader
    • Example 2: Using a baltzo::Loader

Purpose:

Provide a protocol for obtaining information about a time zone.

Classes:

baltzo::Loader

protocol for obtaining time-zone information

See also:

Component baltzo_zoneinfo, Component baltzo_datafileloader, Component baltzo_testloader

Description:

This component provides a protocol, baltzo::Loader, for obtaining information about a time zone from some data-source. The protocol's primary method, loadTimeZone, loads a baltzo::Zoneinfo object describing the time zone identified by a user supplied time-zone string identifier.

Properties of a Populated baltzo::Zoneinfo:

Implementations of baltzo::Loader must return a baltzo::Zoneinfo object that is well-formed (see baltzo::ZoneinfoUtil::isWellFormed), and whose identifier property matches the requested time zone id. Implementations not meeting these constraints will generally not interoperate with other components in this package that enforce those constraints on provided baltzo::Zoneinfo objects, e.g., baltzo_zoneinfocache.

Usage:

This section illustrates intended use of this component.

Example 1: Implementing baltzo::Loader:

This example demonstrates an implementation of baltzo::Loader that can only return data for "America/New_York".

Note that in general, an implementation of baltzo::Loader should obtain time-zone information from an external data source (see baltzo_datafileloader).

First, we define the interface of our implementation:

  class MyLoaderImp : public baltzo::Loader {
      // This class provides a concrete implementation of the
      // 'baltzo::Loader' protocol (an abstract interface) for obtaining a
      // time zone.  This test implementation contains only partial data of
      // the "America/New_York" time zone, and is unable to obtain time-zone
      // information for any other time zones.

    public:
      // CREATORS
      MyLoaderImp();
          // Create a 'MyLoaderImp' object.

      ~MyLoaderImp();
          // Destroy this object.

      // MANIPULATORS
      virtual int loadTimeZone(baltzo::Zoneinfo *result,
                               const char       *timeZoneId);
          // Load into the specified 'result' the "Zoneinfo" time zone
          // information for the time zone identified by the specified
          // 'timeZoneId'.  Return 0 on success, and non-zero otherwise.
  };

Then, we implement the creators, trivially, as this class contains no instance data members.

  MyLoaderImp::MyLoaderImp()
  {
  }

  MyLoaderImp::~MyLoaderImp()
  {
  }

Next, we implement the loadTimeZone function:

  int MyLoaderImp::loadTimeZone(baltzo::Zoneinfo *result,
                                const char       *timeZoneId)
  {

Then, we check the timeZoneId equals to "America/New_York" as this implementation is designed to demonstrate only one time zone:

      if (0 != strcmp("America/New_York", timeZoneId)) {
          return 1;                                                 // RETURN
      }

Next, we load result with the time zone identifier for New York

      result->setIdentifier("America/New_York");

Then, we create two local-time descriptors, one for standard time and one for daylight-saving time.

      baltzo::LocalTimeDescriptor edt(-14400, true, "EDT");
      baltzo::LocalTimeDescriptor est(-18000, false, "EST");

Next, we create a series of transitions between these local time descriptors for the years 2007-2011. Note that the United States transitions to daylight saving time on the second Sunday in March, at 2am local time (7am UTC), and transition back to standard time on the first Sunday in November at 2am local time (6am UTC), resulting in an even number of transitions. Also note that, the rules for generating these transitions were changed in 2007, and may be changed again at some point in the future.

      static const bdlt::Datetime TRANSITION_TIMES[] = {
          bdlt::Datetime(2007,  3, 11, 7),
          bdlt::Datetime(2007, 11,  4, 6),
          bdlt::Datetime(2008,  3,  9, 7),
          bdlt::Datetime(2008, 11,  2, 6),
          bdlt::Datetime(2009,  3,  8, 7),
          bdlt::Datetime(2009, 11,  1, 6),
          bdlt::Datetime(2010,  3, 14, 7),
          bdlt::Datetime(2010, 11,  7, 6),
          bdlt::Datetime(2011,  3, 13, 7),
          bdlt::Datetime(2011, 11,  6, 6),
      };
      const int NUM_TRANSITION_TIMES =
                          sizeof TRANSITION_TIMES / sizeof *TRANSITION_TIMES;

      assert(0 == NUM_TRANSITION_TIMES % 2);

      for (int i = 0; i < NUM_TRANSITION_TIMES; i += 2) {
          result->addTransition(
                      bdlt::EpochUtil::convertToTimeT64(TRANSITION_TIMES[i]),
                      edt);
          result->addTransition(
                  bdlt::EpochUtil::convertToTimeT64(TRANSITION_TIMES[i + 1]),
                  est);
      }
      return 0;
  }

Finally, we define a function f that instantiates an object of type MyLoaderImp:

  void f()
  {
      MyLoaderImp a;
  }

Example 2: Using a baltzo::Loader:

In this example we use a MyLoaderImpl to load the data for one time zone, and print the time transitions, contained in the obtained time zone data, to standard output. Note that, the implementation of this example is for illustrative purpose only, and in general, clients should use an implementation that loads data from an external data source (e.g., baltzo_datafileloader).

First, we obtain a MyLoaderImpl reference to myLoader we constructed in the previous example:

  baltzo::Loader& loader = myLoader;

Now, we load the time zone data for New York:

  baltzo::Zoneinfo nyTimeZone;
  if (0 != loader.loadTimeZone(&nyTimeZone, "America/New_York")) {
     bsl::cout << "Failed to find time zone data." << bsl::endl;
     return -1;                                                     // RETURN
  }

Then, we verify some basic properties of the time zone:

  assert("America/New_York" == nyTimeZone.identifier());

Finally, we write to standard output the information about the daylight-saving time transitions of the loaded time zone, in New York local time:

  baltzo::Zoneinfo::TransitionConstIterator tIt =
                                               nyTimeZone.beginTransitions();
  for (; tIt != nyTimeZone.endTransitions(); ++tIt) {
     bdlt::Datetime transition =
               bdlt::EpochUtil::convertFromTimeT64(tIt->utcTransitionTime());
     const baltzo::LocalTimeDescriptor& descriptor = tIt->descriptor();

     bsl::cout << "transition to "
               << descriptor.description()
               << " at "
               << transition
               << " UTC"
               << bsl::endl;
  }

The resulting output will look like:

  transition to EDT at 11MAR2007_07:00:00.000 UTC
  transition to EST at 04NOV2007_06:00:00.000 UTC
  transition to EDT at 09MAR2008_07:00:00.000 UTC
  transition to EST at 02NOV2008_06:00:00.000 UTC
  transition to EDT at 08MAR2009_07:00:00.000 UTC
  transition to EST at 01NOV2009_06:00:00.000 UTC
  transition to EDT at 14MAR2010_07:00:00.000 UTC
  transition to EST at 07NOV2010_06:00:00.000 UTC
  transition to EDT at 13MAR2011_07:00:00.000 UTC
  transition to EST at 06NOV2011_06:00:00.000 UTC