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

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: <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====
 
@@ -27,7 +27,7 @@ The query <eiffel>duration</eiffel> applied to an instance of [[ref:libraries/ti
 
 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]]). In <eiffel>TIME</eiffel>, the feature <eiffel>relative_duration</eiffel> returns the same duration, but more efficiently and in canonical form. 
+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.
@@ -36,11 +36,11 @@ The feature <eiffel>-</eiffel> returns an [[Interval]] between two instances of
 
 ==DATE==
 
-<eiffel>DATE</eiffel> 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.
+<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 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 <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====
 
@@ -48,7 +48,7 @@ The origin for instances of <eiffel>DATE</eiffel> is January 1, 1600.
 
 ====Comparison====
 
-Instances of <eiffel>DATE</eiffel> may be compared. Functions <eiffel><</eiffel>, <eiffel><=</eiffel>, <eiffel>></eiffel>, and <eiffel>>=</eiffel> are available for ordering instance by value. Function <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>) can be used to test object equality, while <eiffel>=</eiffel> will compare references. 
+Instances of <eiffel>DATE</eiffel> may be compared. Functions <eiffel><</eiffel>, <eiffel><=</eiffel>, <eiffel>></eiffel>, and <eiffel>>=</eiffel> 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====
 

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 <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. 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. 
 {| 
 |- 

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]]
-<eiffel>TIME_DURATION</eiffel>, <eiffel>DATE_DURATION</eiffel>, and <eiffel>DATE_TIME_DURATION</eiffel> 
+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 <eiffel>DURATION</eiffel>, which inherits <eiffel>GROUP_ELEMENT</eiffel> and <eiffel>PART_COMPARABLE</eiffel>. An instance of <eiffel>TIME_DURATION</eiffel>, <eiffel>DATE_DURATION</eiffel>, or <eiffel>DATE_TIME_DURATION</eiffel> is an element of a group, i.e. there is a zero and addition operations (<eiffel>infix +</eiffel>, <eiffel>infix -</eiffel>, <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 (<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>). 
 
@@ -87,7 +87,7 @@ Features <, >, <=, and >= are available. If both instances are definite, numbers
 
 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>.
 
-====Operation====
+====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. 
 
@@ -122,7 +122,7 @@ The rules are the same than those for <eiffel>DATE_DURATION</eiffel>. Features <
 
 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. 
 
-====Operation====
+====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. 
 

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.

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 <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> ( <eiffel>DATE</eiffel>, <eiffel>TIME</eiffel>, <eiffel>DATE_TIME</eiffel>). 
+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 
@@ -17,7 +17,7 @@ The measurement of an interval is done by applying the query <eiffel>duration</e
 
 * <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> performs object comparison.
+* <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.

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]]
-<eiffel>TIME</eiffel> and <eiffel>TIME_DURATION</eiffel> are designed to deal with high precision in time. The only limit is the one from number representation. 
+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> (inherited from <eiffel>TIME_VALUE</eiffel>) which allows high precision. This attribute represents the number of seconds with fractions (it is an instance of <eiffel>DOUBLE</eiffel>). 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 <eiffel>TIME_VALUE</eiffel>). 
+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>. 
 
-As a result of this, when <eiffel>fine_second</eiffel> is positive (3.55 for example), <eiffel>second</eiffel> and <eiffel>fractional_second</eiffel> are also positive (3 and 0.55). When <eiffel>fine_second</eiffel> is negative (- 3.55 for example), <eiffel>second</eiffel> and <eiffel>fractional_second</eiffel> are also negative (- 3 and - 0.55).
+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> looks like make but it takes a <eiffel>DOUBLE</eiffel> for its third argument (instead of an <eiffel>INTEGER</eiffel>). fine_second is then set to this value.
+* <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> looks like <eiffel>make_by_seconds</eiffel> but it takes a <eiffel>DOUBLE</eiffel> for argument (instead of an <eiffel>INTEGER</eiffel>). 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.
+* <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.
+* <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.
+* <eiffel>fine_seconds_count</eiffel> looks like <eiffel>seconds_count</eiffel> but it contains fractions.
 
 ====Element change====
-* <eiffel>set_fine_second</eiffel> allows to set directly <eiffel>fine_second</eiffel> to a <eiffel>DOUBLE</eiffel>. In <eiffel>TIME</eiffel>, a precondition requires that the argument stands in the allowed range. 
+* Set <eiffel>fine_second</eiffel> directly with <eiffel>set_fine_second</eiffel>. 
-* <eiffel>set_fractionals</eiffel> allows to set directly <eiffel>fractional_second</eiffel> to a <eiffel>DOUBLE</eiffel>. In <eiffel>TIME </eiffel>a precondition requires that the argument is positive and smaller than one. In <eiffel>TIME_DURATION</eiffel> the precondition is particular: it is not allowed to have an argument with a different sign than second. Otherwise, as long as <eiffel>fractional_second</eiffel> and <eiffel>second</eiffel> are linked to <eiffel>fine_second</eiffel>, such a setting would mean that second is also changed and <eiffel>fractional_second</eiffel> set to a different value. For example if <eiffel>fine_second</eiffel> = 4.5 (then second = 4 and fractional_second = 0.5) and - 0.8 is the argument of <eiffel>set_fractionals</eiffel>. 
+* Set <eiffel>fractional_second</eiffel> directly with <eiffel>set_fractionals</eiffel>. 
 
-The result of that would be<eiffel> fine_second</eiffel> = 3.2 (then <eiffel>second</eiffel> = 3 and <eiffel>fractional_second</eiffel> = 0.2). It is better to prohibit that.
 
-Comment: feature <eiffel>set_second</eiffel> (from both <eiffel>TIME</eiffel> and <eiffel>TIME_DURATION</eiffel>) will cut down <eiffel>fractional_second</eiffel> to zero. 
+{{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> but takes a <eiffel>DOUBLE</eiffel> for argument.
+* <eiffel>fine_second_add</eiffel> looks like <eiffel>second_add</eiffel> except that it takes a <eiffel>DOUBLE</eiffel> as an argument.
-
+
-In <eiffel>TIME_DURATION</eiffel>: 
-
-- <eiffel>canonical</eiffel> and <eiffel>to_canonical</eiffel> deals already with precision. There is nothing different.