SourcePro 11.1 |
SourcePro® C++ API Reference Guide |
SourcePro C++ Documentation Home |
A basic, concrete timezone implementation of the abstract class RWZone, based on the Daylight Saving Time (DST) rules defined in struct
RWDaylightRule.
More...
#include <rw/tools/classiczone.h>
Public Member Functions | |
RWZoneSimple (const RWDaylightRule *rule, long int tzoff, const RWCString &tzname, long int altoff, const RWCString &altname) | |
RWZoneSimple (long int tzoff, const RWCString &tzname) | |
RWZoneSimple (RWZone::StdZone zone, const RWDaylightRule *rule) | |
RWZoneSimple (RWZone::StdZone zone, RWZone::DstRule=RWZone::NoAm) | |
virtual int | timeZoneOffset () const |
virtual int | altZoneOffset () const |
virtual bool | daylightObserved () const |
virtual RWCString | timeZoneName () const |
virtual RWCString | altZoneName () const |
virtual bool | isDaylight (const struct tm *) const |
virtual void | getBeginDaylight (struct tm *) const |
virtual void | getEndDaylight (struct tm *) const |
RWZoneSimple is an implementation of the abstract interface defined by class RWZone. It implements a simple DST 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.
DST rules are volatile, often reflecting geographical and political changes. In some cases, the hard-coded table-driven struct RWDaylightRule does not accurately reflect the locale installed on your machine. RWZone::os() creates a new RWZoneSimple containing the daylight rule discovered from the underlying operating system, in which the operating system itself is responsible for defining the DST rules.
In many cases, you may want more explicit control of the DST rule for the intended RWZoneSimple. If so, you can build a DST rule with arbitrary begin and end times (see the RWDaylightRule below), and provide it as a parameter to RWZoneSimple.
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, representing Greenwich Mean Time (GMT), 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) DST 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 Library global variable _daylight
. This variable is set whenever any alternate time zone rule is available, whether it represents DST or not. Also the historic changes in DST rules 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::standard() 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*).
#include <time.h> #include <rw/zone.h> RWZoneSimple myZone(RWZone::USCentral);
None
To install US Central time as your global "local" time use:
To install the underlying operating system's Daylight Saving Time rule as your global "local" time use:
RWZone::local(&RWZone::os() );
To install Hawaiian time (where Daylight Saving Time is not observed), use:
Likewise for Japan, use:
For France:
RWZone has predefined values for the RWZone::DstRule rules
Here are the rules used internally for the RWZone::NoAm, RWZone::WeEu, and RWZone::OfficialEU values of RWZone::DstRule. First, here are the rules for the RWZone::NoAm value:
// 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 } };
And here are the rules for the RWZone::WeEu value:
// last Sun in March (2am) to last in September static RWDaylightRule euRuleAuld = { 0, 0000, 1, { 2, 4, 0, 120 }, { 8, 4, 0, 120 } }; // last Sun in March (1am) to last in Oct static RWDaylightRule euRuleLate = { &euRuleAuld, 1998, 1, { 2, 4, 0, 60 }, { 9, 4, 0, 60 } };
And here are the rules for the RWZone::OfficialEU value:
// Last Sun in March (2am) to last in Sept static RWDaylightRule euOfficialRuleAuld = { 0, 0000, 1, { 2, 4, 0, 120 }, { 8, 4, 0, 120 } }; // Last Sun in March (2am) to last in Oct static RWDaylightRule euOfficialRuleLate1996 = { &euOfficialRuleAuld, 1996, 1, { 2, 4, 0, 120 }, { 9, 4, 0, 180 } };
Given these definitions,
is equivalent to the first example given above and repeated here:
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.
RWZoneSimple::RWZoneSimple | ( | const RWDaylightRule * | rule, | |
long int | tzoff, | |||
const RWCString & | tzname, | |||
long int | altoff, | |||
const RWCString & | altname | |||
) | [inline] |
Constructs an RWZoneSimple instance in which DST is computed according to the provided rule. If rule is zero, DST is not observed.
rule | The DST rule | |
tzoff | The offset from GMT (in seconds, positive if west of 0 degrees longitude) | |
tzname | The name of Standard time | |
altoff | The offset (typically equal to tzoff - 600 ) to define when DST is in effect | |
altname | Alternative name for the timezone when DST is in effect, for example, MDT for Mountain Daylight Time. |
RWZoneSimple::RWZoneSimple | ( | long int | tzoff, | |
const RWCString & | tzname | |||
) |
Constructs an RWZoneSimple instance in which DST is not observed. Argument tzoff is the offset from GMT (in seconds, positive if west of 0 degrees longitude) and tzname is the name of the zone.
RWZoneSimple::RWZoneSimple | ( | RWZone::StdZone | zone, | |
const RWDaylightRule * | rule | |||
) |
Constructs an RWZoneSimple instance in which offsets and names are specified by the StdZone
argument. DST is computed according to the rule argument, if non-zero; otherwise, DST is not observed.
RWZoneSimple::RWZoneSimple | ( | RWZone::StdZone | zone, | |
RWZone::DstRule | = RWZone::NoAm | |||
) |
Constructs an RWZoneSimple instance using internal RWDaylightRule instances. This is the simplest interface to RWZoneSimple. The argument zone is the time zone for which an RWZoneSimple is to be constructed. The second argument defines the DST rule to follow. North America's DST rules are the default.
virtual RWCString RWZoneSimple::altZoneName | ( | ) | const [virtual] |
Returns the name of the DST zone represented, such as "PDT"
. Note that the current date and time have no effect on the return value.
Implements RWZone.
virtual int RWZoneSimple::altZoneOffset | ( | ) | const [virtual] |
Returns the number of seconds west of GMT for DST in this zone.
Implements RWZone.
virtual bool RWZoneSimple::daylightObserved | ( | ) | const [virtual] |
Returns true
if DST is observed for this zone.
Implements RWZone.
virtual void RWZoneSimple::getBeginDaylight | ( | struct tm * | tmbuf | ) | const [virtual] |
Returns with the struct tm
argument set to the local time that DST begins for the year specified by the tm_year
field of tmbuf. If DST is not observed, the members of tmbuf are all set to a negative value. Note that in the southern hemisphere, DST ends at an earlier date than it begins.
Implements RWZone.
virtual void RWZoneSimple::getEndDaylight | ( | struct tm * | tmbuf | ) | const [virtual] |
Returns with the struct tm
argument set to the local time that DST ends for the year specified by the tm_year
field of tmbuf. If DST is not observed, the members of tmbuf are all set to a negative value. Note that in the southern hemisphere, DST ends at an earlier date than it begins.
Implements RWZone.
virtual bool RWZoneSimple::isDaylight | ( | const struct tm * | tmbuf | ) | const [virtual] |
Returns true
if the time and date represented in the struct tm
argument is in the range of DST for this zone. The elements of tmbuf must all be self-consistent; in particular, the tm_wday
member must agree with the tm_year
, tm_mon
, and tm_day
members.
Implements RWZone.
virtual RWCString RWZoneSimple::timeZoneName | ( | ) | const [virtual] |
Returns the name of the standard time zone represented, such as "PST"
. Note that the current date and time have no effect on the return value.
Implements RWZone.
virtual int RWZoneSimple::timeZoneOffset | ( | ) | const [virtual] |
Returns the number of seconds west of GMT for standard time in this zone. The number is negative for zones east of Greenwich, England.
Implements RWZone.
© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.