diff --git a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/duration.wiki b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/duration.wiki index 3f6040fe..4193c2f5 100644 --- a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/duration.wiki +++ b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/duration.wiki @@ -3,17 +3,21 @@ [[Property:uuid|64672bd0-b696-0c39-1e30-5ac64aae4a99]] The classes TIME_DURATION, DATE_DURATION, and DATE_TIME_DURATION model time durations. -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, but not TIME + DATE_TIME_DURATION nor DATE_TIME + TIME_DURATION ... see classes TIME, DATE, and DATE_TIME). +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 of its attributes fall into the acceptable ranges. 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. The order is partially implemented. TIME_DURATION has a complete order whereas DATE_DURATION and DATE_TIME_DURATION are more specific. +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. +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==== @@ -23,7 +27,7 @@ The total number of seconds in the current duration can be obtained by applying ====Comparison==== -Instances of TIME_DURATION may be compared easily. 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 ~) tests object equality, = will compare references. +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==== @@ -31,33 +35,46 @@ Set hour, minute, and second ====Operations==== * Add hours, minutes and seconds with features hour_add, minute_add and second_add. -* TIME_DURATION inherits from GROUP_ELEMENT. infix and prefix +, infix and prefix - are available to compose instances of each other. +* 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 ensure a 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 other feature associated with the idea of ''day'' 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. +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. -For example, the current duration is 25:70:600. to_days will return 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. +{{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. -Durations may be canonical or not canonical. This can be tested using the BOOLEAN query canonical. Canonical form depends upon whether the features hour, minute, and second have values that fall in 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. The query canonical tests whether a duration is canonical. The query to_canonical yields a new, canonical TIME_DURATION equivalent to the query's target. ==DATE_DURATION== -DATE_DURATION is similar to TIME_DURATION, but models durations in dates rather than times. Dealing with the Gregorian calendar is not so easy because of its irregularities. A date duration of one month may be equal to 28, 29, 30, 31 days, depending on the current date! Sometimes though, it could be useful to deal with a precise date duration, just a number of days, independent of the current 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. +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 that will be explained below. +''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. 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. +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. -===Relative DATE_DURATION=== +===About ''relative'' DATE_DURATIONs=== -Relative duration cannot 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. +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 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 have equal value with the feature is_equal (or ~). 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. +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. @@ -65,7 +82,7 @@ Nevertheless, there is a way to compare relative durations: a relative date_dura 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 DATE_DURATION=== +===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. @@ -81,7 +98,7 @@ Two creation features are available: make takes three arguments ====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. +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==== @@ -116,7 +133,7 @@ There are still several ways to create an instance: ====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. +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====