RWZone Class Reference

Abstract base class defining an interface to describe time zones. More...

#include <rw/tools/zone.h>

Inheritance diagram for RWZone:

Public Types
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 }

Public Member Functions
virtual RWCString	altZoneName () const =0
virtual int	altZoneOffset () const =0
virtual bool	daylightObserved () const =0
virtual rwint64	fromTM (const struct tm *tmbuf) const
virtual void	getBeginDaylight (struct tm *tmbuf) const =0
virtual void	getEndDaylight (struct tm *tmbuf) const =0
virtual bool	isDaylight (const struct tm *tmbuf) const =0
virtual RWCString	name (const struct tm *tmbuf) const
virtual int	offset (const struct tm *tmbuf) const
virtual RWCString	timeZoneName () const =0
virtual int	timeZoneOffset () const =0
virtual void	toTM (rwint64 msec, struct tm *tmbuf, int *tzOffset, RWCString *tzName) const

Static Public Member Functions
static const RWDaylightRule *	dstRule (DstRule rule=NoAm)
static const RWZone &	local ()
static const RWZone *	local (const RWZone *zone)
static const RWZone &	os ()
static const RWZone &	standard ()
static const RWZone *	standard (const RWZone *zone)
static const RWZone &	utc ()

Detailed Description

RWZone is an abstract base class that defines an interface for time zone issues, such as whether or not Daylight Saving Time (DST) is in use, the names and offsets from Greenwich Mean Time (GMT) (also known as Coordinated Universal Time, or UTC), for both standard and Daylight Saving Time, and the start and stop dates for DST, if used. Note that because it 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 RWZone should act.

Most programs interact with RWZone only by passing an RWZone reference to SourcePro member functions that expect one.

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 RWZone containing the daylight rule discovered from the underlying operating system. This way, the operating system itself defines the DST rules.

Synopsis

#include <time.h>
#include <rw/zone.h>
(abstract base class)

Persistence

None

Example

#include <rw/zone.h>

#include <rw/zone.h>
#include <rw/tools/datetime.h>

int main ()
{
    RWDateTime now(RWDateTime::setCurrentTime);

    std::cout << now.asString("%x %X", RWLocale::global(), RWZone::local()) << std::endl;
    std::cout << now.asString("%x %X", RWLocale::global(), RWZone::utc()) << std::endl;

    return 0;
}

Member Enumeration Documentation

enum RWZone::DstRule

Used by the static member function dstRule() and by constructors for classes derived from RWZone, including RWZoneSimple.

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

enum RWZone::StdZone

Names the standard time zones. Its values are intended to be passed to constructors of classes derived from RWZone.

Enumerator
NewZealand	= -12
CarolineIslands
MarianaIslands
Japan
China
Java
Kazakh
Pakistan
CaspianSea
Ukraine
Nile
Europe
Greenwich
Azores
Oscar
Greenland
Atlantic
USEastern
USCentral
USMountain
USPacific
Yukon
Hawaii
Bering

Member Function Documentation

virtual RWCString RWZone::altZoneName ( ) const

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

Implemented in RWZoneSimple.

virtual int RWZone::altZoneOffset ( ) const

pure virtual

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

Implemented in RWZoneSimple.

virtual bool RWZone::daylightObserved ( ) const

pure virtual

Returns true if DST is observed for this zone.

Implemented in RWZoneSimple.

static const RWDaylightRule* RWZone::dstRule ( DstRule  rule = NoAm )

static

Returns one of the built-in DST rules according to rule. This function is provided for convenience in constructing RWZoneSimple instances for time zones in which common DST rules are obeyed. RWZone has predefined names for these rules, defined under the enumerations section for this class. If DstRule NoDST is provided, then 0 is returned. The result of calling dstRule() is normally passed to the RWZoneSimple constructor.

virtual rwint64 RWZone::fromTM ( const struct tm *  tmbuf ) const

virtual

Returns the number of milliseconds that have elapsed since January 1, 1901 00:00:00:000 UTC in this zone given the date and time in tmbuf.

virtual void RWZone::getBeginDaylight ( struct tm *  tmbuf ) const

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

Implemented in RWZoneSimple.

virtual void RWZone::getEndDaylight ( struct tm *  tmbuf ) const

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

Implemented in RWZoneSimple.

virtual bool RWZone::isDaylight ( const struct tm *  tmbuf ) const

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

Implemented in RWZoneSimple.

static const RWZone& RWZone::local ( )

static

Returns a reference to an RWZone representing local time. By default, this is an instance of RWZoneSimple created with offsets and zone names from the operating system, with U.S. rules for DST, if observed. This is used as a default argument value to member functions of other classes where an RWZone argument is required.

static const RWZone* RWZone::local ( const RWZone *  zone )

static

Sets the RWZone to be returned by RWZone::local() to zone and returns the previous value.

virtual RWCString RWZone::name ( const struct tm *  tmbuf ) const

virtual

Returns the current name of the zone for the time given in tmbuf.

The default implementation of this function returns timeZoneName() if isDaylight() returns false for tmbuf, otherwise returns altZoneName().

virtual int RWZone::offset ( const struct tm *  tmbuf ) const

virtual

Returns the number of seconds west of GMT in this zone for the time given in tmbuf.

The default implementation of this function returns timeZoneOffset() if isDaylight() returns false for tmbuf, otherwise returns altZoneOffset().

static const RWZone& RWZone::os ( )

static

On the first call, determines DST rules for the years 1970 - 2037, from the underlying operating system. On subsequent calls, a cached copy is used. You can set the DST rules for these years by with:

RWZone::local(&RWZone::os()).

static const RWZone& RWZone::standard ( )

static

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

static const RWZone* RWZone::standard ( const RWZone *  zone )

static

Sets the RWZone to be returned by RWZone::standard() to zone and returns the previous value.

virtual RWCString RWZone::timeZoneName ( ) const

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

Implemented in RWZoneSimple.

virtual int RWZone::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 RWZoneSimple.

virtual void RWZone::toTM ( rwint64  msec, struct tm *  tmbuf, int *  tzOffset, RWCString *  tzName  ) const

virtual

Populates tmbuf for this zone based on msec milliseconds since January 1, 1901 00:00:00:000 UTC. If not NULL, tzOffset and tzName are populated with the time zone offset and time zone name at the time specified.

static const RWZone& RWZone::utc ( )

static

Returns a reference to an RWZone representing GMT (UTC) universal time.