RWZone(3C++)

Name
     RWZone - Rogue Wave library class

Synopsis
              #include <time.h>



              #include <rw/zone.h>
          (abstract base class)




Description
     RWZone is an abstract base class.  It defines an interface for time zone
     issues such as whether or not daylight-saving time is in use, the names
     and offsets from UTC (also known as GMT) for both standard and daylight-
     saving times, and the start and stop dates for daylight-saving time, if
     used.  Note that because it is an abstract base class, there is no way to
     actually enforce these goals -- the description here is merely the model
     of how a class derived from RWZone should act.  Most programs interact
     with RWZone only by passing an RWZone reference to an RWTime or RWDate
     member function that expects one.  RWZoneSimple is an implementation of
     the abstract RWZone interface sufficient to represent U.S. daylight-
     saving time rules.  Three instances of RWZoneSimple are initialized from
     the global environment at program startup to represent local, standard,
     and universal time.  They are available via calls to the static member
     functions RWZone::local(), RWZone::standard(), and RWZone::utc(),
     respectively.  See the class RWZoneSimple for details.

Persistence
     None

Example
              #include <rw/zone.h>
          #include <rw/rwtime.h>
          #include <rw/rstream.h>
          main(){
           RWTime now;
           cout << now.asString(' ', RWZone::local()) << endl;
           cout << now.asString("%x %X", RWZone::utc()) << endl;
           return 0;
          }

Enumerations
              enum DstRule { NoDST, NoAm, WeEu };


     Used by the static member function dstRule(), described below, and by
     constructors for classes derived from RWZone.

              enum StdZone {
            NewZealand = -12,     CarolineIslands,     MarianaIslands,
            Japan,                China,               Java,
            Kazakh,               Pakistan,            CaspianSea,
            Ukraine,              Nile,                Europe,
            Greenwich,            Azores,              Oscar,
            Greenland,            Atlantic,            USEastern,
            USCentral,            USMountain,          USPacific,
            Yukon,                Hawaii,              Bering
          };


     StdZone is provided to name the standard time zones.  Its values are
     intended to be passed to constructors of classes derived from RWZone.

Public Member Functions
              virtual int
          timeZoneOffset() const = 0;


     Returns the number of seconds west of UTC for standard time in this zone.
     The number is negative for zones east of Greenwich, England.

              virtual int
          altZoneOffset() const = 0;


     Returns the number of seconds west of UTC for daylight-saving time in
     this zone.

              virtual RWBoolean
          daylightObserved() const = 0;


     Returns TRUE if daylight-saving time is observed for this zone.

              virtual RWBoolean
          isDaylight(const struct tm* tspec) const = 0;


     Returns TRUE if the time and date represented in the struct tm argument
     is in the range of daylight-saving time for this zone.  The elements of
     the tm argument must all be self-consistent; in particular, the tm_wday
     member must agree with the tm_year, tm_mon, and tm_day members.

              virtual void
          getBeginDaylight(struct tm*) const = 0;
          virtual void
          getEndDaylight  (struct tm*) const = 0;


     Return with the struct tm argument set to the local time that daylight-
     saving time begins, or ends, for the year indicated by the tm_year member
     passed in.  If daylight-saving time is not observed, the struct tm
     members are all set to a negative value.  Note that in the southern
     hemisphere, daylight-saving time ends at an earlier date than it begins.

              virtual RWCString
          timeZoneName() const = 0;
          virtual RWCString
          altZoneName() const = 0;


     Return the name of, respectively, the standard and daylight-saving time
     zones represented, such as "PST" and "PDT".  Note that the current date
     and time have no effect on the return values of these functions.

Static Public Member Functions
              static const RWZone&
          local();


     Returns a reference to an RWZone representing local time.  By default
     this will be an instance of RWZoneSimple created with offsets and zone
     names from the operating system, with U.S. rules for daylight-saving time
     if observed.  This is used as the default argument value for RWDate and
     RWTime functions that take an RWZone.

              static const RWZone&
          standard();


     Returns a reference to an RWZone representing standard local time, with
     no daylight-saving time corrections.  By default this is an instance of
     RWZoneSimple with offset and zone name from the operating system.

              static const RWZone&
          utc();


     Returns a reference to an RWZone representing UTC (GMT) universal time.

              static const RWZone*
          local(const RWZone*);
          static const RWZone*
          standard(const RWZone*);


     These functions allow the values returned by the other functions above to
     be set.  Each returns the previous value.

              static constRWDaylightRule*
          dstRule(DstRule rule = NoAm);

     Returns one of the built-in daylight-saving time rules according to rule.
     Function dstRule() is provided for convenience in constructing
     RWZoneSimple instances for time zones in which common daylight-saving
     time rules are obeyed.  Currently two such rule systems are provided,
     NoAm for the U.S.A. and Canada, and WeEu for most of Western Europe
     (excluding the U.K.).  See RWZoneSimple for more details.  If DstRule
     NoDST is given, then 0 is returned. The result of calling dstRule() is
     normally passed to the RWZoneSimple constructor.