Place

A Place is an object containing timezone information for a particular geographical location. As we have seen, Places are used primarily as arguments to Time functions, allowing Times to be specified relative to some timezone other than the host machine location. The special Place constant Place::here() contains timezone information for the host machine location; it is used implicitly by certain Time functions. The information for Place::here() is obtained from the TZ environment variable, which must be present in the execution environment of any program that invokes Place::here(), either explicitly or implicitly (by calling one of the Time functions that calls it). See Time(3C++) for a syntax description of the TZ variable and how to set it in the host environment (and also for what happens if the host environment uses an implementation-defined format for the TZ variable). Other predefined Places declared in Time.h include Place::eastern(), Place::central(), Place::mountain(), and Place::pacific().

The parameterless Place constructor creates a Place whose value is equal to Place::here(). The first argument of the two-parameter constructor must be a character string formed according to the same rules as the TZ environment variable. See Time(3C++) for a full syntax definition. The second argument, which is optional, is an integer flag which independently controls whether daylight savings time should be observed at this Place. The following example illustrates the use of the constructor to define a (rather complicated) Place:

       Place cook("KDT9:30KST10:00;64/5:00,303/20:00");

An example that makes use of the second constructor parameter is given later in this section.

The TZ environment variable (alternatively, the first constructor argument) conveys the following information:

• the name of the standard timezone (``KDT'' for cook)

• the difference between standard time and GMT (9 hours 30 minutes for cook)

• the name of the daylight savings timezone (``KST'' for cook)

• the difference between GMT and daylight savings time when daylight savings time is in effect (10 hours for cook)

• the Time when daylight savings time begins (Julian day 64 at 5 AM for cook)

• the Time when daylight savings time ends (Julian day 303 at 8 PM for cook)

These items of information can be extracted from a Place by invoking member functions provided for this purpose. For example, make_string() returns the original TZ string, while spring_ahead(y) and fall_back(y) return the Times at which daylight savings time begins and ends in year y. For example,

       Place cook("KDT9:30KST10:00;64/5:00,303/20:00");
       cout << cook.make_string() << endl;
       cout << cook.spring_ahead(1988)
                   .make_string("%x %X %Z",cook) << endl;
       cout << cook.fall_back(1988)
                   .make_string("%x %X %Z",cook)
            << endl;

prints:

       KDT9:30KST10:00;64/5:00,303/20:00
       03/04/88 04:30:00 KST
       10/29/88 20:30:00 KDT

As explained in the manpage, omitting the optional items of daylight savings time from the TZ string causes the statutory rules for US savings time to be used. This works for U.S. Places, but is likely to be incorrect elsewhere. For such non-U.S. Places, clients must use the long form to specify the daylight savings time period. Since the TZ variable allows only a single daylight savings time period to be specified, however, such client programs will need to define an array of Places, one for each year, as illustrated by the following example:

       #include "Time.h"
       #include <iostream.h>
       Place dst_table[9];

       inline Place& COOK(unsigned int y){
           return dst_table[y-1980];
       }
       main(){
       //  Set up dst_table:
           COOK(1980)=
               Place("KDT9:30KST10:00;63/5:00,308/20:00");
           COOK(1981)=
               Place("KDT9:30KST10:00;67/5:00,311/20:00");
           ...
           COOK(1988)=
               Place("KDT9:30KST10:00;64/5:00,303/20:00");

       //  Time computations:
           unsigned int y,d;
           Month m;

           Time t(y,m,d,COOK(y));
           ...
           cout << t.make_string(COOK(y)) << endl;
       }

Finally, we illustrate the use of the second constructor argument. Suppose that a Place named XYZ located in the Place::eastern() timezone chooses not to observe daylight savings time (some airports do this). A crude way to achieve this is to define the Place using a truncated TZ string. )The absence of a daylight savings timezone name will be interpreted to mean that daylight savings time is not observed.)

       Place XYZ("EST5");

This solution suffers from the need to re-enter standard timezone information, with the possibility of making a transcription error. Using the second argument eliminates this source of potential error:

       Place XYZ(Place::eastern().make_string(),0);