mirrors/eiffel-org
1
0
Fork 0
mirror of https://github.com/EiffelSoftware/eiffel-org.git synced 2025-12-07 15:22:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Author:halw

Browse Source 
Date:2008-11-03T00:47:47.000000Z


git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@102 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
halw
2008-11-03 00:47:47 +00:00
parent 4d639d0bc2
commit 40772d6536
1 changed files with 16 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/duration.wiki
View File

@@ -5,23 +5,25 @@
The classes dealing with duration inherit <eiffel>DURATION</eiffel>, which inherits <eiffel>GROUP_ELEMENT</eiffel> and <eiffel>PART_COMPARABLE</eiffel>. An instance of <eiffel>TIME_DURATION</eiffel>, <eiffel>DATE_DURATION</eiffel>, or <eiffel>DATE_TIME_DURATION</eiffel> is an element of a group, i.e. there is a zero and addition operations (<eiffel>infix +</eiffel>, <eiffel>infix -</eiffel>, <eiffel>prefix +</eiffel>, and <eiffel>prefix -</eiffel>). Duration is used as an amount of time, without link to an origin. It may be added to the respective absolute notion (<eiffel>TIME + TIME_DURATION</eiffel> is possible, but not <eiffel>TIME + DATE_TIME_DURATION</eiffel> nor <eiffel>DATE_TIME + TIME_DURATION</eiffel> ... see classes <eiffel>TIME</eiffel>, <eiffel>DATE</eiffel>, and <eiffel>DATE_TIME</eiffel>).
Attributes are allowed to take negative values or values which do not fall in the expected range (e.g., <eiffel>hour = -1</eiffel>, <eiffel>minute = 75</eiffel>, <eiffel>day = 40</eiffel>...). However, features are available in each class to convert instances into the usual format: functions <eiffel>canonical</eiffel> and <eiffel>to_canonical</eiffel> are present in each class. An instance is canonical (i.e., when <eiffel>canonical = True</eiffel>) if the values of its attributes fall into the usual range. For example, an instance of <eiffel>TIME_DURATION</eiffel> such as 12:-10:60 is not canonical. to_canonical will return 11:51:0. These features are also present in <eiffel>DATE_DURATION</eiffel> and <eiffel>DATE_TIME_DURATION</eiffel>.The order is partially implemented. <eiffel>TIME_DURATION</eiffel> has a complete order whereas <eiffel>DATE_DURATION</eiffel> and <eiffel>DATE_TIME_DURATION</eiffel> are more specific.
Attributes of durations are allowed to take values which do not fall in the expected range, even negative values (e.g., <eiffel>hour = -1</eiffel>, <eiffel>minute = 75</eiffel>, <eiffel>day = 40</eiffel>...). 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 <eiffel>canonical</eiffel> is <eiffel>True</eiffel>. For example, an instance of <eiffel>TIME_DURATION</eiffel> such as 12:-10:60 is not canonical. The query <eiffel>to_canonical</eiffel> 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 <eiffel>DATE_DURATION</eiffel> and <eiffel>DATE_TIME_DURATION</eiffel>. The order is partially implemented. <eiffel>TIME_DURATION</eiffel> has a complete order whereas <eiffel>DATE_DURATION</eiffel> and <eiffel>DATE_TIME_DURATION</eiffel> are more specific.
==TIME_DURATION==
====Creation====
Instances can be created either by specifying a value for each of the attributes hour, minute and second (<eiffel>make</eiffel>), or by giving an amount of seconds (<eiffel>make_by_seconds</eiffel>). 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 (<eiffel>make</eiffel>), or by specifying only a number of seconds (<eiffel>make_by_seconds</eiffel>). Any integer value is accepted. So, for example, it is possible to create a duration with 1 hour and -60 minutes.
====Access====
The query <eiffel>zero</eiffel> returns a <eiffel>TIME_DURATION</eiffel> with 0 hour, 0 minute and 0 second.
The query <eiffel>zero</eiffel> provides a <eiffel>TIME_DURATION</eiffel> with 0 hour, 0 minute and 0 second.
The total number of seconds in the current duration can be obtained by applying the query <eiffel>seconds_count</eiffel>.
====Comparison====
Instances of <eiffel>TIME_DURATION</eiffel> 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. <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>) tests object equality, <eiffel>=</eiffel> will compare references.
Instances of <eiffel>TIME_DURATION</eiffel> 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 <eiffel>BOOLEAN</eiffel> query <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>) tests object equality, <eiffel>=</eiffel> will compare references.
====Element change====
@@ -33,7 +35,7 @@ Set <eiffel>hour</eiffel>, <eiffel>minute</eiffel>, and <eiffel>second</eiffel>
====Conversion====
Two features ensure a link with the notion of day: <eiffel>to_days</eiffel> 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). <eiffel>to_days</eiffel> is associated with <eiffel>time_modulo_day</eiffel>. This second function returns an instance of <eiffel>TIME_DURATION</eiffel>. The result represents the difference between the current duration and the number of days yielded by <eiffel>to_days</eiffel>. 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, <eiffel>to_days</eiffel> 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 <eiffel>to_days</eiffel> is -1). The other feature associated with the idea of ''day'' is <eiffel>time_modulo_day</eiffel>. This query returns an instance of <eiffel>TIME_DURATION</eiffel>. The result represents the difference between the current duration and the number of days yielded by <eiffel>to_days</eiffel>. It implies that the result is always positive and less than one day.
For example, the current duration is 25:70:600. <eiffel>to_days</eiffel> will return 1 (one day) and <eiffel>time_modulo_day</eiffel> will return 2:20:0:. If the current duration is negative: -23:-80:300, <eiffel>to_days</eiffel> will return -2 (minus two days) and <eiffel>time_modulo_day</eiffel> will return 23:45:0.
@@ -43,17 +45,19 @@ Durations may be canonical or not canonical (tested using the <eiffel>BOOLEAN</e
==DATE_DURATION==
Dealing with the Gregorian calendar is not so easy because of irregularities. A date 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 issue leads to a unique point of design in the class: A separation is made between two kinds of instances.
Dealing with the Gregorian calendar is not so easy because of irregularities. A date 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 issue leads to a unique point of design in the class: A separation is made between two kinds of instances: ''definite'' date durations and the ''relative'' date durations. The <eiffel>BOOLEAN</eiffel> query <eiffel>definite</eiffel> is true for definite durations and false otherwise.
The ''definite'' ones and the ''relative'' ones. The function <eiffel>definite</eiffel> which returns a <eiffel>BOOLEAN</eiffel>, is true for definite duration and false otherwise. An instance is definite if and only if its attributes <eiffel>month</eiffel> and <eiffel>year</eiffel> are 0. Then only the number of days is used. Relative (non definite) durations allow their attributes <eiffel>year</eiffel>, <eiffel>month</eiffel>, and <eiffel>day</eiffel> 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 <eiffel>month</eiffel> and <eiffel>year</eiffel> 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 <eiffel>year</eiffel> and <eiffel>month</eiffel> become 0. However it is possible to deal with instances of <eiffel>DATE_DURATION</eiffel> without taking care of this distinction.
''Relative'' (non-definite) durations allow their attributes <eiffel>year</eiffel>, <eiffel>month</eiffel>, and <eiffel>day</eiffel> 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 <eiffel>year</eiffel> and <eiffel>month</eiffel> become 0. However it is possible to deal with instances of <eiffel>DATE_DURATION</eiffel> 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 <eiffel>></eiffel> (or <eiffel><</eiffel>) 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 <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>). 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 <eiffel>></eiffel> (or <eiffel><</eiffel>) 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 <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>). 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 <eiffel>month</eiffel> and <eiffel>day</eiffel> in a fixed range. <eiffel>month</eiffel> must be between 1 and 12, and <eiffel>day</eiffel> 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: <eiffel>make</eiffel> 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 <eiffel>set_day</eiffel>, <eiffel>set_month</eiffel>, and <eiffel>set_y
<eiffel>DATE_TIME_DURATION</eiffel> is client of <eiffel>DATE_DURATION</eiffel> and <eiffel>TIME_DURATION</eiffel>. Most of the common features described in <eiffel>DATE_DURATION</eiffel> are present in the class. The class deals with its attributes date and time in the same way as <eiffel>DATE_TIME</eiffel>.
There are, as in <eiffel>DATE_DURATION</eiffel>, 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 <eiffel>DATE_TIME_DURATION</eiffel>. They have to deal with the attributes time.
There are, as in <eiffel>DATE_DURATION</eiffel>, 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 <eiffel>DATE_TIME_DURATION</eiffel>. 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 <eiffel>DATE_DURATION</eiffel>. 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 <eiffel>DATE_DURATION</eiffel>. 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====