Place(3C++)


Place -- timezone information

Synopsis

   #include <Time.h>
   namespace SCO_SC {
   

class Time; // see Time(3C++) class ostream; // see iostream(3C++) class Place{ public: // Constructors, destructor Place(); Place(const char* tz,int observes_dst = 1); ~Place(); // Copy and assign Place(const Place& p); Place& operator=(const Place& p); // Operations that return information about a Place String standard_zone()const; int west()const; int observes()const; String daylight_zone()const; int dst()const; Time spring_ahead(unsigned y)const; Time fall_back(unsigned y)const; // Conversion to String(3C++) String make_string()const; // Standard Places static Place greenwich(); static Place eastern(); static Place central(); static Place mountain(); static Place pacific(); static Place yukon(); static Place hawaii(); static Place here(); // Stream insertion friend ostream& operator<<(ostream& os,const Place& p); }; }

Description

A Place contains six items of timezone information for a given location:

Several US Places are pre-defined as a convenience to the user. The Place Place::here() is a special case: it contains information about the local timezone. Information about the local timezone is obtained automatically from the environment variable TZ (see Time(3C++) for the complete syntax of the TZ variable and how to set it). For example, in New Jersey you might set
       TZ="EST5EDT4;117/2:00:00,299/2:00:00"

Then Place::here() would contain the following information:

Constructors, destructor

Place(); A Place with the same value as Place::here(). Raises Time::environment_objection (see Time(3C++)) if the TZ environment variable is not set. The recovery action is to behave as if TZ=GMT0 had been specified.

Place(const char* tz,int observes_dst = 1); A Place whose timezone information is described in tz, which should have the same format as the TZ environment variable, as described in Time(3C++). If observes_dst is 0, then daylight savings time will not be observed at this place, even if tz defines a daylight savings timezone (may be useful at certain airports which elect not to observe daylight savings time even though located in an area which does observe). Preconditions:tz must be nonzero.

~Place(); Destructor.

Copy and assign

Place(const Place& p);

Place& operator=(const Place& p); Copying or assigning a Place creates a copy of its value.

Operations that return information about a Place

String standard_zone()const; The name of the standard zone.

int west()const; The number of seconds to be subtracted from GMT to obtain standard time.

int observes()const; Returns non-zero if this Place observes daylight savings time. A Place observes daylight savings time if and only if (1) a daylight savings timezone name was present in the "tz" string from which this Place was constructed and (2) if the two-parameter constructor was used to construct this Place, the second argument was not zero.

String daylight_zone()const; The name of the daylight savings timezone. Preconditions: this Place must observe daylight savings time.

int dst()const; The number of seconds to be subtracted from GMT to obtain daylight savings time. Preconditions: this Place must observe daylight savings time.

Time spring_ahead(unsigned y)const; Returns the Time (see Time(3C++)) at which clocks are set ahead to begin observance of daylight savings time in year y. Preconditions: this Place must observe daylight savings time.

Time fall_back(unsigned y)const; Returns the Time (see Time(3C++)) at which clocks are set back to end observance of daylight savings time in year y. Preconditions: this Place must observe daylight savings time.

Conversion to String(3C++)

String make_string()const; Returns a String(3C++) having the same format as the TZ environment variable.

Stream insertion

friend ostream& operator<<(ostream& os,const Place& p);" os << p is equivalent to os << p.make_string().

Standard Places

static Place greenwich();

static Place eastern()

static Place central()

static Place mountain()

static Place pacific()

static Place yukon()

static Place hawaii() Pre-defined US Places.

static Place here(); The Place of the host machine. Raises the objection Time::environment_objection (see Time(3C++)) if the TZ environment variable is not set. The recovery action is to behave as if TZ=GMT0 had been specified.

Bugs

Note that the two New Jersey examples are not equivalent. The long example only yields correct results for years in which (1) daylight savings time begins on the fourth Sunday of April (2) the fourth Sunday happens to fall on Julian day number 117 (3) daylight savings time ends on the last Sunday in October and (4) the last Sunday happens to fall on Julian day number 299 (1986 is probably the only such year). The short example yields correct results in all years, with the following exception. Prior to 1970, the default daylight savings time period is assumed to start on the first Sunday in April and end on the last Sunday in October (i.e., the post-1987 rules are used). This is incorrect, but consistent with the SVR3 version of ctime(3), on which this class is based.

References

iostream(3C++), Objection(3C++), String(3C++), Time(3C++)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004