mirrors/eiffel-org
1
0
Fork 0
mirror of https://github.com/EiffelSoftware/eiffel-org.git synced 2025-12-06 14:52:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

updated to 22.12

Browse Source 
git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@2364 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
eifops
2022-12-22 13:24:07 +00:00
parent 3d4c795faf
commit ee2831d52f
2956 changed files with 63295 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
documentation/22.12/solutions/dates-and-times/eiffeltime/eiffeltime-class-reference.wiki Normal file
View File

@@ -0,0 +1,5 @@
[[Property:title|EiffelTime Class Reference]]
[[Property:weight|2]]
[[Property:uuid|ab08dc65-7d32-f681-d7de-e391081736eb]]
==View the [[ref:libraries/time/reference/index|EiffelTime Class Reference]]==

129
documentation/22.12/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/absolute-time.wiki Normal file
View File

@@ -0,0 +1,129 @@
[[Property:modification_date|Mon, 17 Aug 2020 18:49:38 GMT]]
[[Property:publication_date|Mon, 17 Aug 2020 08:47:20 GMT]]
[[Property:title|Absolute time]]
[[Property:weight|0]]
[[Property:uuid|195849fc-1a9c-d734-2d2b-acae78133886]]
The classes dealing with date and those dealing with time have many similarities. These classes descend from more abstract classes implementing the notion of value ([[ref:libraries/time/reference/time_value_chart|TIME_VALUE]] , [[ref:libraries/time/reference/date_value_chart|DATE_VALUE]] , [[ref:libraries/time/reference/date_time_value_chart|DATE_TIME_VALUE]] ). From this notion come two kinds of heirs which are the absolute notion of time (classes [[ref:libraries/time/reference/date_chart|DATE]] , [[ref:libraries/time/reference/time_chart|TIME]] and [[ref:libraries/time/reference/date_time_chart|DATE_TIME]] ) and the notion of duration (classes [[ref:libraries/time/reference/date_duration_chart|DATE_DURATION]] , [[ref:libraries/time/reference/time_duration_chart|TIME_DURATION]] , [[ref:libraries/time/reference/date_time_duration_chart|DATE_TIME_DURATION]] ).
[[ref:libraries/time/reference/date_chart|DATE]] , [[ref:libraries/time/reference/time_chart|TIME]] and [[ref:libraries/time/reference/date_time_chart|DATE_TIME]] inherit from the deferred class [[ref:libraries/time/reference/absolute_chart|ABSOLUTE]]. These classes model absolute temporal values, i.e., specific times and dates. Because <eiffel>ABSOLUTE</eiffel> inherits from <eiffel>COMPARABLE</eiffel>, the ordering functions <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code> are available on instances of [[ref:libraries/time/reference/absolute_chart|ABSOLUTE]] and its descendants.
{{Note|The associated library "time" (also "time_german" and "time_french") are part of the distribution located at $ISE_LIBRARY\library\time\time.ecf and is also available by linking with the IRON repository.}}
==TIME==
[[ref:libraries/time/reference/time_chart|TIME]] models times of day, supporting queries: <eiffel>hour</eiffel>, <eiffel>minute</eiffel>, and <eiffel>second</eiffel>. It is possible to use more precision for time. However, this section deals with precision only to the second. See [[More precision]] for additional information on higher precision.
====Creation====
There are three ways to create an instance of the class <eiffel>TIME</eiffel>: by choosing the time (<eiffel>make</eiffel>), by getting the time from the system (<eiffel>make_now</eiffel>), or by choosing the number of seconds elapsed from the origin (<eiffel>make_by_seconds</eiffel>). The arguments of <eiffel>make</eiffel> and <eiffel>make_by_seconds</eiffel> have to respect the range of a day (see preconditions).
====Origin and cyclic representation====
The origin for instances of <eiffel>TIME</eiffel> is 0 hour 0 minute and 0 second. The notion of time is relative to a day, and has a cyclic representation. So, days begin at 0:0:0 and end at 23:59:59. If a second is added to 23:59:59 then the result will be 0:0:0. Subtracting a minute from 0:0:0 will yield 23:59:0.
====Comparison====
Instances of [[ref:libraries/time/reference/time_chart|TIME ]] may be compared. Functions <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code> are available for ordering instances. Function <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>) can be used to test object equality, whereas <eiffel>=</eiffel> will compare references.
====Measurement====
The query <eiffel>duration</eiffel> applied to an instance of [[ref:libraries/time/reference/time_chart|TIME ]] returns an instance of [[ref:libraries/time/reference/time_duration_chart|TIME_DURATION]]. It is the duration from the origin until the current time.
The query <eiffel>seconds</eiffel> returns the total number of seconds since the origin. This query may be useful to get the number of seconds between two events.
The feature <eiffel>-</eiffel> returns an [[Interval]] between two instances of <eiffel>TIME</eiffel>. The duration of this interval is given by the function <eiffel>duration</eiffel>. However, this duration is non-canonical (See [[Duration|Duration]] for a definition of canonical form). In <eiffel>TIME</eiffel>, the feature <eiffel>relative_duration</eiffel> returns the same duration, but more efficiently and in canonical form.
====Operations====
* Set values for <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 must satisfy the rules of creation.
* Add hours, minutes, and seconds with features <eiffel>hour_add</eiffel>, <eiffel>minute_add</eiffel>, and <eiffel>second_add</eiffel>. Features <eiffel>add</eiffel> and <eiffel>+</eiffel> take an instance of TIME_DURATION as an argument and add it to the current time.
* Adjust an instance of <eiffel>TIME</eiffel> to the next or the previous hour, minute, or second with features <eiffel>hour_forth</eiffel>, <eiffel>hour_back</eiffel>, <eiffel>minute_forth</eiffel>, <eiffel>minute_back</eiffel>, <eiffel>second_forth</eiffel>, and <eiffel>second_back</eiffel>. It is more efficient to use these features rather than the addition commands listed above (e.g., <eiffel>hour_back</eiffel> will outperform <eiffel>hour_add (-1)</eiffel> ).
==DATE==
<eiffel>DATE</eiffel> models dates, and supports queries <eiffel>year</eiffel>, <eiffel>month</eiffel> and <eiffel>day</eiffel>. Working with dates is more complicated than working with times of day because of the irregularities in elements of dates. Months, for example, have varying numbers of days. The number of days in a year varies between non-leap years and leap years. The only limit to magnitude for dates comes from INTEGER representation. If, as in most cases, INTEGER size is 32 bits, the range for a date is -2^31 to 2^31 days, or about 5.8 million years from the origin. So, unless you're trying to determine if the "big bang" occurred on a Tuesday, this should probably be adequate.
====Creation====
There are three ways to create an instance of the class <eiffel>DATE</eiffel>: by choosing the date (<eiffel>make</eiffel>, <eiffel>make_month_day_year</eiffel>, <eiffel>make_day_month_year</eiffel>), by getting the date from the system (<eiffel>make_now</eiffel>), or by choosing the number of days elapsed from the origin (<eiffel>make_by_days</eiffel>). The arguments of each creation procedure, when considered together, must represent a valid date. For example, a month of February and day of 29 will be invalid if the value for the year is not a leap year.
====Origin====
The origin for instances of <eiffel>DATE</eiffel> is January 1, 1600.
====Comparison====
Instances of <eiffel>DATE</eiffel> may be compared. Functions <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code> are available for ordering instances by value. Function <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>) can be used to test object equality, while <eiffel>=</eiffel> will compare references.
====Measurement====
Each instance of <eiffel>DATE</eiffel> has a function (<eiffel>duration</eiffel>) which returns the duration since the origin until the current date (it is an instance of DATE_DURATION). This duration is definite, i.e. it contains only days (See [[Duration]]). However, it may be useful to deal directly with days (no need of DATE_DURATION). In this case, the function <eiffel>days</eiffel> of <eiffel>DATE</eiffel> yields the number of days since origin.
====Status Report====
You can obtain information about instances from status reporting queries. Some examples are:
* <eiffel>leap_year</eiffel> is <eiffel>True</eiffel> if the instance is a leap year.
* <eiffel>year_day</eiffel> returns the number of days from the beginning of the year to this instance. So, for example, for the date January 31, <eiffel>year_day</eiffel> would return 31. For February 1, <eiffel>year_day</eiffel> would return 32.
* <eiffel>day_of_the_week</eiffel> returns the number of days the instance is from the beginning of the week. Values range from 1 (Sunday) through 7 (Saturday).
====Operations====
<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 more efficient 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 [[Duration]]), while <eiffel>definite_duration</eiffel> returns a definite result which may be not canonical.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==
[[ref:libraries/time/reference/date_time_chart|DATE_TIME]] provides a combined date and time. <eiffel>DATE_TIME</eiffel> is client of both <eiffel>TIME</eiffel> and <eiffel>DATE</eiffel>. Some features from <eiffel>DATE</eiffel> and <eiffel>TIME</eiffel> are offered directly as features of <eiffel>DATE_TIME</eiffel>. Other features of <eiffel>DATE</eiffel> and <eiffel>TIME</eiffel> may be called indirectly with the correct <eiffel>DATE_TIME</eiffel> attribute (<eiffel>time</eiffel> or <eiffel>date</eiffel>).
====Creation====
There are several ways to create an instance:
* 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|The creation procedure <eiffel>make_by_date_time</eiffel> 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).
====Origin====
The origin for instances of <eiffel>DATE_TIME</eiffel> is 0:0:0 on January 1, 1600.
====Access====
An instance of <eiffel>DATE_TIME</eiffel> has attributes which are instances of classes <eiffel>TIME</eiffel> and <eiffel>DATE</eiffel>, respectively. As a convenience, some features of <eiffel>TIME</eiffel> and <eiffel>DATE</eiffel> have been made available directly as features of <eiffel>DATE_TIME</eiffel> (and passed through to <eiffel>time</eiffel> and <eiffel>date</eiffel>). These include <eiffel>days</eiffel>, <eiffel>seconds</eiffel>, <eiffel>duration</eiffel>, <eiffel>date_duration</eiffel>, and <eiffel>time_duration</eiffel>.
====Comparison====
Instances of <eiffel>DATE_TIME</eiffel> can be compared. Functions <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code> are available for ordering instance by value. Function <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>) is used to test object equality, while <eiffel>=</eiffel> compares references.
====Measurement====
<eiffel>duration</eiffel> returns an instance of <eiffel>DATE_TIME_DURATION</eiffel> which represents the duration of time between the instance and the origin.
====Element change====
It is possible to change reference of <eiffel>time</eiffel> and <eiffel>date</eiffel> 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</eiffel> or <eiffel>DATE</eiffel> have to be used.
====Operations====
Add hours, minutes, and seconds with features <eiffel>hour_add</eiffel>, <eiffel>minute_add</eiffel>, and <eiffel>second_add</eiffel>.
{{caution|Using the addition features from <eiffel>TIME</eiffel> on the <eiffel>time</eiffel> attribute is also possible but the date will not be modified in the case <eiffel>time</eiffel> makes a cycle. So, for example use:<eiffel> my_date_time.hour_add (more_hours)</eiffel> instead of: <eiffel>my_date_time.time.hour_add (more_hours)</eiffel> }}
<eiffel>day_add</eiffel> is available on instances of <eiffel>DATE_TIME</eiffel> to add days.
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.
{{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 [[Duration]]), while <eiffel>definite_duration</eiffel> returns a result which is definite but may be not canonical.
==Obtaining a DATE from a DATE_TIME and vice versa==
Obtaining an instance of <eiffel>DATE</eiffel> which represents the date portion of an instance of <eiffel>DATE_TIME</eiffel> can be done by applying the query <eiffel>date</eiffel> to the instance of <eiffel>DATE_TIME</eiffel>.
You can ask for a new instance of <eiffel>DATE_TIME</eiffel> from an instance of <eiffel>DATE</eiffel> by 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>.

110
documentation/22.12/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/date-time-string-conversion.wiki Normal file
View File

@@ -0,0 +1,110 @@
[[Property:title|DATE TIME to STRING Conversion]]
[[Property:weight|3]]
[[Property:uuid|88972ba4-694b-8558-b0c8-87b1fc40afc4]]
The classes <eiffel>TIME</eiffel>, <eiffel>DATE</eiffel>, and <eiffel>DATE_TIME</eiffel> provide a query <eiffel>formatted_out</eiffel> which can be used to retrieve a string containing the date or time in a format specified by a string or format conversion codes that the caller provides as an argument. The conversion is done in the <eiffel>DATE_TIME_CODE_STRING</eiffel> class. So for example, if a <eiffel>DATE</eiffel> instance referenced by <eiffel>my_date</eiffel> has a value of February 3, 2008, then applying the query:
<eiffel>
my_date.formatted_out ("[0]dd mmm yyyy")
</eiffel>
will return the string:
<code lang=text>
03 FEB 2008
</code>
The following table lists format conversion codes.
{|
|-
| '''Code'''
| '''Description'''
|-
| dd
| day - numeric
|-
| <nowiki>[0]dd</nowiki>
| day - numeric (padded with '0' to 2 figures)
|-
| ddd
| day - text (3 letters e.g "MON", "TUE")
|-
| yyyy
| year - numeric (4 figures)
|-
| yy
| year - numeric (2 figures)
|-
| mm
| month - numeric
|-
| <nowiki>[0]mm</nowiki>
| month - numeric (padded with '0' to 2 figures)
|-
| mmm
| month - text (3 letters e.g "DEC", "JAN")
|-
| hh
| hour - numeric (24 hour clock scale by default)
|-
| <nowiki>[0]hh</nowiki>
| hour - numeric (padded with '0' to 2 figures)
|-
| hh12
| hour - numeric (12 hour clock scale)
|-
| mi
| minute - numeric
|-
| <nowiki>[0]mi</nowiki>
| minute - numeric (padded with '0' to 2 figures)
|-
| ss
| seconds - numeric
|-
| <nowiki>[0]ss</nowiki>
| seconds - numeric (padded with '0' to 2 figures)
|-
| ff<n>
| fractional seconds - numeric (precise to <n> figures)
|-
| am
| meridiem indicator. Includes "AM" for ante meridiem times (before noon) and "PM" for post meridiem times (after noon).
|-
| ':', '/', '-' and ','
| separators e.g. "03/FEB/08"
|}
These are some examples of output with their associated format code:
{|
|-
| '''Code'''
| '''Output'''
|-
| yy/mm/dd
| 08/2/3
|-
| <nowiki>mmm-[0]dd-yy</nowiki>
| FEB-03-08
|-
| dd,mm,yyyy
| 3,2,2008
|-
| hh-mi-ss
| 13-6-32
|-
| hh12,mi,ss
| 1,6,32
|-
| <nowiki>hh12:[0]mi:[0]ss:ff2 am</nowiki>
| 1:06:32.25 PM
|-
| <nowiki>[0]hh:[0]mi:[0]ss.ff3</nowiki>
| 13:06:32.248
|-
| <nowiki>[0]mm/dd/yy hh12:mi:ss.ff3</nowiki>
| 02/3/08 1:6:32.248
|}

152
documentation/22.12/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/duration.wiki Normal file
View File

@@ -0,0 +1,152 @@
[[Property:title|Duration]]
[[Property:weight|1]]
[[Property:uuid|64672bd0-b696-0c39-1e30-5ac64aae4a99]]
The classes <eiffel>TIME_DURATION</eiffel>, <eiffel>DATE_DURATION</eiffel>, and <eiffel>DATE_TIME_DURATION</eiffel> model time durations.
The classes dealing with duration inherit from <eiffel>DURATION</eiffel>, which in turn inherits from <eiffel>GROUP_ELEMENT</eiffel> and <eiffel>PART_COMPARABLE</eiffel>. From this lineage comes the query <eiffel>zero</eiffel>, the addition features <eiffel>infix +</eiffel> and <eiffel>infix -</eiffel> and the unary features <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 So, <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> in [[Absolute time]].
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 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 <eiffel>TIME_DURATION</eiffel>, the value of <eiffel>second</eiffel> will be in 0..59). 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>.
Ordering is partial for <eiffel>DATE_DURATION</eiffel> and <eiffel>DATE_TIME_DURATION</eiffel> for reasons explained below, and total for <eiffel>TIME_DURATION</eiffel>.
==TIME_DURATION==
====Creation====
Instances can be created either by specifying a value for each of the attributes <eiffel>hour</eiffel>, <eiffel>minute</eiffel>, and <eiffel>second</eiffel> (<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> 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. 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 <code><</code>, <code>></code>, <code><=</code>, and <code>>=</code> are available. The <eiffel>BOOLEAN</eiffel> query <eiffel>is_equal</eiffel> (or the object equality operator <eiffel>~</eiffel>) tests object equality, <eiffel>=</eiffel> will compare references.
====Element change====
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====
* Add hours, minutes and seconds with features <eiffel>hour_add</eiffel>, <eiffel>minute_add</eiffel> and <eiffel>second_add</eiffel>.
* <eiffel>infix</eiffel> <eiffel>+</eiffel> and <eiffel>infix</eiffel> <eiffel>-</eiffel> are available for producing sums and differences of durations.
* <eiffel>prefix</eiffel> <eiffel>-</eiffel> is available for producing the inverse of a duration.
====Conversion====
Two features provide a conceptual 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 second 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.
{{sample|Suppose the value of an instance of <eiffel>TIME_DURATION</eiffel> is 25:70:600. Then applying <eiffel>to_days</eiffel> will return 1 (one day) and applying <eiffel>time_modulo_day</eiffel> will return 2:20:0. Now suppose that the value of the <eiffel>TIME_DURATION</eiffel> is negative, say -23:-80:300. In this case, applying <eiffel>to_days</eiffel> will return -2 (minus two days) and <eiffel>time_modulo_day</eiffel> will return 23:45:0.}}
Durations may be in canonical or non-canonical form. This can be tested using the <eiffel>BOOLEAN</eiffel> query <eiffel>canonical</eiffel>. Canonical form depends upon whether the features <eiffel>hour</eiffel>, <eiffel>minute</eiffel>, and <eiffel>second</eiffel> have values that fall into a particular range. 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.
Two queries help you work with canonical form:
* The value of the query <eiffel>canonical</eiffel> is <eiffel>True</eiffel> if duration is in canonical form.
* The query <eiffel>to_canonical</eiffel> yields a new, canonical <eiffel>TIME_DURATION</eiffel> equivalent to the duration to which it is applied.
==DATE_DURATION==
<eiffel>DATE_DURATION</eiffel> is similar to <eiffel>TIME_DURATION</eiffel>, 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 <eiffel>DATE_DURATION</eiffel> 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 <eiffel>True</eiffel> for definite date durations and false for relative date durations.
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 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 <eiffel>DATE_DURATION</eiffel>, there is no ambiguity: a given number of days is added to the date. In the case of a relative <eiffel>DATE_DURATION</eiffel>, the result is relative to the duration's <eiffel>origin_date</eiffel>. 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 (<code>></code> or <code><</code>) is applied in a state in which either the current instance or the argument or both are relative durations, the result will be always <eiffel>False</eiffel>.
We are able to determine if two durations have equal value by applying the feature <eiffel>is_equal</eiffel> (or the object equality operator <eiffel>~</eiffel>).
When adding a relative <eiffel>DATE_DURATION</eiffel> to a <eiffel>DATE</eiffel>, 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 <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.
===About ''definite'' DATE_DURATIONs===
Definite durations are characterized by the attribute <eiffel>day</eiffel>. Whenever a duration has its attributes <eiffel>year</eiffel> and <eiffel>month</eiffel> 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: <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 <code><</code>, <code>></code>, <code><=</code>, and <code>>=</code> 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 <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>.
====Operations====
* 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====
* <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 <eiffel>canonical</eiffel> and <eiffel>to_canonical</eiffel> 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:
* 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====
<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 <code><</code>, <code>></code>, <code><=</code>, and <code>>=</code> 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 <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.
====Operations====
* <eiffel>DATE_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 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====
* <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.

23
documentation/22.12/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/index.wiki Normal file
View File

@@ -0,0 +1,23 @@
[[Property:title|EiffelTime Tutorial]]
[[Property:weight|0]]
[[Property:uuid|2c1bfedd-d515-cd6b-bd22-b06326fc98d8]]
The library EiffelTime is designed to provide software components for the effective modeling and manipulation of ''dates and times''. EiffelTime is built on three notions of time:
* ''Absolutes'' are used to denote specific times. For example, an absolute time would be used to denote a particular event, like the starting time for a meeting, say 3:45 p.m.
* ''Intervals'' denote the interval between events. So, an interval could express the fact that the meeting will run from 3:45 p.m. until 6:00 p.m.
* ''Durations'' are used to represent the length of an interval. So, a duration can express the fact that the meeting lasts for 2 hours and 15 minutes.
As you read this documentation you will notice other concepts that are used in various classes. Here are some examples:
* There is a concept of ''origin'' which allows absolute instances to have an anchor in time. The origin for an absolute time is 00:00:00, the earliest time of day. The origin for dates is January 1, 1600. A similar notion, origin date, is used with certain date durations.
* Durations can be in ''canonical'' or ''non-canonical'' form. Canonical form means that the values for components of the duration fall into the expected range for each component. So, for example a time duration with a value for minutes that is larger than 59 would be in non-canonical form.
* Date durations can be ''relative'' or ''definite''. Definite date durations consist only of a number of days. Relative date durations can have values for a number of years and months. As you will see, comparison and arithmetic are affected by whether date durations are relative or definite.
You will read more about these and other EiffelTime concepts in the detailed pages that follow.
{{note|When you use [[EiffelStudio: Project settings window|project settings]] to [[Adding a library|add]] the EiffelTime library, you will see that there are library choices for different default formatting. The default EiffelTime library uses English formatting by default. However, you can choose the option that uses German or French default formatting by selecting the library whose name contains "german" or "french". }}

41
documentation/22.12/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/interval.wiki Normal file
View File

@@ -0,0 +1,41 @@
[[Property:title|Interval]]
[[Property:weight|2]]
[[Property:uuid|d33d0216-fa71-60dc-f3b0-61ff42d621e6]]
Class <eiffel>INTERVAL [G -> ABSOLUTE]</eiffel> deals with intervals between two instances of the same class (an actual generic parameter substituting for <eiffel>G</eiffel>) which conforms to<eiffel> ABSOLUTE</eiffel> (specifically: <eiffel>DATE</eiffel>, <eiffel>TIME</eiffel>, <eiffel>DATE_TIME</eiffel>).
====Creation====
The creation procedure <eiffel>make (s, e: G)</eiffel> takes as arguments two instances of type <eiffel>G</eiffel> (or <eiffel>G</eiffel>'s actual type from a declaration, e.g., <eiffel>my_time_interval: INTERVAL [TIME]</eiffel> ), which will become the start bound and the end bound of the <eiffel>INTERVAL</eiffel>. The start bound argument must be "before" the end bound argument (i.e., <eiffel>s <= e</eiffel>). <eiffel>make</eiffel> creates twins of its arguments so that the objects referenced as arguments will not change even if the values in the <eiffel>INTERVAL</eiffel> change.
====Interval measurement====
The measurement of an interval is done by applying the query <eiffel>duration</eiffel>. Although the result of <eiffel>duration</eiffel> will be an instance of class <eiffel>DURATION</eiffel>, it will be a direct instance of the <eiffel>DURATION</eiffel> descendant that is appropriate to the actual value of the generic parameter <eiffel>G</eiffel>. So, for an <eiffel>INTERVAL [TIME]</eiffel>, the result of <eiffel>duration</eiffel> will be a direct instance of <eiffel>TIME_DURATION</eiffel>.
====Comparison====
* <eiffel>infix <</eiffel> and <eiffel>infix ></eiffel> compare two intervals on a "strict" basis. This means that <eiffel>int_1 < int_2</eiffel> is <eiffel>True</eiffel> if <eiffel>int_1</eiffel> starts and ends strictly before <eiffel>int_2</eiffel>. In other words, <eiffel>int_1</eiffel> must have a start bound less than that of <eiffel>int_2</eiffel> and an end bound less than that of <eiffel>int_2</eiffel>.
* <eiffel>infix <=</eiffel> and <eiffel>infix >=</eiffel> compare two intervals on a non-strict basis. So, <eiffel>int_1 <= int_2</eiffel> is <eiffel>True</eiffel> if <eiffel>int_1</eiffel> has a start bound less than or equal to that of <eiffel>int_2</eiffel> and an end bound less than or equal to that of <eiffel>int_2</eiffel>.
* <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>)performs object comparison.
* <eiffel>intersects</eiffel> is true if one (target) <eiffel>INTERVAL</eiffel> shares some of the same bounded area with a second (argument) <eiffel>INTERVAL</eiffel>.
* <eiffel>overlaps</eiffel> is similar to <eiffel>intersects</eiffel> with the exception that the argument <eiffel>INTERVAL</eiffel> has to be after the target <eiffel>INTERVAL</eiffel>. <eiffel>is_overlapped</eiffel> is the opposite of <eiffel>overlaps</eiffel>.
* <eiffel>meets</eiffel> and <eiffel>is_met</eiffel> are used to test whether two intervals have a common bound.
* <eiffel>strict_includes</eiffel> can be used to test whether the target <eiffel>INTERVAL</eiffel> strictly includes the argument <eiffel>INTERVAL</eiffel>. So, <eiffel> int_1.strict_includes (int_2) </eiffel> will be <eiffel>True</eiffel> if the start bound of <eiffel>int_2</eiffel> is greater than the start bound of <eiffel>int_1</eiffel> and the end bound of <eiffel>int_2</eiffel> is less than the end bound of <eiffel>int_1</eiffel>. <eiffel>is_strict_included_by</eiffel> provides the opposite of <eiffel>strict_includes</eiffel>.
* <eiffel>includes</eiffel> and <eiffel>is_included_by</eiffel> test for inclusion on a non-strict basis.
====Status Report====
* <eiffel>empty</eiffel> is <eiffel>True</eiffel> if the <eiffel>INTERVAL</eiffel> is empty, i.e., if the value of the start bound is equal to the value of the end bound.
* <eiffel>has</eiffel>, <eiffel>strict_before</eiffel>, <eiffel>strict_after</eiffel>, <eiffel>before</eiffel>, and <eiffel>after</eiffel> test the position of an element relative to the current interval.
====Element change====
<eiffel>set_start_bound</eiffel> and <eiffel>set_end_bound</eiffel> are available to change the bounds. <eiffel>set_start_bound</eiffel> and <eiffel>set_end_bound</eiffel> create new objects from their arguments (twins), so that if these bounds are altered later, the original objects which had been referenced as arguments will not change.
====Operations====
* <eiffel>union</eiffel> provides a new <eiffel>INTERVAL</eiffel> that includes the entire range covered by both the target <eiffel>INTERVAL</eiffel> and an argument <eiffel>INTERVAL</eiffel> which intersects the target.
* <eiffel>intersection</eiffel> returns a new <eiffel>INTERVAL</eiffel> that represents the area common to both the target <eiffel>INTERVAL</eiffel> and the argument <eiffel>INTERVAL</eiffel>. <eiffel>intersection</eiffel> returns <eiffel>Void</eiffel> if the target and argument do not intersect.
* <eiffel>gather</eiffel> requires that a target and argument <eiffel>INTERVAL</eiffel> have a common bound (i.e., <eiffel> int_1.meets (int_2) </eiffel> is <eiffel>True</eiffel>) and then returns a new <eiffel>INTERVAL</eiffel> with the union of the two.

42
documentation/22.12/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/more-precision.wiki Normal file
View File

@@ -0,0 +1,42 @@
[[Property:title|More precision]]
[[Property:weight|4]]
[[Property:uuid|fadf5bc2-bb72-f681-b9c4-bab7f0633209]]
The classes <eiffel>TIME</eiffel> and <eiffel>TIME_DURATION</eiffel> are designed to deal with time in high precision, limited only by platform numerical representation.
The classes <eiffel>TIME</eiffel> and <eiffel>TIME_DURATION</eiffel> have an attribute <eiffel>fine_second</eiffel> of type <eiffel>DOUBLE</eiffel> which allows high precision. This attribute represents the number of seconds with fractions. From <eiffel>fine_second</eiffel> are calculated the values for <eiffel>second</eiffel> and <eiffel>fractional_second</eiffel>. <eiffel>second</eiffel> is the truncated-to-integer part of <eiffel>fine_second</eiffel> and <eiffel>fractional_second</eiffel> is the fractional part of <eiffel>fine_second</eiffel>.
When <eiffel>fine_second</eiffel> is positive, 3.55 for example, <eiffel>second</eiffel> and <eiffel>fractional_second</eiffel> are both positive (3 and 0.55, respectively). When <eiffel>fine_second</eiffel> is negative (- 3.55 for example), then <eiffel>second</eiffel> and <eiffel>fractional_second</eiffel> are both negative (- 3 and - 0.55).
Manipulation on second and fractional_second are in fact always made through fine_second. Users who do not want to deal with precision do not need to care about this.
Features dealing with <eiffel>fine_second</eiffel> and <eiffel>fractional_second</eiffel> are described here.
====Creation (common to <eiffel>TIME, </eiffel> <eiffel>TIME_DURATION</eiffel>)====
* <eiffel>make_fine</eiffel> is similar to <eiffel>make</eiffel> except that it takes a <eiffel>DOUBLE</eiffel> for its third argument (instead of an <eiffel>INTEGER</eiffel>, as is the case with <eiffel>make</eiffel>). <eiffel>fine_second</eiffel> is then set to this value.
* <eiffel>make_by_fine_seconds</eiffel> is similar to <eiffel>make_by_seconds</eiffel> except that it takes a <eiffel>DOUBLE</eiffel> for an argument (instead of an <eiffel>INTEGER</eiffel>, as is the case with<eiffel>make_by_seconds</eiffel>).
====Measurement and access====
In <eiffel>TIME</eiffel>:
* <eiffel>fine_seconds</eiffel> looks like seconds but it contains fractions.
In <eiffel>TIME_DURATION</eiffel>:
* <eiffel>fine_seconds_count</eiffel> looks like <eiffel>seconds_count</eiffel> but it contains fractions.
====Element change====
* Set <eiffel>fine_second</eiffel> directly with <eiffel>set_fine_second</eiffel>.
* Set <eiffel>fractional_second</eiffel> directly with <eiffel>set_fractionals</eiffel>.
{{note|Use of the feature <eiffel>set_second</eiffel> (in either <eiffel>TIME</eiffel> and <eiffel>TIME_DURATION</eiffel>) will result in <eiffel>fractional_second</eiffel> having a value of zero. }}
====Operations====
* <eiffel>fine_second_add</eiffel> looks like <eiffel>second_add</eiffel> except that it takes a <eiffel>DOUBLE</eiffel> as an argument.

8
documentation/22.12/solutions/dates-and-times/eiffeltime/index.wiki Normal file
View File

@@ -0,0 +1,8 @@
[[Property:title|EiffelTime]]
[[Property:weight|9]]
[[Property:uuid|3d96626f-11f3-67a2-dec6-69f7faf4a8d6]]
==EiffelTime Library==
Type: Library <br/>
Platform: Any

10
documentation/22.12/solutions/dates-and-times/index.wiki Normal file
View File

@@ -0,0 +1,10 @@
[[Property:modification_date|Mon, 17 Aug 2020 18:50:21 GMT]]
[[Property:publication_date|Mon, 17 Aug 2020 08:39:17 GMT]]
[[Property:title|Dates and times]]
[[Property:weight|-13]]
[[Property:uuid|082fd8e1-b531-6cf1-3409-9cd9bc6483ad]]
== Date and time manipulation solutions==
{{Note|The associated library "time" (also "time_german" and "time_french") are part of the distribution located at $ISE_LIBRARY\library\time\time.ecf and is also available by linking with the IRON repository.}}