From 5dd5ca1ef0eace5221327b994d7f30cae2089a1f Mon Sep 17 00:00:00 2001 From: halw Date: Mon, 24 Nov 2008 01:27:34 +0000 Subject: [PATCH] Author:halw Date:2008-11-24T01:27:34.000000Z git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@110 abb3cda0-5349-4a8f-a601-0c33ac3a8c38 --- .../eiffeltime-tutorial/absolute-time.wiki | 10 +++---- .../date-time-string-conversion.wiki | 10 +++++++ .../eiffeltime-tutorial/duration.wiki | 6 ++-- .../eiffeltime/eiffeltime-tutorial/index.wiki | 2 +- .../eiffeltime-tutorial/interval.wiki | 4 +-- .../eiffeltime-tutorial/more-precision.wiki | 28 ++++++++----------- 6 files changed, 33 insertions(+), 27 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 ff032ee7..0259a1e7 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 @@ -7,7 +7,7 @@ The classes dealing with date and those dealing with time have many similarities ==TIME== -[[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. +[[ref:libraries/time/reference/time_chart|TIME]] models times of day, supporting queries: 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==== @@ -27,7 +27,7 @@ The query duration applied to an instance of [[ref:libraries/ti 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. +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]] for a definition of canonical form). In TIME, the feature relative_duration returns the same duration, but more efficiently and in canonical form. ====Operations==== * Set values for hour, minute, and second with set_hour, set_minute, and set_second. Arguments must satisfy the rules of creation. @@ -36,11 +36,11 @@ The feature - returns an [[Interval]] between two instances of ==DATE== -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. +DATE models dates, and supports queries 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 should probably be adequate. ====Creation==== -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]]). +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, 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==== @@ -48,7 +48,7 @@ The origin for instances of DATE is January 1, 1600. ====Comparison==== -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. +Instances of DATE may be compared. Functions <, <=, >, and >= are available for ordering instances by value. Function is_equal (or ~) can be used to test object equality, while = will compare references. ====Measurement==== diff --git a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/date-time-string-conversion.wiki b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/date-time-string-conversion.wiki index c4b956af..b6aa43ec 100644 --- a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/date-time-string-conversion.wiki +++ b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/date-time-string-conversion.wiki @@ -1,6 +1,16 @@ [[Property:title|DATE / TIME to STRING Conversion]] [[Property:weight|3]] [[Property:uuid|88972ba4-694b-8558-b0c8-87b1fc40afc4]] +The classes TIME, DATE, and DATE_TIME provide a query formatted_out 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. So for example, if a DATE instance referenced by my_date has a value of February 3, 2008, then applying the query: + + my_date.formatted_out ("[0]dd mmm yyyy") + +will return the string: + +03 FEB 2008 + + + The following table lists format conversion codes. {| |- diff --git a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/duration.wiki b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/duration.wiki index 7577fbf5..3f6040fe 100644 --- a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/duration.wiki +++ b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/duration.wiki @@ -1,7 +1,7 @@ [[Property:title|Duration]] [[Property:weight|1]] [[Property:uuid|64672bd0-b696-0c39-1e30-5ac64aae4a99]] -TIME_DURATION, DATE_DURATION, and DATE_TIME_DURATION +The classes TIME_DURATION, DATE_DURATION, and DATE_TIME_DURATION model time durations. The classes dealing with duration inherit DURATION, which inherits GROUP_ELEMENT and PART_COMPARABLE. An instance of TIME_DURATION, DATE_DURATION, or DATE_TIME_DURATION 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, but not TIME + DATE_TIME_DURATION nor DATE_TIME + TIME_DURATION ... see classes TIME, DATE, and DATE_TIME). @@ -87,7 +87,7 @@ Features <, >, <=, and >= are available. If both instances are definite, numbers Features set_day, set_month, and set_year are available to set one of these three attributes day, month, year. -====Operation==== +====Operations==== * Add years, months and days with features year_add, month_add, and day_add. * DATE_DURATION inherits from GROUP_ELEMENT. infix and prefix +, infix and prefix - are available to compose instances of each other. @@ -122,7 +122,7 @@ The rules are the same than those for DATE_DURATION. Features < 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_DURATION or DATE_DURATION have to be used. -====Operation==== +====Operations==== * DATE_TIME_DURATION 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 TIME_DURATION or DATE_DURATION have to be used. 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 ce1bc6d6..91ccbf74 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 @@ -11,7 +11,7 @@ The library EiffelTime is designed to provide software components for the effect 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. +* 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. diff --git a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/interval.wiki b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/interval.wiki index 2cf760d1..1cae8fff 100644 --- a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/interval.wiki +++ b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/interval.wiki @@ -1,7 +1,7 @@ [[Property:title|Interval]] [[Property:weight|2]] [[Property:uuid|d33d0216-fa71-60dc-f3b0-61ff42d621e6]] -Class INTERVAL [G -> ABSOLUTE] deals with intervals between two instances of the same class (an actual generic parameter substituting for G) which conforms to ABSOLUTE ( DATE, TIME, DATE_TIME). +Class INTERVAL [G -> ABSOLUTE] deals with intervals between two instances of the same class (an actual generic parameter substituting for G) which conforms to ABSOLUTE (specifically: DATE, TIME, DATE_TIME). ====Creation==== The creation procedure @@ -17,7 +17,7 @@ The measurement of an interval is done by applying the query durationinfix < and infix > compare two intervals on a "strict" basis. This means that int_1 < int_2 is True if int_1 starts and ends strictly before int_2. In other words, int_1 must have a start bound less than that of int_2 and an end bound less than that of int_2. * infix <= and infix >= compare two intervals on a non-strict basis. So, int_1 <= int_2 is True if int_1 has a start bound less than or equal to that of int_2 and an end bound less than or equal to that of int_2. -* is_equal performs object comparison. +* is_equal (or ~)performs object comparison. * intersects is true if one (target) INTERVAL shares some of the same bounded area with a second (argument) INTERVAL. * overlaps is similar to intersects with the exception that the argument INTERVAL has to be after the target INTERVAL. is_overlapped is the opposite of overlaps. * meets and is_met are used to test whether two intervals have a common bound. diff --git a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/more-precision.wiki b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/more-precision.wiki index fbe3e6b6..2521aca2 100644 --- a/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/more-precision.wiki +++ b/documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/more-precision.wiki @@ -1,45 +1,41 @@ [[Property:title|More precision]] [[Property:weight|4]] [[Property:uuid|fadf5bc2-bb72-f681-b9c4-bab7f0633209]] -TIME and TIME_DURATION are designed to deal with high precision in time. The only limit is the one from number representation. +The classes TIME and TIME_DURATION are designed to deal with time in high precision, limited only by platform numerical representation. -The classes TIME and TIME_DURATION have an attribute fine_second (inherited from TIME_VALUE) which allows high precision. This attribute represents the number of seconds with fractions (it is an instance of DOUBLE). From this attribute are calculated second and fractional_second (which are functions): second is the truncated-to-integer part and fractional_second is the difference between the two previous one, so that the sum of second and fractional_second is always equal to fine_second (see invariant in TIME_VALUE). +The classes TIME and TIME_DURATION have an attribute fine_second of type DOUBLE which allows high precision. This attribute represents the number of seconds with fractions. From fine_second are calculated the values for second and fractional_second. second is the truncated-to-integer part of fine_second and fractional_second is the fractional part of fine_second. -As a result of this, when fine_second is positive (3.55 for example), second and fractional_second are also positive (3 and 0.55). When fine_second is negative (- 3.55 for example), second and fractional_second are also negative (- 3 and - 0.55). +When fine_second is positive, 3.55 for example, second and fractional_second are both positive (3 and 0.55, respectively). When fine_second is negative (- 3.55 for example), then second and fractional_second 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 fine_second and fractional_second are described here. ====Creation (common to TIME, TIME_DURATION)==== -* make_fine looks like make but it takes a DOUBLE for its third argument (instead of an INTEGER). fine_second is then set to this value. -* make_by_fine_seconds looks like make_by_seconds but it takes a DOUBLE for argument (instead of an INTEGER). Comparison (common) There are no new features. The same ones are available since they are written to deal with precision. It is possible to compare two instances, one with precision and the other one without. +* make_fine is similar to make except that it takes a DOUBLE for its third argument (instead of an INTEGER, as is the case with make). fine_second is then set to this value. +* make_by_fine_seconds is similar to make_by_seconds except that it takes a DOUBLE for an argument (instead of an INTEGER, as is the case withmake_by_seconds). ====Measurement and access==== In TIME: -- fine_seconds looks like seconds but it contains fractions. +* fine_seconds looks like seconds but it contains fractions. In TIME_DURATION: -- fine_seconds_count looks like seconds_count but it contains fractions. +* fine_seconds_count looks like seconds_count but it contains fractions. ====Element change==== -* set_fine_second allows to set directly fine_second to a DOUBLE. In TIME, a precondition requires that the argument stands in the allowed range. -* set_fractionals allows to set directly fractional_second to a DOUBLE. In TIME a precondition requires that the argument is positive and smaller than one. In TIME_DURATION the precondition is particular: it is not allowed to have an argument with a different sign than second. Otherwise, as long as fractional_second and second are linked to fine_second, such a setting would mean that second is also changed and fractional_second set to a different value. For example if fine_second = 4.5 (then second = 4 and fractional_second = 0.5) and - 0.8 is the argument of set_fractionals. +* Set fine_second directly with set_fine_second. +* Set fractional_second directly with set_fractionals. -The result of that would be fine_second = 3.2 (then second = 3 and fractional_second = 0.2). It is better to prohibit that. -Comment: feature set_second (from both TIME and TIME_DURATION) will cut down fractional_second to zero. +{{note|Use of the feature set_second (in either TIME and TIME_DURATION) will result in fractional_second having a value of zero. }} ====Operations==== -- fine_second_add looks like second_add but takes a DOUBLE for argument. - -In TIME_DURATION: - -- canonical and to_canonical deals already with precision. There is nothing different. +* fine_second_add looks like second_add except that it takes a DOUBLE as an argument. +