Click on the banner to return to the Class Reference home page.

©Copyright 1996 Rogue Wave Software

RWZoneSimple

RWZoneSimpleRWZone

Synopsis

 
#include <time.h>
#include <rw/zone.h>

RWZoneSimple myZone(USCentral);

Description

RWZoneSimple is an implementation of the abstract interface defined by class RWZone. It implements a simple daylight-saving time rule sufficient to represent all historical U.S. conventions and many European and Asian conventions. It is table-driven and depends on parameters given by the struct RWDaylightRule, which is described below.

Direct use of RWDaylightRule affords the most general interface to RWZoneSimple. However, a much simpler programmatic interface is offered, as illustrated by the examples below.

Three instances of RWZoneSimple are automatically constructed at program startup, to represent UTC, Standard, and local time. They are available via calls to the static member functions RWZone::utc(), RWZone::standard(), and RWZone::local(), respectively.

These member functions are set up according to the time zone facilities provided in the execution environment (typically defined by the environment variable TZ). By default, if DST is observed at all, then the local zone instance will use U.S. (RWZone::NoAm) daylight-saving time rules.

Note for developers outside North America: for some time zones this default will not be correct because these time zones rely on the C standard global variable _daylight. This variable is set whenever any alternate time zone rule is available, whether it represents daylight-saving time or not. Also the periods of history affected by daylight-saving time may be different in your time zone from those in North America, causing the North American rule to be erroneously invoked. The best way to ensure that these default time zones are correct is to construct an RWZoneSimple using an appropriate RWDaylightRule and initialize RWZone::local() and RWZone::std() with this value.

Other instances of RWZoneSimple may be constructed to represent other time zones, and may be installed globally using RWZone static member functions RWZone::local(const RWZone*) and RWZone::standard(const RWZone*).

Persistence

None

Examples

To install US Central time as your global "local" time use:

RWZone::local(new RWZoneSimple(RWZone::USCentral));
To install Hawaiian time (where daylight-saving time is not observed) one would say,


RWZone::local(new RWZoneSimple(RWZone::Hawaii, RWZone::NoDST));



Likewise for Japan:


RWZone::local(new RWZoneSimple(RWZone::Japan, RWZone::NoDST));



For France:


RWZone::local(new RWZoneSimple(RWZone::Europe, RWZone::WeEu));



Here are the rules used internally for the RWZone::NoAm and RWZone::WeEu values of RWZone::DstRule:


// last Sun in Apr to last in Oct:
     const RWDaylightRule  usRuleAuld =
     { 0, 0000, 1, { 3, 4, 0, 120 }, { 9, 4, 0, 120 } };
// first Sun in Apr to last in Oct
     const RWDaylightRule usRule67 =
     { &usRuleAuld, 1967, 1, { 3, 0, 0, 120 }, { 9, 4, 0, 120 } };
// first Sun in Jan to last in Oct:
     const RWDaylightRule usRule74 =
     { &usRule67, 1974, 1, { 0, 0, 0, 120 }, { 9, 4, 0, 120 } };
// last Sun in Feb to last in Oct
     const RWDaylightRule usRule75 =
    { &usRule74, 1975, 1, { 1, 4, 0, 120 }, { 9, 4, 0, 120 } };
// last Sun in Apr to last in Oct
     const RWDaylightRule usRule76 =
     { &usRule75, 1976, 1, { 3, 4, 0, 120 }, { 9, 4, 0, 120 } };
// first Sun in Apr to last in Oct
     const RWDaylightRule usRuleLate =
     { &usRule76, 1987, 1, { 3, 0, 0, 120 }, { 9, 4, 0, 120 } };

// last Sun in Mar to last in Sep
     const RWDaylightRule euRuleLate =
     { 0, 0000, 1, { 2, 4, 0, 120 }, { 8, 4, 0, 120 } };

Given these definitions, 


RWZone::local(new RWZoneSimple(RWZone::USCentral, &usRuleLate));



is equivalent to the first example given above and repeated here:


RWZone::local(new RWZoneSimple(RWZone::USCentral));



Daylight-saving time systems that cannot be represented with RWDaylightRule and RWZoneSimple must be modeled by deriving from RWZone and implementing its virtual functions.


For example, under Britain's Summer Time rules, alternate timekeeping begins the morning after the third Saturday in April, unless that is Easter (in which case it begins the week before) or unless the Council decides on some other time for that year.  In some years Summer Time has been two hours ahead, or has extended through winter without a break.  British Summer Time clearly deserves an RWZone class all its own.


Constructors


RWZoneSimple(RWZone::StdZone zone, 
             RWZone::DstRule = RWZone::NoAm);





RWZoneSimple(const RWDaylightRule* rule,
             long tzoff,  const RWCString& tzname,
             long altoff, const RWCString& altname);





RWZoneSimple(long tzoff, const RWCString& tzname);





RWZoneSimple(RWZone::StdZone zone, 
             const RWDaylightRule* rule);





struct RWDaylightRule


The RWDaylightRule struct passed to RWZoneSimple's constructor can be a single rule for all years or can be the head of a chain of rules going backwards in time.


RWDaylightRule is a struct with no constructors.  It can be initialized with the syntax used in the Examples section above.  The data members of this structure are as follows:


struct RWExport RWDaylightRule {



  RWDaylightRule const* next_;
  short firstYear_;
  char observed_;
  RWDaylightBoundary begin_; 
  RWDaylightBoundary end_;
}

RWDaylightRule const*
next_;





short
firstYear_;





char
observed_;





RWDaylightBoundary
begin_;





RWDaylightBoundary
end_;





struct RWDaylight-Boundary


struct RWExport RWDaylightBoundary {



  // this struct uses <time.h> struct tm conventions:
  int month_;    // [0..11]
  int week_;     // [0..4], or -1
  int weekday_;  // [0..6], 0=Sunday; or, [1..31] if week_== -1
  int minute_;   // [0..1439]  (Usually 2 AM, = 120)
};
int
month_;





int
week_;





int
weekday_;





int
minute_;