Duration

The classes TIME_DURATION, DATE_DURATION, and DATE_TIME_DURATION model time durations.

The classes dealing with duration inherit from DURATION, which in turn inherits from GROUP_ELEMENT and PART_COMPARABLE. From this lineage comes the query zero, the addition features infix + and infix - and the unary features 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 So, TIME + TIME_DURATION is possible, but not TIME + DATE_TIME_DURATION nor DATE_TIME + TIME_DURATION ... see classes TIME, DATE, and DATE_TIME in Absolute time.

Attributes of durations are allowed to take values which do not fall in the expected range, even negative values (e.g., hour = -1, minute = 75, day = 40...). However, queries are available in each class to test for canonical format and to provide equivalent instances in canonical format.

An instance is canonical if the values for all of its relevant attributes fall into the specific ranges defined for each type of duration, documented in sections below (for example, for a canonical instance of TIME_DURATION, the value of second will be in 0..59). In such a case, the value of query canonical is True. For example, an instance of TIME_DURATION such as 12:-10:60 is not canonical. The query to_canonical will return a new instance with equivalent value, but with its components in canonical form, in the case of our example: 11:51:0. These features are also present in DATE_DURATION and DATE_TIME_DURATION.

Ordering is partial for DATE_DURATION and DATE_TIME_DURATION for reasons explained below, and total for TIME_DURATION.

TIME_DURATION

Creation

Instances can be created either by specifying a value for each of the attributes hour, minute, and second (make), or by specifying only a number of seconds (make_by_seconds). Any integer value is accepted. So, for example, it is possible to create a duration with 1 hour and -60 minutes.

Access

The query zero provides a TIME_DURATION with 0 hour, 0 minute and 0 second.

The total number of seconds in the current duration can be obtained by applying the query seconds_count.

Comparison

Instances of TIME_DURATION may be compared. The order is the order of the respective total number of seconds. So, 1:-40:0 is less than 0:0:1800, for example. Functions <, >, <=, and >= are available. The BOOLEAN query is_equal (or the object equality operator ~) tests object equality, = will compare references.

Element change

Set hour, minute, and second with set_hour, set_minute, and set_second. Arguments do not need to satisfy any range rule.

Operations

• Add hours, minutes and seconds with features hour_add, minute_add and second_add.
• infix + and infix - are available for producing sums and differences of durations.
• prefix - is available for producing the inverse of a duration.

Conversion

Two features provide a conceptual link with the notion of day:

• The first, 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 to_days is -1).
• The second is time_modulo_day. This query 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.

Sample: Suppose the value of an instance of TIME_DURATION is 25:70:600. Then applying to_days will return 1 (one day) and applying time_modulo_day will return 2:20:0. Now suppose that the value of the TIME_DURATION is negative, say -23:-80:300. In this case, applying to_days will return -2 (minus two days) and time_modulo_day will return 23:45:0.

Durations may be in canonical or non-canonical form. This can be tested using the BOOLEAN query canonical. Canonical form depends upon whether the features hour, minute, and second have values that fall into a particular range. An instance of TIME_DURATION is canonical if:

• in the case of a positive duration (> zero), all of the three features have to be positive or 0, minute and second less than 60.
• in the case of a negative duration (< zero), all of the three features have to be negative or 0, minute and second strictly greater than -60.

Two queries help you work with canonical form:

• The value of the query canonical is True if duration is in canonical form.
• The query to_canonical yields a new, canonical TIME_DURATION equivalent to the duration to which it is applied.

DATE_DURATION

DATE_DURATION is similar to TIME_DURATION, but models durations in dates rather than times. Dealing with the Gregorian calendar is complicated by its irregularities. For example, a date duration of one month may be equal to 28, 29, 30, 31 days, depending on a date of reference. Sometimes though, it is useful to deal with a precise date duration, just a number of days, independent of any particular date. This issue leads to a unique point of design in the DATE_DURATION class: a separation is made between two kinds of instances: definite date durations and the relative date durations. The BOOLEAN query definite is True for definite date durations and false for relative date durations.

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 allow their attributes year, month, and day to have meaningful values, but disallow comparisons with other durations, for reasons which will be explained below.

The distinction between definite and relative date duration makes a difference when a duration is added to a date. In the case of a definite DATE_DURATION, there is no ambiguity: a given number of days is added to the date. In the case of a relative DATE_DURATION, the result is relative to the duration's origin_date. For example, a one month duration may be equal to 28 days if the date is in February or 31 days if the date is in August.

About relative DATE_DURATIONs

Relative durations cannot be compared with any other durations (including zero). This is because of the complexities of the Gregorian calendar. If we consider how many days there are in a duration of one month, we cannot point to a specific integer value that will be correct in all cases ... it depends upon which month we are considering ... and in some cases whether it is a leap year.

If a comparison (> or <) is applied in a state in which either the current instance or the argument or both are relative durations, the result will be always False.

We are able to determine if two durations have equal value by applying the feature is_equal (or the object equality operator ~).

When adding a relative DATE_DURATION to a DATE, the years and the months are added first, then the date may be cut (for example, June 31 cut to 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?

• If the origin date is 01/15 (15th of January), the final date is 02/14. We cannot convert 30 days into 1 month in this case. The duration is canonical.
• If the origin date is 04/15 (15th of April), the final date is 05/15. The duration is not canonical since it is possible to convert days into 1 month. The origin date is used to determine whether the duration is positive or not. If the final date is after the origin date the duration is positive, otherwise it is negative. That does not mean we can compare it to zero, that is only used to determine the sign of the canonical standard. If the duration is negative, it is canonical only if all the attributes are negative.

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.

About definite DATE_DURATIONs

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 relative.

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.

General description

Creation

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.

Comparison

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.

Element change

Features set_day, set_month, and set_year are available to set one of these three attributes day, month, year.

Operations

• Add years, months and days with features year_add, month_add, and day_add.
• DATE_DURATION inherits from GROUP_ELEMENT. infix and prefix +, infix and prefix - are available to compose instances of each other.

Conversion

• to_canonical is used to get a new duration equivalent to the current one and canonical. It needs an argument from class DATE, which is the origin of calculations.
• to_definite is used to get a new duration equivalent to the current one and definite. As with the previous feature, one argument is needed.
• to_date_time is used to get an instance of DATE_TIME_DURATION. It will have the same date of the current duration and time set to zero.

DATE_TIME_DURATION

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.

Creation

There are still several ways to create an instance:

• Provide values for all the components of date and time (make).
• Provide a value for day and values for all the components of time. The instance is then definite (make_definite).
• by gathering an instance of DATE with an instance of TIME (make_by_date_time). This feature copies the references of its arguments, so that if the time (or the date) is changed, the instance previously initialized will be also changed. If this effect has to be avoided, the use of twins is required.
• by encapsulating an instance of DATE (make_by_date). The attribute time is set to zero, i.e. 0:0:0. The attribute date is set with the same reference than the argument.

Access

seconds_count is the amount of seconds of the time part only. To get the total amount of seconds of the current 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).

Comparison

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.

Element change

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.

Operations

• DATE_TIME_DURATION inherits from GROUP_ELEMENT. infix and prefix +, infix and prefix - are available to compose instances to each other.
• Only day_add is present. To add only one element, features from TIME_DURATION or DATE_DURATION have to be used.

Conversion

• canonical and to_canonical are available in the class. To be canonical an instance of the class must have its attributes time and date canonical. Then time must have the same sign than the one of the current duration. The sign of the current instance is determined by adding it to the argument (from DATE_TIME). That will yield a final date. If this final date is after the origin (= the argument), the current duration is considered positive. Otherwise, it is considered negative. Finally time must be less than one day (if positive) or more than minus one day (if negative). to_canonical returns a duration equivalent to the current one (for the argument) and canonical.
• time_to_canonical looks like to_canonical but focuses mainly on time. It requires a definite duration so that it is possible to compare it to zero. It yields a definite duration equivalent to the current one with a canonical time. hour is then cut so that it stands in the range of one day (0 to 23 if positive and -23 to 0 if negative). The attribute day is also modified to keep the result equivalent to the current duration. time_to_canonical does not need any argument because only time and day are modified.