RWZoneSimple(3C++) RWZoneSimple(3C++)
NameRWZoneSimple - Rogue Wave library class
Synopsis
#include <time.h>
#include <rw/zone.h>
RWZoneSimplemyZone(USCentral);
DescriptionRWZoneSimple 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:
Page 1
RWZoneSimple(3C++) RWZoneSimple(3C++)
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 } };
Page 2
RWZoneSimple(3C++) RWZoneSimple(3C++)
// 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);
Constructs an RWZoneSimple instance using internally held
RWDaylightRules. This is the simplest interface to RWZoneSimple. The
first argument is the time zone for which an RWZoneSimple is to be
constructed. The second argument is the daylight-saving time rule which
is to be followed.
RWZoneSimple(const RWDaylightRule* rule,
long tzoff, const RWCString& tzname,
long altoff, const RWCString& altname);
Constructs an RWZoneSimple instance which daylight-saving time is
computed according to the rule specified. Variables tzoff and tzname are
the offset from UTC (in seconds, positive if west of 0 degrees longitude)
and the name of standard time. Arguments altoff and altname are the
offset (typically equal to tzoff - 3600) and name when daylight-saving
Page 3
RWZoneSimple(3C++) RWZoneSimple(3C++)
time is in effect. If rule is zero, daylight-saving time is not
observed.
RWZoneSimple(long tzoff, const RWCString& tzname);
Constructs an RWZoneSimple instance in which daylight-saving time is not
observed. Argument tzoff is the offset from UTC (in seconds, positive if
west of 0 degrees longitude) and tzname is the name of the zone.
RWZoneSimple(RWZone::StdZone zone,
const RWDaylightRule* rule);
Constructs an RWZoneSimple instance in which offsets and names are
specified by the StdZone argument. Daylight-saving time is computed
according to the rule argument, if non-zero; otherwise, DST is not
observed.
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_;
Points to the next rule in a chain which continues backwards in time.
short
firstYear_;
Four digit representation of the year in which this rule first goes into
effect.
Page 4
RWZoneSimple(3C++) RWZoneSimple(3C++)
char
observed_;
A boolean value that can be used to specify a period of years for which
daylight-saving time is not observed. 1 = Daylight-saving time is in
effect during this period 0 = Daylight-saving time is not in effect
during this period (Note that these are numeric values as distinguished
from '1' and '0'.)
RWDaylightBoundary
begin_;
This structure indicates the time of year, to the minute, when DST begins
during this period. (See RWDaylightBoundary below.)
RWDaylightBoundary
end_;
This structure indicates the time of year, to the minute, when standard
time resumes during this period. (See RWDaylightBoundary below.)
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_;
The month from (0 - 11), where 0 = January.
int
week_;
A week of the month from (0 - 4), or -1 if the following field is to
represent a day within the month.
Page 5
RWZoneSimple(3C++) RWZoneSimple(3C++)
int
weekday_;
A day of the week from (0 - 6), where 0 = Sunday, or, if the week_ field
is -1, a day of the month from (1 - 31).
int
minute_;
Minutes after 12:00 AM, from (0 - 1439). For example, 120 = 2 AM.
Page 6
