rwsf::TimeZoneSimple Class Reference

Implementation of abstract base class rwsf::TimeZone. More...

#include <rwsf/core/TimeZone.h>

Inheritance diagram for rwsf::TimeZoneSimple:

Public Member Functions
	TimeZoneSimple (const DaylightRule *rule, long tzoff, const std::string &tz_name, long altoff, const std::string &altname)
	TimeZoneSimple (long tzoff, const std::string &tz_name)
	TimeZoneSimple (StdZone zone, const DaylightRule *rule)
	TimeZoneSimple (StdZone zone, DstRule rule=NoAm)
virtual std::string	altZoneName () const
virtual long	altZoneOffset () const
virtual bool	daylightObserved () const
virtual void	getBeginDaylight (struct tm *) const
virtual void	getEndDaylight (struct tm *) const
virtual bool	isDaylight (const struct tm *tmbuf) const
virtual std::string	timeZoneName () const
virtual long	timeZoneOffset () const

Additional Inherited Members
Public Types inherited from rwsf::TimeZone
enum	DstRule { NoDST, NoAm, WeEu, OfficialEU }
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 }
Static Public Member Functions inherited from rwsf::TimeZone
static const DaylightRule *	dstRule (DstRule rule=NoAm)
static const TimeZone &	local ()
static const TimeZone *	local (const TimeZone *zone)
static const TimeZone &	os ()
static const TimeZone &	standard ()
static const TimeZone *	standard (const TimeZone *zone)
static const TimeZone &	utc ()

Detailed Description

rwsf::TimeZoneSimple is an implementation of the abstract interface defined by class rwsf::TimeZone. It implements a simple Daylight Saving Time (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 DaylightRule.

IMPORTANT: DST 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 DaylightRule) and provide it as a parameter to rwsf::TimeZoneSimple.

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) 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 global variable _daylight. This variable is set whenever any alternate time zone rule is available, whether it represents DST or not. Also the periods of history affected by DST 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*).

Constructor & Destructor Documentation

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

Constructs an rwsf::TimeZoneSimple instance for which DST is computed according to the rule specified. Variables tzoff and tz_name 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 DST is in effect. If rule is zero, DST is not observed.

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

Constructs an rwsf::TimeZoneSimple instance in which DST is not observed. Argument tzoff is the offset from GMT (in seconds, positive if west of 0 degrees longitude) and tz_name is the name of the zone.

rwsf::TimeZoneSimple::TimeZoneSimple	(	StdZone	zone,
		const DaylightRule *	rule
	)

Constructs an rwsf::TimeZoneSimple instance in which offsets and names are specified by the StdZone parameter zone. DST is computed according to the rule parameter, if non-zero; otherwise, DST is not observed.

rwsf::TimeZoneSimple::TimeZoneSimple	(	StdZone	zone,
		DstRule	rule = NoAm
	)

Constructs an rwsf::TimeZoneSimple instance using internally held instances of DaylightRule. This is the simplest interface to rwsf::TimeZoneSimple. The first parameter, zone, is the time zone for which an rwsf::TimeZoneSimple is to be constructed. The second parameter, rule, is the DST rule which is to be followed.

Member Function Documentation

virtual std::string rwsf::TimeZoneSimple::altZoneName ( ) const

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.

Implements rwsf::TimeZone.

virtual long rwsf::TimeZoneSimple::altZoneOffset ( ) const

virtual

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

Implements rwsf::TimeZone.

virtual bool rwsf::TimeZoneSimple::daylightObserved ( ) const

virtual

Returns true if DST is observed for this zone.

Implements rwsf::TimeZone.

virtual void rwsf::TimeZoneSimple::getBeginDaylight ( struct tm *  ) const

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.

Implements rwsf::TimeZone.

virtual void rwsf::TimeZoneSimple::getEndDaylight ( struct tm *  ) const

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.

Implements rwsf::TimeZone.

virtual bool rwsf::TimeZoneSimple::isDaylight ( const struct tm *  tmbuf ) const

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.

Implements rwsf::TimeZone.

virtual std::string rwsf::TimeZoneSimple::timeZoneName ( ) const

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.

Implements rwsf::TimeZone.

virtual long rwsf::TimeZoneSimple::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 rwsf::TimeZone.