|
|
The relationship between Time and Duration can be seen readily by examining the code that creates the `sample values'
#include <Time.h>
#include <iostream.h>
main(){
Time t1 = Time(1987,Time::july,3) + Duration(0,21);
Time t2 = Time(1987,Time::july,4) + Duration(0,3);
Duration d=t1-t2;
cout << t1 << endl;
cout << t2 << endl;
cout << d << endl;
}
The Time constructor takes three arguments specifying a year, Month (an enumeration type defined in Time.h), and day-within-month; it constructs a Time equivalent to midnight on the beginning of the specified date. A Time other than midnight is obtained by adding a Duration to a Time; by adding Durations of 0d 21h and 0d 3h, respectively, to t1 and t2, we obtain Times of 9PM and 3AM on two successive dates. Finally, the Duration variable d is initialized with the difference between t1 and t2 yielding a Duration of -6h. The output of the program will be:
07/03/87 21:00:00
07/04/87 03:00:00
-0d 06h 00m 00s
Let's take a look at how Times actually work. The Time constructor assumes that its arguments express a Time of midnight on the beginning of the specified date in the local timezone; it computes an internal representation of absolute time based on the number of seconds elapsed since January 1, 1970 at 0h GMT, a representation chosen to make the arithmetic and relational operations more efficient. This is the same definition of absolute time used by the standard facilities. Assuming the machine running the above program is located in the US Eastern timezone, four hours would be added as part of the conversion to the internal representation. (In the Eastern timezone, clocks are normally 5h behind Greenwich Mean Time; when daylight savings time is in effect, as in the example, the difference is only 4h.) Operations that view Times in component form (such as stream insertion) convert back to the local timezone by applying the inverse transformation. Note that both conversions are completely transparent to clients who are deal only in local time, as we do in the above example.
Clients who need the ability to express or view Times in timezones other than the local zone can take advantage of the fact that many Time operations come in pairs: one with and one without a Place parameter. The ones with the Place parameter allow a Time to be expressed relative to a particular Place. Those without the Place parameter implicitly use the timezone in which the host machine is located. For example, the Time constructor also comes in a four-parameter version in which the fourth parameter specifies a Place:
Time t1(1987,Time::july,3,Place::eastern());
Time t2(1987,Time::july,3,Place::central());
Time t3(1987,Time::july,3,Place::mountain());
Time t4(1987,Time::july,3,Place::pacific());
Time t5(1987,Time::july,3,Place::here());
In each of the above declarations, the fourth argument is a static function declared in Time.h returning information for a specific US timezone. For example, Place::eastern() returns a Place 5h west of Greenwich having a daylight savings differential of 1h, and so on. The static function Place::here() is special; it returns information about the host machine timezone. Place::here() is the default value of Time operations without the extra Place parameter. The following declarations therefore create two equal Times:
Time t5(1987,Time::july,3,Place::here());
Time t6(1987,Time::july,3);
Timezone information for Place::here() is obtained from the UNIX environment variable TZ. However the environment variable is not queried unless local timezone information is actually needed; that is, it will only be queried on behalf of programs that either explicitly or implicitly invoke the function Place::here(). Most simple-minded Time applications will need this information, so unless you are willing to get involved with fancy error-handling (see the section, ``Error handling'', remember to set TZ prior to running such applications.
Times do not `remember' their Places. This means, for example, that when viewing the components of a Time, the Place argument must be supplied again so that the transformation back to the correct local zone can be performed. If the following code were executed in New Jersey,
Time t = Time(1987,Time::july,3,Place::central()) +
Duration::hours(18);
...
cout << t.clock_part() << endl;
the output would be 0d 19h 00m 00s (not 0d 18h 00m 00s) since clock_part() assumes Place::here() by default. To see the time-of-day in the Place::central() timezone, we must write
cout << t.clock_part(Place::central()) << endl;