No more ctime(3C) errors - Time(3C++)

Constructors

Time has three constructors. The parameterless constructor creates a Time equal to Time::REF(), as defined in the section, ``Time constants''. The four-parameter constructor expects its first three arguments to describe a date and the fourth argument to be a Place. It constructs a Time of midnight on the beginning of specified date at the specified Place (a ``local time'' relative to that Place). A version of the constructor without the fourth parameter does the same thing for the Place in which the host machine is located (see ``Place''.

For example:

       Time t1(1988,Time::january,1,Place::pacific());
       Time t2(1988,Time::january,1,Place::eastern());
       cout << (t1-t2) << endl;

prints:

      0d 03h 00m 00s

because midnight in the Pacific timezone occurs three hours later than midnight in the Eastern timezone.

In applications concerned with Times at Places other than the host machine location, it is the client's responsibility to keep track of the Place associated with each Time, and to remember to pass the same Place argument to any operation that returns Place-dependent information. For example:

       Time t(1988,Time::january,1,Place::eastern());
       cout << t.day_part() << endl;

will not necessarily print ``1''; rather, it will print the day of the month at the host machine location that corresponds, in absolute time, to 0h, Jan 1, 1988 at Place::eastern(). Assume that the machine running the above program is located in Place::pacific(). Then the program would actually print 31! To print the correct day number for Place::eastern(), the Place argument must be repeated:

       t2.day_part(Place::eastern())

In most of the examples that follow, we will use versions of Time functions that assume the host machine location. We will say more about defining and using Places in the section, ``Place''.

The four-parameter Time constructor requires that the arguments you pass must describe both (1) a valid date and (2) a Time lying within the range [Time::MIN(),Time::MAX()]. A date is valid if

the Month parameter lies in the range [0,11] (where 0 represents January, 1 represents February, and so on. You can use the enumeration type Time::Month when naming these numbers.)
the day parameter is a valid day number for the given month of the given year. (29 would be a valid day number in February 1988 (1988 was a leap year), but not in February 1989.)

For efficiency, the Time constructor does not check for bad arguments. Passing bad arguments to the constructor causes undefined behavior. [1]

If you have arguments from an unreliable source, you may check them using the auxiliary static member function Time::valid_date() (see the section, ``Auxiliary Time functions'')

       Time paranoid(unsigned y,Time::Month m,unsigned d){
           Time result;
           if(Time::valid_date(y,m,d)){
               result = Time(y,m,d);
           }
           return result;
       }