rwsf::TimeZoneSimple

rwsf::TimeZoneSimple  rwsf::TimeZone

• Local Index
• Header File
• Description
• Examples
• Constructors
• struct DaylightRule
• struct Daylight-Boundary

Members

begin_ DaylightBoundary DaylightRule

end_ firstYear_ minute_

month_ next_ observed_

TimeZoneSimple() weekday_ week_

#include <rwsf/core/TimeZone.h>

rwsf::TimeZoneSimple is an implementation of the abstract interface defined by class rwsf::TimeZone. 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 DaylightRule, which is discussed later in this class.

Daylight saving-time rules are volatile, often reflecting geographical and political changes. In some cases, the hard-coded table-driven struct DaylightRule does not accurately reflect the locale installed on your machine. TimeZone::os() creates a new rwsf::TimeZoneSimple containing the daylight rule discovered from the underlying operating system. The onus of correctness for this DST rule is on the operating system itself.

In many cases, you may want more explicit control of the DST rule for the intended rwsf::TimeZoneSimple. If so, you can build a DST rule with arbitrary begin and end times (see the DaylightRule below), and provide it as a parameter to rwsf::TimeZoneSimple.

Direct use of DaylightRule affords the most general interface to rwsf::TimeZoneSimple. However, a much simpler programmatic interface is offered, as illustrated by the examples below.

Three instances of rwsf::TimeZoneSimple are automatically constructed at program startup, to represent GMT, Standard, and local time. They are available via calls to the static member functions TimeZone::utc(), TimeZone::standard(), and TimeZone::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. (TimeZone::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 rwsf::TimeZoneSimple using an appropriate DaylightRule and initialize TimeZone::local() and TimeZone::std() with this value.

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

To install U.S. Central time as your global "local" time use:

rwsf::TimeZone::local(new rwsf::TimeZoneSimple(rwsf::TimeZone::USCentral));

To install the underlying operating system's Daylight Saving Time rule as your global "local" time use:

rwsf::TimeZone::local(&rwsf::TimeZone::os() );

To install Hawaiian time (where Daylight Saving Time is not observed), use:

rwsf::TimeZone::local(new rwsf::TimeZoneSimple(rwsf::TimeZone::Hawaii,
    rwsf::TimeZone::NoDST));

Likewise for Japan, use:

rwsf::TimeZone::local(new rwsf::TimeZoneSimple(rwsf::TimeZone::Japan,
    rwsf::TimeZone::NoDST));

For France:

rwsf::TimeZone::local(new rwsf::TimeZoneSimple(rwsf::TimeZone::Europe,
    rwsf::TimeZone::WeEu));

rwsf::TimeZone has predefined values for the rwsf::TimeZone::DstRule rules:

Here are the rules used internally for the NoAm, WeEu, and OfficialEU values of rwsf::TimeZone::DstRule. First, here are the rules for the NoAm value:

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

And here are the rules for the WeEu value:

// last Sun in March (2am) to last in September
     static DaylightRule euRuleAuld =
     { 0, 0000, 1, { 2, 4, 0, 120 }, { 8, 4, 0, 120 } };
// last Sun in March (1am) to last in Oct
     static DaylightRule euRuleLate =
     { &euRuleAuld, 1998, 1, { 2, 4, 0, 60 }, { 9, 4, 0, 60 } };

And here are the rules for the OfficialEU value:

// Last Sun in March (2am) to last in Sept
     static DaylightRule euOfficialRuleAuld =
     { 0, 0000, 1, { 2, 4, 0, 120 }, { 8, 4, 0, 120 } };
// Last Sun in March (2am) to last in Oct
     static DaylightRule euOfficialRuleLate1996 =
     { &euOfficialRuleAuld, 1996, 1, { 2, 4, 0, 120 }, { 9, 4, 0, 180 } };

Given these definitions,

rwsf::TimeZone::local(new rwsf::TimeZoneSimple(rwsf::TimeZone::USCentral,
              rwsf::TimeZone::NoAm));

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

rwsf::TimeZone::local(new rwsf::TimeZoneSimple(rwsf::TimeZone::USCentral));

Daylight Saving Time systems that cannot be represented with DaylightRule and rwsf::TimeZoneSimple must be modeled by deriving from rwsf::TimeZone 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 rwsf::TimeZone class all its own.

TimeZoneSimple(StdZone zone, 
    DstRule = NoAm);

Constructs an rwsf::TimeZoneSimple instance using internally held DaylightRules. This is the simplest interface to rwsf::TimeZoneSimple. The first argument is the time zone for which an rwsf::TimeZoneSimple is to be constructed. The second argument is the Daylight Saving Time rule which is to be followed.

TimeZoneSimple(const DaylightRule* rule,
    long tzoff,  const std::string& tz_name,
    long altoff, const std::string& altname);

Constructs an rwsf::TimeZoneSimple instance which Daylight Saving Time is computed according to the rule specified. Variables tzoff and tzname are the offset from GMT (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 Time is in effect. If rule is zero, Daylight Saving Time is not observed.

TimeZoneSimple(long tzoff, const std::string& tz_name);

Constructs an rwsf::TimeZoneSimple instance in which Daylight Saving Time 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.

TimeZoneSimple(StdZone zone, 
    const DaylightRule* rule); 

Constructs an rwsf::TimeZoneSimple 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.

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

DaylightRule 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 DaylightRule {
  DaylightRule const* next_;
  short firstYear_;
  char observed_;
  DaylightBoundary begin_; 
  DaylightBoundary end_;
}


DaylightRule 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.

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'.)

DaylightBoundary
begin_;

This structure indicates the time of year, to the minute, when DST begins during this period. (See DaylightBoundary below.)

DaylightBoundary
end_;

This structure indicates the time of year, to the minute, when standard time resumes during this period. (See DaylightBoundary below.)

struct DaylightBoundary {

  // 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.

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.

©2004-2007 Copyright Quovadx, Inc. All Rights Reserved.
Quovadx and Rogue Wave are registered trademarks and HydraSDO is a trademark of Quovadx, 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.