diff --git a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/absolute-time.wiki b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/absolute-time.wiki index 8b377f20..3ee83fcc 100644 --- a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/absolute-time.wiki +++ b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/absolute-time.wiki @@ -32,7 +32,7 @@ The feature - returns an [[Interval]] between two instances of ====Operations==== * Set values for hour, minute, and second with set_hour, set_minute, and set_second. Arguments must satisfy the rules of creation. * Add hours, minutes, and seconds with features hour_add, minute_add, and second_add. Features add and + take an instance of TIME_DURATION as an argument and add it to the current time. -* Adjust an instance of TIME to the next or the previous hour, minute, or second with features hour_forth, hour_back, minute_forth, minute_back, second_forth, and second_back. It is more efficient to use these features rather than those above (e.g., hour_back will outperform hour_add (-1) ). +* Adjust an instance of TIME to the next or the previous hour, minute, or second with features hour_forth, hour_back, minute_forth, minute_back, second_forth, and second_back. It is more efficient to use these features rather than the addition commands listed above (e.g., hour_back will outperform hour_add (-1) ). ==DATE== @@ -44,7 +44,7 @@ There are three ways to create an instance of the class DATE: b ====Origin==== -The origin for dates is 01/01/1600. +The origin for instances of DATE is January 1, 1600. ====Comparison==== @@ -56,41 +56,47 @@ Each instance of DATE has a function (duration ====Status Report==== -You can obtain information about instances from status reporting functions. Most of these queries are used within the class, but they are also exported for use by clients. +You can obtain information about instances from status reporting queries. Some examples are: +* leap_year is True if the instance is a leap year. +* year_day returns the number of days from the beginning of the year to this instance. So, for example, for the date January 31, year_day would return 31. For February 1, year_day would return 32. +* day_of_the_week returns the number of days the instance is from the beginning of the week. Values range from 1 (Sunday) through 7 (Saturday). ====Operations==== DATE operations look much like those of TIME: * Set year, month, and day with set_year, set_month, and set_day. Arguments must satisfy the rules of creation. These rules are more complicated than those of TIME. 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 make. Similarly for years: you cannot set year 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: set_month_cut_days and set_year_cut_days will cut day down to the largest value allowed. * Add years, months and days with features year_add, month_add, and day_add. 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 add and + take an instance of DATE_DURATION as an argument and add it to the instance of date. 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 year_forth, year_back, month_forth, month_back, day_forth, and day_back. It faster to use these features than the addition commands (e.g., year_back performs better than year_add (-1) ). -* Features relative_duration and definite_duration return the duration between the current date and the argument. relative_duration returns a result which is canonical (See definitions below), while definite_duration 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, relative_duration will yield 1 month and 8 days whereas definite_duration will yield 38 days. +* Move to the next or the previous year, month or day with features year_forth, year_back, month_forth, month_back, day_forth, and day_back. It more efficient to use these features than the addition commands (e.g., year_back performs better than year_add (-1) ). +* Features relative_duration and definite_duration return the duration between the current date and the argument. relative_duration returns a result which is canonical (See [[Duration]]), while definite_duration 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, relative_duration will yield 1 month and 8 days whereas definite_duration will yield 38 days. ==DATE_TIME== -The aim is to gather the time with the date. DATE_TIME is client of both TIME and DATE. Some features from DATE and TIME are offered directly as features of DATE_TIME. Other features of DATE and TIME may be called indirectly with the correct DATE_TIME attribute (time or date). +[[ref:libraries/time/reference/date_time_chart|DATE_TIME]] provides a combined date and time. DATE_TIME is client of both TIME and DATE. Some features from DATE and TIME are offered directly as features of DATE_TIME. Other features of DATE and TIME may be called indirectly with the correct DATE_TIME attribute (time or date). ====Creation==== There are several ways to create an instance: * Choose values for each of the attributes of the date and the time (make). * Get the current date and time from the system (make_now). -* Associate an instance of DATE with an instance of TIME (make_by_date_time). {{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 twin's of the arguments is required.}} +* Associate an instance of DATE with an instance of TIME (make_by_date_time). +{{caution|The creation procedure make_by_date_time 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 twin's of the arguments is required.}} * Encapsulate an instance of DATE (make_by_date). 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 caution just mentioned above). +====Origin==== + +The origin for instances of DATE_TIME is 0:0:0 on January 1, 1600. + ====Access==== An instance of DATE_TIME has attributes which are instances of classes TIME and DATE, respectively. As a convenience, some features of TIME and DATE have been made available directly as features of DATE_TIME (and passed through to time and date). These include days, seconds, duration, date_duration, and time_duration. ====Comparison==== -Instances of DATE_TIME are totally ordered (by way of inheritance from ABSOLUTE). Functions <, +, >, and >= are available. Function is_equal (or ~) is used to test object equality, while = compares references. +Instances of DATE_TIME can be compared. Functions <, <=, >, and >= are available for ordering instance by value. Function is_equal (or ~) is used to test object equality, while = compares references. ====Measurement==== -Function duration gathers functions duration from the attributes time and date. The result is an instance of DATE_TIME_DURATION. +duration returns an instance of DATE_TIME_DURATION which represents the duration of time between the instance and the origin. ====Element change==== @@ -109,13 +115,13 @@ Feature add (or +) takes an instance of add 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 relative_duration and definite_duration return the duration between the current date (with time) and the argument. relative_duration returns a result which is canonical (see definitions below), while definite_duration returns a result which is definite but may be not canonical. +Feature relative_duration and definite_duration return the duration between the current date (with time) and the argument. relative_duration returns a result which is canonical (see [[Duration]]), while definite_duration returns a result which is definite but may be not canonical. ==Obtaining a DATE from a DATE_TIME and vice versa== -Because DATE_TIME is a client to class DATE, it is easy enough to ask for the DATE from an instance of DATE_TIME by applying the query date. +Obtaining an instance of DATE which represents the date portion of an instance of DATE_TIME can be done by applying the query date to the instance of DATE_TIME. -You can ask for a new instance of DATE_TIME from a DATE using the query to_date_time. The new instance will have the same date as the target, and have its time set to the origin (0:0:0). A DATE_TIME instance can be initialized with a specific DATE by using DATE_TIME's creation procedure make_by_date. +You can ask for a new instance of DATE_TIME from an instance of DATE by using the query to_date_time. The new instance will have the same date as the target, and have its time set to the origin (0:0:0). A DATE_TIME instance can be initialized with a specific DATE by using DATE_TIME's creation procedure make_by_date. diff --git a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/index.wiki b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/index.wiki index 02afafe4..ce1bc6d6 100644 --- a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/index.wiki +++ b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/index.wiki @@ -17,6 +17,6 @@ As you read this documentation you will notice other concepts that are used in v You will read more about these and other EiffelTime concepts in the detailed pages that follow. -One more thing you should know about EiffelTime is that the cluster contains subclusters which allow the library to support either classic or .NET targets, and provide default formatting of dates and times in either English, French, or German style formats. This means that if you just add the ''time'' cluster to your project as a cluster with the default recursive directory searching, you will get configuration errors stating that multiple classes were found with the same name. So in EiffelStudio settings, you need to specify the subclusters that best fit your application's needs. +One more thing you should know about EiffelTime is that the cluster contains subclusters which allow the library to support either classic or .NET targets, and provide default formatting of dates and times in either English, French, or German style formats. This means that if you just add the ''time'' cluster to your project as a cluster with the default recursive directory searching, you will get configuration errors stating that multiple classes were found with the same name. So in the EiffelStudio project settings, you need to specify the subclusters that best fit your application's needs.