This chapter contains the following sections:
Class RWTime represents time, stored as the number of seconds since 1 January 1901 UTC. UTC is sometimes called GMT, for Greenwich Meridian Time. The number of seconds that can be stored is limited by the size of a long on your system. The last date and time that can be represented with a four-byte (32-bit) long is 22:28:15 February 5, 2037 UTC.
Class RWTime uses UTC because it is a widely accepted standard, useful in calculations, but it is not the usual time reference people use in their daily lives. We tell time with a local time which may or may not observe daylight-saving time (DST) conventions; in fact, DST may or may not be in effect.
When we create an RWTime object to represent the current time, the library obtains the current UTC time directly from the operating system. However, when we create an RWTime object for some specific time, we are unlikely to do so with UTC. More likely, the time we give it will be with respect to some other time zone, and we must specify which time zone for RWTime to do its job, or even print out the time. So by default, RWTime uses a global local time, set by RWZone::local().
The question naturally arises, how does the library determine this local time?
The UNIX operating system provides for setting the local time zone and for establishing whether DST is locally observed. Class RWTime uses various system calls to determine these values and sets itself accordingly. Class RWTime should function properly in North America or places where DST is not observed. In places not governed by United States DST rules, you may need to re-initialize the local time zone—see RWZone in the Class Reference.
Users of the various Windows operating systems may have to set the time switches manually. How you do this depends on your compiler. If you do nothing, the class will function properly for local time, but may not give the proper GMT because the computer has no way of knowing the offset from local time to GMT.
If you use Borland, MetaWare, Microsoft, Symantec, or Watcom, you must set your environment variable TZ to the appropriate time zone. For example:
set TZ=PST8PDT |
For further information, see the documentation for function tzset() or _tzset() in your compiler's run-time library reference.
Finally, it is essential that your computer's system clock be set and functioning correctly. If you are using a PC, be sure the batteries that power the system clock are charged.
An RWTime may be constructed in several ways:
Construct an RWTime with the current time:
RWTime t; |
Construct an RWTime with today's date, at the specified local hour (0-23), minute (0-59), and second (0-59):
RWTime t(16, 45, 0); // today, 16:45:00 |
Construct an RWTime for a given date and local time:
RWDate d(2, "June", 1952); RWTime t(d, 16, 45, 0); // 6/2/52 16:45:003 |
Construct an RWTime for a given date and time zone:
RWDate d(2, "June", 1952); RWTime t(d, 16, 45, 0, RWZone::utc()); // 6/2/52 16:45:00 |
Class RWTime has member functions to compare, store, restore, add, and subtract RWTimes. An RWTime may return hours, minutes or seconds, or fill a struct tm for any time zone. A complete list of member functions is included in the Class Reference.
For example, here is a code fragment that outputs the hour in local and UTC zones, and then the complete local time and date:
RWTime t;
cout << t.hour() << endl; // Local hour
cout << t.hour(RWZone::utc()) << endl; // UTC hour
cout << t.asString('c') << endl; // Local time and date |
See the definition for c and other format characters for time under the entry for RWLocale in the Class Reference. The next example shows how you find out when daylight-saving time starts for the current year and local time zone:
RWDate today; // Current date RWTime dstStart = RWTime::beginDST(today.year(), RWZone::local()); |
In order to ensure that this will give the right results for time zones outside of North America, you should reset RWZone::local() with an RWZoneSimple equipped with an appropriate daylight-saving time rule. For more information see RWZoneSimple in the Class Reference. See the entry for c and other format characters for time in RWLocale in the Class Reference.