mirror of
https://github.com/EiffelSoftware/eiffel-org.git
synced 2025-12-06 14:52:03 +01:00
Author:halw
Date:2008-10-31T21:13:55.000000Z git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@100 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
halw
@@ -58,13 +58,13 @@ You can obtain information about instances from status reporting functions. Most
|
||||
|
||||
====Operations====
|
||||
|
||||
<eiffel>DATE</eiffel> operations looks like <eiffel>TIME</eiffel> operations:
|
||||
* Setting directly <eiffel>year</eiffel>, <eiffel>month</eiffel>, and <eiffel>day</eiffel> with <eiffel>set_year</eiffel>, <eiffel>set_month</eiffel>, and <eiffel>set_day</eiffel>. Arguments must satisfy the rules of creation. These rules are more complicated than those of <eiffel>TIME</eiffel>. For example it is not allowed to set day to 31 if the current month is April, whereas it is allowed if the month is January. It is the same rules as for make. The same thing for years: It is not allowed to set year to a non-leap year if the current date is February 29th of a leap year. However, two features are available to set month and year even if day is too large: <eiffel>set_month_cut_days</eiffel> and <eiffel>set_year_cut_days</eiffel> will cut day down to the largest value allowed.
|
||||
* Adding years, months and days with features <eiffel>year_add</eiffel>, <eiffel>month_add</eiffel>, and <eiffel>day_add</eiffel>. There is no requirement to add a year or a month. However, these features have to return a correct result, i.e. day is checked before each addition-. Adding one month to August 31st will yield September 30th. 31 is cut to 30 since there are only 30 days in September. Features <eiffel>add</eiffel> and <eiffel>+</eiffel> take an instance of DATE_DURATION in argument and add it to the current date. It is written so that years and months are added first, the days last.(see DATE_DURATION below)
|
||||
* Moving to the next or the previous year, month or day with features <eiffel>year_forth</eiffel>, <eiffel>year_back</eiffel>, <eiffel>month_forth</eiffel>, <eiffel>month_back</eiffel>, <eiffel>day_forth</eiffel>, and <eiffel>day_back</eiffel>. It is the same but faster to use these features rather than those upper (e.g., <eiffel>year_back</eiffel> performs better than <eiffel>year_add (-1)</eiffel> ).
|
||||
* Features <eiffel>relative_duration</eiffel> and <eiffel>definite_duration</eiffel> return the duration between the current date and the argument. The first one returns a result which is canonical (See definitions below), while the second one returns a definite result but may be not canonical.
|
||||
<eiffel>DATE</eiffel> operations look much like those of <eiffel>TIME</eiffel>:
|
||||
* Set <eiffel>year</eiffel>, <eiffel>month</eiffel>, and <eiffel>day</eiffel> with <eiffel>set_year</eiffel>, <eiffel>set_month</eiffel>, and <eiffel>set_day</eiffel>. Arguments must satisfy the rules of creation. These rules are more complicated than those of <eiffel>TIME</eiffel>. For example you cannot set day to 31 if the current month is April, whereas you can if the month is January. These restrictions also apply to <eiffel>make</eiffel>. Similarly for years: you cannot set <eiffel>year</eiffel> to a non-leap year if the current date is February 29th. However, two features are available to set month and year even if day is too large: <eiffel>set_month_cut_days</eiffel> and <eiffel>set_year_cut_days</eiffel> will cut <eiffel>day</eiffel> down to the largest value allowed.
|
||||
* Add years, months and days with features <eiffel>year_add</eiffel>, <eiffel>month_add</eiffel>, and <eiffel>day_add</eiffel>. There is no restriction on adding a year or a month. However, these features have to return a correct result, i.e., the day is checked before each addition. Adding one month to August 31st will yield September 30th. 31 is cut to 30 since there are only 30 days in September. Features <eiffel>add</eiffel> and <eiffel>+</eiffel> take an instance of DATE_DURATION as an argument and add it to the instance of <eiffel>date</eiffel>. It is written so that years and months are added first, the days last.(see DATE_DURATION below)
|
||||
* Move to the next or the previous year, month or day with features <eiffel>year_forth</eiffel>, <eiffel>year_back</eiffel>, <eiffel>month_forth</eiffel>, <eiffel>month_back</eiffel>, <eiffel>day_forth</eiffel>, and <eiffel>day_back</eiffel>. It faster to use these features than the addition commands (e.g., <eiffel>year_back</eiffel> performs better than <eiffel>year_add (-1)</eiffel> ).
|
||||
* Features <eiffel>relative_duration</eiffel> and <eiffel>definite_duration</eiffel> return the duration between the current date and the argument. <eiffel>relative_duration</eiffel> returns a result which is canonical (See definitions below), while <eiffel>definite_duration</eiffel> returns a definite result which may be not canonical.
|
||||
|
||||
For example, date1 is April 20th and date2 is May 28th. Both features will yield instances of DURATION; however, relative_duration will yield 1 month and 8 days whereas definite_duration will yield 38 days.
|
||||
For example, suppose date1 is April 20th and date2 is May 28th. Both features will yield instances of DURATION; however, <eiffel>relative_duration</eiffel> will yield 1 month and 8 days whereas definite_duration will yield 38 days.
|
||||
|
||||
==DATE_TIME==
|
||||
|
||||
@@ -73,12 +73,10 @@ The aim is to gather the time with the date. <eiffel>DATE_TIME</eiffel> is clien
|
||||
====Creation====
|
||||
|
||||
There are several ways to create an instance:
|
||||
* by choosing value for all the attributes of the date and the time (<eiffel>make</eiffel>).
|
||||
* by getting the time from the system (<eiffel>make_now</eiffel>).
|
||||
* by gathering an instance of <eiffel>DATE</eiffel> with an instance of <eiffel>TIME</eiffel> (<eiffel>make_by_date_time</eiffel>).This feature copies only 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, using <eiffel>twin</eiffel>s of the arguments is required.
|
||||
* by encapsulating an instance of <eiffel>DATE</eiffel> (<eiffel>make_by_date</eiffel>). The attribute time is set to the origin, i.e. 0:0:0.
|
||||
|
||||
The attribute date is set with the same reference as the argument (See comment of the previous section).
|
||||
* Choose values for each of the attributes of the date and the time (<eiffel>make</eiffel>).
|
||||
* Get the current date and time from the system (<eiffel>make_now</eiffel>).
|
||||
* Associate an instance of <eiffel>DATE</eiffel> with an instance of <eiffel>TIME</eiffel> (<eiffel>make_by_date_time</eiffel>). {{caution|This feature copies only 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, using <eiffel>twin</eiffel>'s of the arguments is required.}}
|
||||
* Encapsulate an instance of <eiffel>DATE</eiffel> (<eiffel>make_by_date</eiffel>). The attribute time is set to the origin, i.e. 0:0:0. The attribute <eiffel>date</eiffel> is set with the same reference as the argument (See caution just mentioned above).
|
||||
|
||||
====Access====
|
||||
|
||||
@@ -106,15 +104,15 @@ Addition of hours, minutes and seconds are available directly in the class.It ca
|
||||
|
||||
Feature <eiffel>add</eiffel> (or <eiffel>+</eiffel>) takes an instance of <eiffel>DATE_TIME_DURATION</eiffel> as an argument. Internally, <eiffel>add</eiffel> first adds the the date duration, and then the time duration.
|
||||
|
||||
{{note|Adding the time duration first would have yield undesirable results in rare cases such as in this example: the current date/time is August 30th 23:59:59. The duration being added is one month and one second. Applying feature <eiffel>add</eiffel> makes the current date/time October 1st 0:0:0, because the date duration is added first. Adding the time duration first would yield September 30th 0:0:0 ! The same effect would occur with leap years.}}
|
||||
{{info|Adding the time duration first would yield undesirable results in rare cases such as in this example: the current date/time is August 30th 23:59:59. The duration being added is one month and one second. Applying feature <eiffel>add</eiffel> makes the current date/time October 1st 0:0:0, because the date duration is added first. Adding the time duration first would yield September 30th 0:0:0 ! The same effect would occur with leap years.}}
|
||||
|
||||
Feature <eiffel>relative_duration</eiffel> and <eiffel>definite_duration</eiffel> return the duration between the current date (with time) and the argument. <eiffel>relative_duration</eiffel> returns a result which is canonical (see definitions below), while <eiffel>definite_duration</eiffel> returns a result which is definite but may be not canonical.
|
||||
|
||||
==DATE and DATE_TIME==
|
||||
==Obtaining a DATE from a DATE_TIME and vice versa==
|
||||
|
||||
Another way to process would have been to make <eiffel>DATE_TIME</eiffel> inherit from <eiffel>DATE</eiffel>, as long as <eiffel>DATE_TIME</eiffel> is a <eiffel>DATE</eiffel>, with more precision. The choice was to have a client relation between them. Otherwise <eiffel>DATE</eiffel> should have known the existence of <eiffel>DATE_TIME</eiffel>, and many assignment attempts would have been useful in features such as <eiffel>infix +</eiffel>. So <eiffel>DATE_TIME</eiffel> is client of <eiffel>DATE</eiffel>.
|
||||
Because <eiffel>DATE_TIME</eiffel> is a client to class <eiffel>DATE</eiffel>, it is easy enough to ask for the <eiffel>DATE</eiffel> from an instance of <eiffel>DATE_TIME</eiffel> by applying the query <eiffel>date</eiffel>.
|
||||
|
||||
However, it could be useful to mix instances of <eiffel>DATE</eiffel> of <eiffel>DATE_TIME</eiffel>. As <eiffel>DATE_TIME</eiffel> is client of <eiffel>DATE</eiffel> with its attribute <eiffel>date</eiffel>, it is easy to get only the date from instances of <eiffel>DATE_TIME</eiffel>. On the other way features are available to convert objects from <eiffel>DATE</eiffel> to <eiffel>DATE_TIME</eiffel>. In class <eiffel>DATE</eiffel>, feature <eiffel>to_date_time</eiffel> builds an instance of <eiffel>DATE_TIME</eiffel> with the origin of time (0,0,0). In the class DATE_TIME, the creation procedure <eiffel>make_by_date</eiffel> has the same effect. (The same feature exists for duration, replacing origin by zero).
|
||||
You can ask for a new instance of <eiffel>DATE_TIME</eiffel> from a <eiffel>DATE</eiffel> using the query <eiffel>to_date_time</eiffel>. The new instance will have the same date as the target, and have its time set to the origin (0:0:0). A <eiffel>DATE_TIME</eiffel> instance can be initialized with a specific <eiffel>DATE</eiffel> by using <eiffel>DATE_TIME</eiffel>'s creation procedure <eiffel>make_by_date</eiffel>.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -3,63 +3,63 @@
|
||||
[[Property:uuid|64672bd0-b696-0c39-1e30-5ac64aae4a99]]
|
||||
<eiffel>TIME_DURATION</eiffel>, <eiffel>DATE_DURATION</eiffel>, and <eiffel>DATE_TIME_DURATION</eiffel>
|
||||
|
||||
The classes dealing with duration inherit DURATION, which inherits GROUP_ELEMENT and PART_COMPARABLE. 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 (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 <eiffel>TIME</eiffel>, <eiffel>DATE</eiffel>, and <eiffel>DATE_TIME</eiffel>).
|
||||
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 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 <eiffel>TIME_DURATION</eiffel> such as 12:-10:60 is not canonical. to_canonical will return 11:51:0. In <eiffel>DATE_DURATION</eiffel> and <eiffel>DATE_TIME_DURATION</eiffel>, these features are also present.
|
||||
|
||||
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 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 (<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.
|
||||
|
||||
==TIME_DURATION==
|
||||
|
||||
====Creation====
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
====Access====
|
||||
|
||||
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.
|
||||
The query <eiffel>zero</eiffel> returns 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. Is_equal tests equality, = will compare references.
|
||||
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.
|
||||
|
||||
====Element change====
|
||||
|
||||
Set directly hour, minute and second with set_hour, set_minute and set_second. Arguments do not need to satisfy any range rule.
|
||||
Set <eiffel>hour</eiffel>, <eiffel>minute</eiffel>, and <eiffel>second</eiffel> with <eiffel>set_hour</eiffel>, <eiffel>set_minute</eiffel>, and <eiffel>set_second</eiffel>. Arguments do not need to satisfy any range rule.
|
||||
|
||||
====Operations====
|
||||
* Adding hours, minutes and seconds with features hour_add, minute_add and second_add.
|
||||
* <eiffel>TIME_DURATION</eiffel> inherits from GROUP_ELEMENT. infix and prefix +, infix and prefix - are available to compose instances of each other.
|
||||
* Add hours, minutes and seconds with features <eiffel>hour_add</eiffel>, <eiffel>minute_add</eiffel> and <eiffel>second_add</eiffel>.
|
||||
* <eiffel>TIME_DURATION</eiffel> inherits from <eiffel>GROUP_ELEMENT</eiffel>. <eiffel>infix</eiffel> and <eiffel>prefix</eiffel> <eiffel>+</eiffel>, <eiffel>infix</eiffel> and <eiffel>prefix</eiffel> <eiffel>-</eiffel> are available to compose instances of each other.
|
||||
|
||||
====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 <eiffel>TIME_DURATION</eiffel>. 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: <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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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 <eiffel>TIME_DURATION</eiffel> 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 function canonical tests if the duration is canonical or not, the function to_canonical yields a new duration equivalent to the current one and canonical.
|
||||
Durations may be canonical or not canonical (tested using the <eiffel>BOOLEAN</eiffel> query <eiffel>canonical</eiffel>). That means the features <eiffel>hour</eiffel>, <eiffel>minute</eiffel>, and <eiffel>second</eiffel> are included in a particular range, or not. An instance of <eiffel>TIME_DURATION</eiffel> is canonical if:
|
||||
* in the case of a positive duration (> zero), all of the three features have to be positive or 0, <eiffel>minute</eiffel> and <eiffel>second</eiffel> less than 60.
|
||||
* in the case of a negative duration (< zero), all of the three features have to be negative or 0, <eiffel>minute</eiffel> and <eiffel>second</eiffel> strictly greater than -60. The function <eiffel>canonical</eiffel> tests if the duration is canonical or not, the function <eiffel>to_canonical</eiffel> yields a new duration equivalent to the current one and canonical.
|
||||
|
||||
==DATE_DURATION==
|
||||
|
||||
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 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 <eiffel>DATE_DURATION</eiffel> without taking care of this distinction.
|
||||
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 have their attributes <eiffel>year</eiffel>, <eiffel>month</eiffel>, and <eiffel>day</eiffel> 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 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 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 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.
|
||||
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 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?
|
||||
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.
|
||||
* 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.
|
||||
|
||||
===Definite date_duration===
|
||||
===Definite DATE_DURATION===
|
||||
|
||||
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.
|
||||
|
||||
@@ -71,56 +71,57 @@ A definite duration may be canonical or not. It is canonical if the number of da
|
||||
|
||||
====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.
|
||||
Two creation features are available: <eiffel>make</eiffel> takes three arguments (<eiffel>year</eiffel>, <eiffel>month</eiffel>, and <eiffel>day</eiffel>). If year and month are null, the duration will be definite; <eiffel>make_by_days</eiffel> 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.
|
||||
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.
|
||||
Features <eiffel>set_day</eiffel>, <eiffel>set_month</eiffel>, and <eiffel>set_year</eiffel> are available to set one of these three attributes <eiffel>day</eiffel>, <eiffel>month</eiffel>, <eiffel>year</eiffel>.
|
||||
|
||||
====Operation====
|
||||
* Add years, months and days with features year_add, month_add and day_add.
|
||||
* <eiffel>DATE_DURATION</eiffel> inherits from GROUP_ELEMENT. infix and prefix +, infix and prefix - are available to compose instances of each other.
|
||||
* Add years, months and days with features <eiffel>year_add</eiffel>, <eiffel>month_add</eiffel>, and <eiffel>day_add</eiffel>.
|
||||
* <eiffel>DATE_DURATION</eiffel> inherits from <eiffel>GROUP_ELEMENT</eiffel>. <eiffel>infix</eiffel> and <eiffel>prefix</eiffel> <eiffel>+</eiffel>, <eiffel>infix</eiffel> and <eiffel>prefix</eiffel> <eiffel>-</eiffel> 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 <eiffel>DATE</eiffel>, 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 <eiffel>DATE_TIME_DURATION</eiffel>. It will have the same date of the current duration and time set to zero.
|
||||
* <eiffel>to_canonical</eiffel> is used to get a new duration equivalent to the current one and canonical. It needs an argument from class <eiffel>DATE</eiffel>, which is the origin of calculations.
|
||||
* <eiffel>to_definite</eiffel> is used to get a new duration equivalent to the current one and definite. As with the previous feature, one argument is needed. - <eiffel>to_date_time</eiffel> is used to get an instance of <eiffel>DATE_TIME_DURATION</eiffel>. It will have the same date of the current duration and time set to zero.
|
||||
|
||||
==DATE_TIME_DURATION==
|
||||
|
||||
<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 DATE_TIME_DURATION. 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====
|
||||
|
||||
There are still several ways to create an instance:
|
||||
* by choosing values for all the attributes of date and time (make). - by choosing a value for day and values for all the attributes of time. The instance is then definite (make_definite).
|
||||
* by gathering an instance of <eiffel>DATE</eiffel> with an instance of <eiffel>TIME</eiffel> (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 clones is required.
|
||||
* by encapsulating an instance of <eiffel>DATE</eiffel> (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.
|
||||
* Provide values for all the components of date and time (<eiffel>make</eiffel>).
|
||||
* Provide a value for day and values for all the components of time. The instance is then definite (<eiffel>make_definite</eiffel>).
|
||||
* by gathering an instance of <eiffel>DATE</eiffel> with an instance of <eiffel>TIME</eiffel> (<eiffel>make_by_date_time</eiffel>). 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 <eiffel>DATE</eiffel> (<eiffel>make_by_date</eiffel>). The attribute <eiffel>time</eiffel> is set to zero, i.e. 0:0:0. The attribute <eiffel>date</eiffel> 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).
|
||||
<eiffel>seconds_count</eiffel> 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 <eiffel>seconds_count</eiffel>. 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 <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====
|
||||
|
||||
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 <eiffel>TIME_DURATION</eiffel> or <eiffel>DATE_DURATION</eiffel>have to be used.
|
||||
It is possible to change reference of time and date with the features <eiffel>set_time</eiffel> and <eiffel>set_date</eiffel>. To change only one element (for example <eiffel>hour</eiffel>), features from <eiffel>TIME_DURATION</eiffel> or <eiffel>DATE_DURATION</eiffel>have to be used.
|
||||
|
||||
====Operation====
|
||||
* <eiffel>DATE_TIME_DURATION</eiffel> 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 <eiffel>TIME_DURATION</eiffel> or <eiffel>DATE_DURATION</eiffel> have to be used.
|
||||
* <eiffel>DATE_TIME_DURATION</eiffel> inherits from <eiffel>GROUP_ELEMENT</eiffel>. infix and prefix <eiffel>+</eiffel>, infix and prefix <eiffel>-</eiffel> are available to compose instances to each other.
|
||||
* Only <eiffel>day_add</eiffel> is present. To add only one element, features from <eiffel>TIME_DURATION</eiffel> or <eiffel>DATE_DURATION</eiffel> 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 <eiffel>DATE_TIME</eiffel>). 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 attributes 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.
|
||||
* <eiffel>canonical</eiffel> and <eiffel>to_canonical</eiffel> are available in the class. To be canonical an instance of the class must have its attributes <eiffel>time</eiffel> and <eiffel>date</eiffel> 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 <eiffel>DATE_TIME</eiffel>). 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). <eiffel>to_canonical</eiffel> returns a duration equivalent to the current one (for the argument) and canonical.
|
||||
* <eiffel>time_to_canonical</eiffel> looks like <eiffel>to_canonical</eiffel> 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. <eiffel>hour</eiffel> 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 <eiffel>day</eiffel> is also modified to keep the result equivalent to the current duration. <eiffel>time_to_canonical</eiffel> does not need any argument because only time and day are modified.
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user