From cdce168f2072c07a3f0fcb80b3e3bb0b2931dce6 Mon Sep 17 00:00:00 2001 From: halw Date: Tue, 18 Nov 2008 21:39:14 +0000 Subject: [PATCH] Author:halw Date:2008-11-18T21:39:14.000000Z git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@106 abb3cda0-5349-4a8f-a601-0c33ac3a8c38 --- .../eiffeltime-tutorial/absolute-time.wiki | 35 ++++++++++--------- .../eiffeltime/eiffeltime-tutorial/index.wiki | 7 +++- 2 files changed, 25 insertions(+), 17 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 3dc2ad2b..8b377f20 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 @@ -1,15 +1,13 @@ [[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 almost the same construction. At the top of the hierarchy are the constants and 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]] ). +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 ABSOLUTE. It implies that instances of these classes are used as absolutes. We can imagine an oriented axis on which are reported values. ABSOLUTE inherits COMPARABLE, there is a complete order inside the class and its heir. ABSOLUTE is a client of DURATION, so that each instance of ABSOLUTE is linked with the duration between the origin and itself. - -The default way to compare absolute objects is to compare their respective duration to each other. +[[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 ABSOLUTE inherits from COMPARABLE, the ordering functions <, +, >, and >= are available on instances of [[ref:libraries/time/reference/absolute_chart|ABSOLUTE]] and its descendants. ==TIME== -[[ref:libraries/time/reference/time_chart|TIME]] deals with hour, minute, and second. It is possible to use more precision for time (there is no limit inside the class). See More precision in TIME for documentation. This section deals only with second. +[[ref:libraries/time/reference/time_chart|TIME]] deals with hour, minute, and second. 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==== @@ -17,40 +15,44 @@ There are three ways to create an instance of the class TIME: b ====Origin and cyclic representation==== -The origin is 0 hour 0 minute and 0 second. Notion of time is relative to a day in a cyclic representation: 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. +The origin for instances of TIME 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 <, +, >, and >= are available. Function is_equal (or ~) can be used to test object equality, whereas = will compare references. +Instances of [[ref:libraries/time/reference/time_chart|TIME ]] may be compared. Functions <, <=, >, and >= are available for ordering instances. Function is_equal (or ~) can be used to test object equality, whereas = will compare references. ====Measurement==== -The duration linked to an instance of [[ref:libraries/time/reference/time_chart|TIME]] (query duration) results in 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 seconds returns the number of seconds since the origin. This query may be useful to get the number of seconds between two events.The feature - creates an interval between two instances of TIME. The duration of this interval is given by the function duration. However, this duration is non-canonical (See [[Duration|Duration]] for precisions). In TIME, the feature relative_duration returns the same duration, but more efficiently and also it is canonical. +The query duration 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 seconds 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 - returns an [[Interval]] between two instances of TIME. The duration of this interval is given by the function duration. However, this duration is non-canonical (See [[Duration|Duration]]). In TIME, the feature relative_duration returns the same duration, but more efficiently and in canonical form. ====Operations==== -* Set directly hour, minute, and second with set_hour, set_minute, and set_second. Arguments must satisfy the rules of creation. -* Adding hours, minutes, and seconds with features hour_add, minute_add, and second_add. Features add and + take an instance of TIME_DURATION as an Page 3 argument and add it to the current time. -* Moving 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 faster to use these features rather than those above (e.g., hour_back will outperform hour_add (-1) ). +* 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) ). ==DATE== -DATE deals with year, month and day. It is more complicated since there is no regular period in dates: each month contains its own total of days and there are leap years. That is why some peculiarities appear while manipulating objects of this class. There is no limit for a date (inside the class). The only limit comes from INTEGER representation. If INTEGER size is 32 bits (most common case), and as long as the basic unit is a day, the range for a date is from (- 2^31) to 2^31 (days), i.e. 5.8 million years from the origin. +DATE deals with year, month and day. 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 will probably be adequate. ====Creation==== -There are also three ways to create an instance of the class DATE: by choosing the date (make, make_month_day_year, make_day_month_year), by getting the date from the system (make_now), or by choosing the number of days elapsed from the origin (make_by_days). The arguments of each creation procedure have to respect the common range (See preconditions). +There are three ways to create an instance of the class DATE: by choosing the date (make, make_month_day_year, make_day_month_year), by getting the date from the system (make_now), or by choosing the number of days elapsed from the origin (make_by_days). The arguments of each creation procedure have to respect the common range (See the respective creation procedures' preconditions in class [[ref:libraries/time/reference/date_chart|DATE]]). ====Origin==== -The origin is 01/01/1600. +The origin for dates is 01/01/1600. ====Comparison==== -Instances of DATE may be compared. Functions <, +, >, and >= are available. Function is_equal (or ~) can be used to test object equality, while = will compare references. +Instances of DATE may be compared. Functions <, <=, >, and >= are available for ordering instance by value. Function is_equal (or ~) can be used to test object equality, while = will compare references. ====Measurement==== -Each instance of DATE has a function (duration) 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 below). However, it may be useful to deal directly with days (no need of DATE_DURATION). In this case, the function days of DATE yields the number of days since origin. +Each instance of DATE has a function (duration) 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 days of DATE yields the number of days since origin. ====Status Report==== @@ -98,6 +100,7 @@ It is possible to change reference of time and dateDATE_TIME, because adding time to a DATE_TIME may have a consequence on the date. + {{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. }} day_add is also available directly since it is frequently used within the class. 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 bf25d210..02afafe4 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 @@ -1,7 +1,7 @@ [[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. +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. @@ -9,9 +9,14 @@ The library EiffelTime is designed to provide software components for the effect * ''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. The notion of origin is also 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. + +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. + +