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 0c303625..65b63be0 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 @@ -5,23 +5,25 @@ 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). -Attributes are allowed to take negative values or values which do not fall in the expected range (e.g., 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 (i.e., when canonical = True) if the values of its attributes fall 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. 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. +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. ==TIME_DURATION== ====Creation==== -Instances can be created either by specifying a value for each of the attributes hour, minute and second (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. +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 returns a TIME_DURATION with 0 hour, 0 minute and 0 second. +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 easily. The order is the order oft he respective total amount of second. 1:-40:0 is less than 0:0:1800, etc... Functions <, >, <=, and >= are available. is_equal (or ~) tests object equality, = will compare references. +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. ====Element change==== @@ -33,7 +35,7 @@ Set hour, minute, and second ====Conversion==== -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. +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. 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. @@ -43,17 +45,19 @@ Durations may be canonical or not canonical (tested using the BOOLEANBOOLEAN query definite is true for definite durations and false otherwise. -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 allow their attributes year, month, and day to have meaningful values, 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?). +An instance is ''definite'' if and only if its attributes month and year are 0. Then only the number of days is used. -The distinction between definite and relative date duration matters when a duration is added to a date. In the case of a definite 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 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. +''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. + +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 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 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. ===Relative DATE_DURATION=== 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. -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 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. 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. @@ -77,7 +81,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==== @@ -96,7 +100,7 @@ Features set_day, set_month, and set_y 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, 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==== @@ -112,7 +116,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====