Absolute Times

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

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

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 1^rst 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 definite. For example the duration between 2 May 2000 and 3 July 2000 yields 62 days. 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 days is the smallest possible one and the absolute value of the number of months is between 0 and 11. In such a case, one should call the routine canonical_duration instead of the duration routine above. The subtraction of the two dates 3 July 2000 and 2 May 2000 now yields the canonical duration 2 months and 1 day. But again, because of irregularities in the Gregorian calendar, this might become tricky. For example the canonical duration between 31 May 2000 and 30 June 2000 is 1 month and not 30 days! Indeed, if we follow the definition of canonical duration, 0 day is smaller than 30 days and adding 1 month to 31 May 2000 yields the expected date thanks to the truncation of the day which occurs in the addition routines.

Constants related to date are available in class DT_GREGORIAN_CALENDAR. Months_in_year returns the number of months in a year. Days_in_year returns the number of days in a non-leap year whereas Days_in_leap_year returns the number of days in a leap year. The months of the year are also given symbolic names: January, February, March, April, May, June, July, August, September, October, November, December. Days_in_week returns the number of days in a week and days of the week are given symbolic names: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. The next and previous day of a given day in the week can also be found by calling features next_day and previous_day.

Date Time

Date/time objects are a combination of a date and a time relative to that date. They are made up of year, month, day, hour, minute, second and millisecond. Class DT_DATE_TIME is equipped with the same setting routines as DT_DATE and DT_TIME. In addition to the features inherited from these two classes, one can also get or set the date and the time parts of a date/time object with routines date, time, set_date and set_time.

Five creation procedures are provided. make requires six arguments to set the year, month, day, hour, minute and second, whereas make_precise needs an extra argument to set the millisecond precision. On the other hand make_from_date_time and make_from_date create a new date/time object based on its date and time parts. make_from_epoch creates a new date time from the number of seconds since epoch (1 Jan 1970 at 00:00:00). This routine is useful to convert the time stamp of a file (see feature time_stamp from class KI_FILE) into a human readable format.

Contrary to time, date time objects do not have a cyclic representation. When the time part reaches 23:59:59, the date part swiches to the next day. For example adding 2 hours to 30 April 2000 23:30:00 yields 1 May 2000 01:30:00. Otherwise it is possible to add and subtract years, months, days, hours, minutes, seconds and/or milliseconds to a date/time using the same features as in DT_DATE and DT_TIME. One can also add date durations, time durations and date/time durations with the features add_date_duration, add_time_duration and add_duration or their infix operator counterparts infix "&d", infix "&t" and infix "+". In order to get the duration between two date/times, one can call the routines duration or its equivalent infix operator infix "-". As for date objects, these routines return a definite duration. In orther words the year and month parts are null and the hour, minute and second parts may have arbitrary values. One should call canonical_duration instead of the duration routine above in order to get a duration where the date and time parts are canonical. One last difference with DT_DATE and DT_TIME is that date_duration only returns the date part of duration whereas time_duration only returns its time part.