Rogue Wave web site:  Home Page  |  Main Documentation Page

rwsf::TimeZone Class Reference
[Core Date/Time Manipulation]

Abstract base class for customizing timezone details. More...

#include <rwsf/core/TimeZone.h>

Inheritance diagram for rwsf::TimeZone:

List of all members.

Public Types
enum	StdZone {   NewZealand, CarolineIslands, MarianaIslands, Japan,   China, Java, Kazakh, Pakistan,   CaspianSea, Ukraine, Nile, Europe,   Greenwich, Azores, Oscar, Greenland,   Atlantic, USEastern, USCentral, USMountain,   USPacific, Yukon, Hawaii, Bering }
enum	DstRule { NoDST, NoAm, WeEu, OfficialEU }
Public Member Functions
virtual long	timeZoneOffset () const =0
virtual long	altZoneOffset () const =0
virtual bool	daylightObserved () const =0
virtual std::string	timeZoneName () const =0
virtual std::string	altZoneName () const =0
virtual bool	isDaylight (const struct tm *tmbuf) const =0
virtual void	getBeginDaylight (struct tm *dstDate) const =0
virtual void	getEndDaylight (struct tm *dstDate) const =0
Static Public Member Functions
static const TimeZone &	local ()
static const TimeZone &	standard ()
static const TimeZone &	utc ()
static const TimeZone &	os ()
static const TimeZone *	local (const TimeZone *zone)
static const TimeZone *	standard (const TimeZone *zone)
static const DaylightRule *	dstRule (DstRule rule=NoAm)

---

Detailed Description

rwsf::TimeZone is an abstract base class. It defines an interface to customize timezone specifics, such as whether or not Daylight Saving Time (DST) is in use, the names and offsets from GMT (also known as UTC) for both standard and DST, and the start and stop dates for DST, if used.

Note:

Because this 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 rwsf::TimeZone should act.

Most programs interact with rwsf::TimeZone only by passing an rwsf::TimeZone reference to an rwsf::DateTime member function that expects one.

IMPORTANT: DST rules are volatile, often reflecting geographical and political changes. In some cases, the hard-coded DST rules may not accurately reflect the locale installed on your machine. rwsf::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.

---

Member Enumeration Documentation

enum rwsf::TimeZone::DstRule

Used by the static member function dstRule(), described below, and by constructors for classes derived from rwsf::TimeZone, including rwsf::TimeZoneSimple.

Enumerator:

NoDST	Daylight Savings Time never observed.
NoAm	North America (U.S., Canada).
WeEu	Western Europe, except U.K.
OfficialEU	Official European Union DST rules.

enum rwsf::TimeZone::StdZone

Provided to name the standard time zones. These values are intended to be passed to constructors of classes derived from rwsf::TimeZone.

Enumerator:

NewZealand	New Zealand Time.
CarolineIslands	Caroline Islands.
MarianaIslands	Mariana Islands.
Japan	Japan.
China	China.
Java	Java.
Kazakh	Kazakh.
Pakistan	Pakistan.
CaspianSea	Caspian Sea.
Ukraine	Ukraine.
Nile	Nile.
Europe	Europe.
Greenwich	Greenwich.
Azores	Azores.
Oscar	Oscar (military timezone, UTC-11).
Greenland	Greenland.
Atlantic	Atlantic.
USEastern	U.S. Eastern.
USCentral	U.S. Central.
USMountain	U.S. Mountain.
USPacific	U.S. Pacific standard time.
Yukon	Alaska Time Zone (UTC-9).
Hawaii	Hawaii-Aleutian Standard Time.
Bering	Bering Standard Time, UTC-11.

---

Member Function Documentation

virtual std::string rwsf::TimeZone::altZoneName

(

)

const [pure virtual]

Returns the name of, respectively, the standard and DST zones represented, such as PST and PDT. Note that the current date and time have no effect on the return values of these functions.

Implemented in rwsf::TimeZoneSimple.

virtual long rwsf::TimeZone::altZoneOffset

(

)

const [pure virtual]

Returns the number of seconds west of GMT for DST in this zone.

Implemented in rwsf::TimeZoneSimple.

virtual bool rwsf::TimeZone::daylightObserved

(

)

const [pure virtual]

Returns true if DST is observed for this zone.

Implemented in rwsf::TimeZoneSimple.

static const DaylightRule* rwsf::TimeZone::dstRule

(

DstRule

rule = NoAm

)

[static]

Returns one of the built-in DST rules according to rule. Function dstRule() is provided for convenience in constructing rwsf::TimeZoneSimple instances for time zones in which common DST rules are obeyed. rwsf::TimeZone has predefined names for these rules, defined under "Enumerations" for this class. If rule is NoDST, then 0 is returned. The result of calling dstRule() is normally used in the rwsf::TimeZoneSimple constructor.

virtual void rwsf::TimeZone::getBeginDaylight

(

struct tm *

dstDate

)

const [pure virtual]

Returns with the struct tm parameter dstDate set to the local time that DST begins, or ends, for the year indicated by the tm_year member passed in. If DST is not observed, the fields of dstDate are all set to a negative value. Note that in the southern hemisphere, DST ends at an earlier date in a given year than it begins.

Implemented in rwsf::TimeZoneSimple.

virtual void rwsf::TimeZone::getEndDaylight

(

struct tm *

dstDate

)

const [pure virtual]

Returns with the struct tm parameter dstDate set to the local time that DST begins, or ends, for the year indicated by the tm_year member passed in. If DST is not observed, the fields of dstDate are all set to a negative value. Note that in the southern hemisphere, DST ends at an earlier date in a given year than it begins.

Implemented in rwsf::TimeZoneSimple.

virtual bool rwsf::TimeZone::isDaylight

(

const struct tm *

tmbuf

)

const [pure virtual]

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

Implemented in rwsf::TimeZoneSimple.

static const TimeZone* rwsf::TimeZone::local

(

const TimeZone *

zone

)

[static]

Sets the stored local time zone to zone. This will change the TimeZone returned by the local() function.

static const TimeZone& rwsf::TimeZone::local

(

)

[static]

Returns a reference to an rwsf::TimeZone representing local time. By default this will be an instance of rwsf::TimeZoneSimple created with offsets and zone names from the operating system, with U.S. rules for DST if observed. This is used as the default parameter value for rwsf::DateTime functions that take an rwsf::TimeZone.

static const TimeZone& rwsf::TimeZone::os

(

)

[static]

Determines the current DST rule from the underlying operating system. You can set a DST for the current year by instantiating TimeZone::local( &TimeZone::os()).

static const TimeZone* rwsf::TimeZone::standard

(

const TimeZone *

zone

)

[static]

Sets the stored standard time zone to zone. This will change the TimeZone returned by the standard() function.

static const TimeZone& rwsf::TimeZone::standard

(

)

[static]

Returns a reference to an rwsf::TimeZone representing standard local time, with no DST corrections. By default, this is an instance of rwsf::TimeZoneSimple with offset and zone name from the operating system.

virtual std::string rwsf::TimeZone::timeZoneName

(

)

const [pure virtual]

Returns the name of, respectively, the standard and DST zones represented, such as PST and PDT. Note that the current date and time have no effect on the return values of these functions.

Implemented in rwsf::TimeZoneSimple.

virtual long rwsf::TimeZone::timeZoneOffset

(

)

const [pure 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.

Implemented in rwsf::TimeZoneSimple.

static const TimeZone& rwsf::TimeZone::utc

(

)

[static]

Returns a reference to an rwsf::TimeZone representing GMT (UTC) universal time.