From ddca99dbe757993019cffa662c5d6215af7b87f7 Mon Sep 17 00:00:00 2001 From: halw Date: Thu, 30 Oct 2008 19:34:58 +0000 Subject: [PATCH] Author:halw Date:2008-10-30T19:34:58.000000Z git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@99 abb3cda0-5349-4a8f-a601-0c33ac3a8c38 --- .../eiffeltime-tutorial/absolute-time.wiki | 36 +++++++++++-------- 1 file changed, 21 insertions(+), 15 deletions(-) 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 4e3a5ca5..83197c9c 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 @@ -68,47 +68,53 @@ For example, date1 is April 20th and date2 is May 28th. Both features will yield ==DATE_TIME== -The aim is to gather the time with the date. DATE_TIME is client of both TIME and DATE (see inheritance relation). Some features from DATE and TIME are re-written since they are useful within the class. Many other features may be called indirectly with the correct attribute (time or date). +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). ====Creation==== -There are still several ways to create an instance: -* by choosing value for all the attributes of the date and the time (make). -* by getting the time from the system (make_now). -* by gathering an instance of DATE with an instance of TIME (make_by_date_time).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, cloning the arguments is required. -* by encapsulating an instance of DATE (make_by_date). The attribute time is set to the origin, i.e. 0:0:0. +There are several ways to create an instance: +* by choosing value for all the attributes of the date and the time (make). +* by getting the time from the system (make_now). +* by gathering an instance of DATE with an instance of TIME (make_by_date_time).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 twins of the arguments is required. +* by encapsulating 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 comment of the previous section). ====Access==== -To make it easier calls to features of TIME and DATE, the most useful access features are written as features in DATE_TIME (days, seconds and their associated duration date_duration and time_duration). +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 (the class inherit from ABSOLUTE). Functions <, +, >, and >= are available. Function is_equal or ~ is used to test object equality. = will compare references. +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. ====Measurement==== -Function duration gathers functions duration from the attributes time and date. The result is an instance of DATE_TIME_DURATION. +Function duration gathers functions duration from the attributes time and date. The result is an instance of DATE_TIME_DURATION. ====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 TIME or DATE have to be used. +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 TIME or DATE have to be used. ====Operations==== -Addition of hours, minutes and seconds are available directly in the class.The reason is that adding one second may have a consequence on the date. Using second_add from TIME is also possible but the date will not be modified in the case time makes a cycle. It is of course the same for minute and hour. day_add is also available directly since it is frequently used within the class. +Addition of hours, minutes and seconds are available directly in the class.It can be important to use the versions from DATE_TIME, because adding time to a DATE_TIME may have a consequence on the date. -Features + and add take an instance of DATE_TIME_DURATION in arguments. The date duration is added first then the time duration. Adding the time duration first would have yield some different result as in this example: the current date is August 30th 23:59:59. The duration to add is one month and one second. Feature add returns October 1st 0:0:0, whereas adding the second first would return September 30th 0:0:0! The same difference occurs with leap years. +{{caution|Using the addition features from TIME on the time attribute is also possible but the date will not be modified in the case time makes a cycle. }} -Feature relative_duration and definite_duration returns the duration between the current date (with time) and the argument. The first one returns a result which is canonical (see definitions below), while the second one returns a result definite but may be not canonical. It is the same notion than in DATE. +day_add is also available directly since it is frequently used within the class. + +Feature add (or +) takes an instance of DATE_TIME_DURATION as an argument. Internally, add 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 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. ==DATE and DATE_TIME== -Another way to process would have been to make DATE_TIME inherit from DATE,as long as DATE_TIME is a DATE, with more precision. The choice was to have a client relation between them. Otherwise DATE should have known the existence of DATE_TIME, and many assignment attempts would have been useful in features such as infix +. So DATE_TIME is client of DATE. +Another way to process would have been to make DATE_TIME inherit from DATE, as long as DATE_TIME is a DATE, with more precision. The choice was to have a client relation between them. Otherwise DATE should have known the existence of DATE_TIME, and many assignment attempts would have been useful in features such as infix +. So DATE_TIME is client of DATE. -However, it could be useful to mix instances of DATE of DATE_TIME. As DATE_TIME is client of DATE with its attribute date, it is easy to get only the date from instances of DATE_TIME. On the other way features are available to convert objects from DATE to DATE_TIME. In class DATE, feature to_date_time builds an instance of DATE_TIME with the origin of time (0,0,0). In the class DATE_TIME, the creation procedure make_by_date has the same effect. (The same feature exists for duration, replacing origin by zero). +However, it could be useful to mix instances of DATE of DATE_TIME. As DATE_TIME is client of DATE with its attribute date, it is easy to get only the date from instances of DATE_TIME. On the other way features are available to convert objects from DATE to DATE_TIME. In class DATE, feature to_date_time builds an instance of DATE_TIME with the origin of time (0,0,0). In the class DATE_TIME, the creation procedure make_by_date has the same effect. (The same feature exists for duration, replacing origin by zero).