Introduction to Time(3C++)

This tutorial describes a C++ component called Time(3C++) which allows you to deal with time in a much more natural and convenient fashion. The following Time(3C++) program is functionally equivalent to the C program above:

       #include <Time.h>
       #include <iostream.h>
       main(){
           Time result = make_time("now") + Duration::days(30);
           cout << result << endl;
       }

Notice that the program is short and transparently correct. Things that are hard to do using the standard facilities are easy to do using Time(3C++). For example, we can display the result in a different timezone:

       cout << result.make_string(Place::pacific()) << endl;

and we can even control the output format:

       cout << result.make_string("%a %b %E, %Y\ n",
               Place::pacific());

As a matter of fact, Time(3C++) adds little if any new functionality to the standard facilities beyond the relaxation of the year 2038 limit. By providing a more natural and convenient interface to those facilities, however, Time(3C++) makes it easier for you to write programs--without time errors!

The Time(3C++) section of the manual contains three manpages, plus an introduction. The manpages describe three relatively orthogonal sets of facilities that make up the component:

Time(3C++)

Describes class Time and related facilities. A Time value combines, in a single value, a (Gregorian) calendar date and a time-of-day. Time values are represented using 64 bits and have a range from January 1, 1901 to January 1, 2901 and a fixed precision of one second. July 3, 1987 at 9:00PM and July 4, 1987 at 3:00AM are two sample values of class Time.

Duration(3C++)

Describes class Duration and related facilities. Durations denote signed time differences with magnitude of up to the full range of Time values, and fixed precision of one second. Minus thirty minutes (which we will abbreviate as -30m) is a sample value of class Duration. Note that a nonnegative Duration less than 24 hours can be viewed as a ``time-of-day,'' a term that we will use freely throughout this tutorial.

Place(3C++)

Describes class Place and related facilities. A Place contains timezone information for a particular geographical location. 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.

The next section paves the way for the discussion of individual classes in the sections, ``Duration'' through ``Place'', by giving several examples that illustrate the close relationships among these three types. The section ``Error handling'' discusses the error handling mechanism employed uniformly by all classes.