| Absolute Times | |
The notion of date and time can be represented with an oriented axis with values in the past on the left and values in the future on the right. Date and time are absolute values which can be compared using a total order relationship based on this time axis representation. Therefore class DT_ABSOLUTE_TIME is a descendant of COMPARABLE. It also inherits from HASHABLE in order to allow dates and times to be used as keys in hash tables. There are three kinds of absolute times. Times, instances of class DT_TIME, are temporal values in a day such as 14:30:21. Dates, instances of class DT_DATE, are values in the Gregorian calendar such as 21 April 2000. And date/times, instances of class DT_DATE_TIME, are a combination of date and time such as 25 December 2000 at 10:35:10.
Time objects are made up of hour, minute and second. These features follow the normal conventions: seconds are within the range 0 to 59, minutes are between 0 and 59, and hours are between 0 and 23. Precision up to the millisecond is also available thanks to the feature millisecond. These four fields of class DT_TIME can be set individually or together with the following routines: set_hour, set_minute, set_second, set_millisecond, set_hour_minute_second and set_precise_hour_minute_second. The precise prefix in feature names implies that the millisecond field is involved. These setting routines are equipped with preconditions to ensure that the fields of the time objects are still within their corresponding ranges. Two other routines, second_count and millisecond_count, return the number of seconds and milliseconds elapsed since midnight. Time objects can be set using these values with set_second_count and set_millisecond_count.
Four creation procedures are provided. make requires three arguments to set the hour, minute and second, whereas make_precise needs an extra argument to set the millisecond precision. On the other hand make_from_second_count and make_from_millisecond_count create a new time object based on its number of seconds or milliseconds since midnight.
It is possible to add or subtract hours, minutes, seconds and/or milliseconds to a time using features add_hours, add_minutes, add_seconds, add_milliseconds, add_hours_minutes_seconds and add_precise_hours_minutes_seconds with positive or negative arguments. For example adding 25 minutes to the time 14:44:10 yields 15:09:10. However since the notion of time is relative to a day in a cyclic representation, times are always bounded within 00:00:00 and 23:59:59. Therefore adding 1 second to the time 23:59:59 yields 00:00:00 also known as midnight. Likewise adding -6 hours to 02:35:21 yields 20:35:21. Time durations can also be added to time objects with features add_duration and add_time_duration, or their equivalent infix operators infix "+" and infix "&t" which return a new object at each call and do not alter the current time object. In short, a time duration is an object which contains among other things the number of hours, minutes, seconds and milliseconds between two times. For example the duration between the times 10:23:45 and 14:35:50 is 4 hours, 12 minutes and 5 seconds. In order to get the duration between two times, one can call the routines duration and time_duration or their equivalent infix operator infix "-". This operator subtract the fields of the times field by field. For example the subtraction of the times 20:05:14 and 13:24:00 yields 7 hours, -19 minutes and 14 seconds. However it is common practice to use canonical durations, in other words durations where all fields have the same sign and where the absolute value of the number of minutes is between 0 and 59 and absolute value of the number of seconds is between 0 and 59. In such a case, one should call the routine canonical_duration instead of the duration routine above. The subtraction of the two times 20:05:14 and 13:24:00 now yields the canonical duration 6 hours, 41 minutes and 14 seconds.
Constants related to time are available in class DT_GREGORIAN_CALENDAR. Seconds_in_minute, Seconds_in_hour and Seconds_in_day return the number of seconds in a minute, hour or day. Milliseconds_in_day returns the number of milliseconds in a day. Minutes_in_hour returns the number of minutes in an hour. Hours_in_day returns the number of hours in a day.
Date objects are made up of year, month and day. Because of the irregularities in the Gregorian calendar, the months in a year don't have the same number of days. For example days in January are in the range 1 to 31 whereas in Februay there are either 28 or 29 days depending on whether the year is a leap year or not. One can query the number of days for a given month with the routine days_in_month from class DT_GREGORIAN_CALENDAR. Likewise one can check whether a given year is a leap year or not with the routine leap_year. Two similar routines, days_in_current_month and is_leap_year, are also available in class DT_DATE in order to inspect the month and year of a given date object. The three fields of class DT_DATE can be set individually or together with the following routines: set_year, set_month, set_day and set_year_month_day. Of course these routines are equipped with preconditions to ensure that the date stays consistent. For example the month has to be between 1 and 12, and the day has to fit in the resulting month. It is indeed impossible given the date 31 March 2000 to set the month to June since there are only 30 days in June.
Two creation procedures are provided. make requires three arguments to set the year, month and day. On the other hand make_from_day_count takes only one argument corresponding to the number of days since epoch (1 January 1970). It is indeed common practice for operating systems to provide the current date of the system by returning the number of days or seconds elapsed since January 1rst 1970 at midnight. Two related routines in class DT_DATE are day_count which returns the number of days since 1 January 1970, and set_day_count which has a similar effect as the creation procedure make_from_day_count. For example, the day_count for 31 January 1970 will be 30 whereas the day_count for 31 December 1969 will have the negative value -1. Two other useful features are week_day which returns the day in the current week of a date object within the range 1 (i.e. Sunday) to 7 (i.e. Saturday), and year_day which returns the day of a date object in its current year. For example for 1 January 2000, year_day yields 1 whereas for 31 December 1999 the result is 365.
It is possible to add or subtract years, months and/or days to a date using features add_years, add_months, add_days and add_years_months_days with positive or negative arguments. For example adding 8 months to the date 3 August 1996 yields 3 April 1997. Note that because of the irregularities in the Gregorian calendar, it has been decided to truncate the day when the resulting date is invalid. For instance adding one year to 29 February 2000 yields 28 February 2001, and adding one month to 31 March 2000 yields 30 April 2000. Similarly, adding 5 days and 1 month is not always the same as adding 1 month and 5 days. For example starting with 28 March 2000, the first operation yields 2 May 2000 whereas the second yields 3 May 2000. Therefore the convention chosen for add_years_months_days is to add the years first, then the months, truncate the day if necessary and finally add the days. Date durations can also be added to date objects with the features add_duration and add_date_duration, or their equivalent infix operators infix "+" and infix "&d" which return a new object at each call and do not alter the current date object. In short, a date duration is an object which contains among other things the number of years, months and days between two dates. For example the duration between the dates 5 April 2000 and 15 July 2002 is 2 years, 3 months and 10 days. In order to get the duration between two dates, one can call the routines duration and date_duration or their equivalent infix operator infix "-". As we will see later, a date duration is generally not deterministic. For example adding one month to 15 April 2000 is equivalent to adding 30 days, whereas adding 1 month to 15 May 2000 is equivalent to adding 31 days. Therefore a date duration is said to be definite when it is expressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of the three duration routines above is n it is ressed only in terms of days, leaving the year and month parts empty. The result of