TIME_DURATION, DATE_DURATION AND DATE_TIME_DURATION
The classes dealing with duration inherit DURATION, which inherits GROUP_ELEMENT and PART_COMPARABLE. An instance of TIME_DURATION, DATE_DURATION or DATE_TIME_DURATION is an element of a group, i.e. there is a zero and addition operations (infix +, infix -, prefix + and prefix -). Duration is used as an amount of time, without link to an origin. It may be added to the respective absolute notion (time + time_duration is possible, not time + date_time_duration nor date_time + time_duration...see classes TIME, DATE and DATE_TIME).
Attributes are allowed to take negative values or values which do not stand in the usual range (hour = -1, minute = 75, day = 40...). However, features are available in each class to convert instances into the usual format: functions canonical and to_canonical are present in each class. An instance is canonical (canonical = True) if its attributes stand into the usual range. For example, an instance of TIME_DURATION such as 12:-10:60 is not canonical. to_canonical will return 11:51:0. In DATE_DURATION and DATE_TIME_DURATION, these features are also present.
The order is partially implemented. TIME_DURATION has a complete order whereas DATE_DURATION and DATE_TIME_DURATION are more specific.
Two ways are possible: by choosing the value of each attributes hour, minute and second (feature make), or by giving an amount of seconds (make_by_seconds). Any integer value is accepted. It is possible to create a duration with 1 hour and -60 minutes.
Zero is a once feature with 0 hour, 0 minute and 0 second. The total amount of second of the current duration is the result of feature seconds_count.
Instances of TIME_DURATION may be compared easily. The order is the order of the respective total amount of second. 1:-40:0 is less than 0:0:1800, etc... Functions <, >, <= and >= are available. Is_equal tests equality, = will compare references.
Set directly hour, minute and second with set_hour, set_minute and set_second. Arguments do not need to satisfy any range rule.
Two features ensure a link with the notion of day: to_days returns the number of days equivalent to the current duration. For example, a duration such as 23:60:0 is equivalent to one day. For negative duration, the result is never 0. -1 hour is equivalent to -1 day (i.e. the result of the function is - 1). To_days is associated with time_modulo_day. This second function returns an instance of TIME_DURATION. The result represents the difference between the current duration and the number of days yielded by to_days. It implies that the result is always positive and less than one day.
For example, the current duration is 25:70:600. to_days will returns 1 (one day) and time_modulo_day will return 2:20:0:. If the current duration is negative: -23:-80:300, to_days will return -2 (minus two days) and time_modulo_day will return 23:45:0.
Durations may be canonical or not canonical (BOOLEAN canonical). That means the features hour, minute and second are included in a particular range, or not. An instance of TIME_DURATION is canonical if:
Dealing with the gregorian calendar is not so easy because of irregularities. A duration of one month may be equal to 28 up to 31 days, depending on the current date! On the other hand, it could be useful to deal with precise duration. This point leads to an original design of the class: A separation is made between two kinds of instances.
The definite ones and the relative ones. The function definite which returns a BOOLEAN, is true for definite duration and false otherwise. An instance is definite if and only if its attributes month and year are 0. Then only the number of days is used. Relative (non definite) durations have their attributes year, month and day meaningful but it is then impossible to compare them to each other (is one month greater than 30 days?, is one year greater than 365 days?). The main difference appears when a duration is added to a date. In the case of a definite duration, there is no ambiguity. A given number of days are added to the date, taking care of the calendar. In the other case, the result is relative to the origin date. For example, a one month duration may be equal to 28 days if the date is in February or 31days if the date is in August. A duration becomes definite when its attributes year and month become 0. However it is possible to deal with instances of DATE_DURATION without taking care of this distinction.
Relative duration can not be compared with any other durations (including zero). The reason is simple. It is not possible to say if 30 days are less than 1 month: it depends on the date: it is true in August (in a 31 days month) and it is false in February.
If feature > (or <, + + is called with at least one non definite member (the current instance or the argument), the result will be always False. We may only know if two durations are equal, with the feature is_equal. It compares field by field the two durations. When adding a relative date_duration to a date, the years and the months are added first, then the date may be cut (June 31 -> June 30) and finally the days are added. For example, if one month is added to the date August 31st, the result is September 30th.
Nevertheless there is a way to compare relative durations: a relative date_duration may be canonical. It means that the duration has its attributes month and day in a fixed range. month must be between 1 and 12, and day larger than 1 and less than a value between 27 and 30. This value is fixed simply: (in the case of a positive duration) when setting day to 0 and adding one more month, the addition of the start date and this new duration must yield a date strictly after the final date (yielded by adding date and tested duration). For example is 0/0/30 (i.e. 0 year, 0 month and 30 days) canonical?
A way to compare two relative durations is to make them canonical from the same date, and then to compare the fields. It is the same as adding the durations to the same date, and to compare the final dates to each other.
Definite durations are characterized by the attribute day. Whenever a duration has its attributes year and month equal to 0, this duration is then definite. On the other hand, if one of these two attributes is not 0, the duration is not definite anymore.
The number of days between an origin date and the result of (date + duration) does not depend on the origin date. It is possible to compare definite date_duration to each other. The order is the one of day.
A definite duration may be canonical or not. It is canonical if the number of day is small enough.
Two creation features are available: make takes three arguments (year, month and day). If year and month are null, the duration will be definite; make_by_days takes only the number of day. The duration is automatically definite.
Features <, >, <= and >= are available. If both instances are definite, numbers of days are compared. If one of them is non definite, the result is False.
Features set_day, set_month and set_year are available to set one of these three attributes day, month, year.
DATE_TIME_DURATION is client of DATE_DURATION and TIME_DURATION. Most of the common features described in DATE_DURATION are present in the class. The class deals with its attributes date and time in the same way as DATE_TIME.
There are, as in DATE_DURATION, definite and non definite durations. It is the date part which gives the definite non definite status. Features canonical and to_canonical are present in DATE_TIME_DURATION. They have to deal with the attributes time.
There are still several ways to create an instance:
Seconds_count is the amount of seconds of the time part only. To get the total amount of seconds of the cur-rent duration, first shift it to a definite duration, then multiply day by the number of seconds in day and add to it seconds_count. Take care that the duration is not more than 68 years. If it is, the number of seconds will be larger than 2 billion, which is the upper limit for INTEGER (4 bytes).
The rules are the same than those for DATE_DURATION. Features <, >, <= and >= are available. If both instances are definite, numbers of days are compared. If one of them is non definite, the result is False.
It is possible to change reference of time and date with the features set_time and set_date. To change only one element (for example hour), features from TIME_DURATION or DATE_DURATION have to be used.