From: Kay, Michael <Michael.Kay@softwareag.com>

Date: Mon, 22 Sep 2003 12:22:16 +0200

Message-ID: <DFF2AC9E3583D511A21F0008C7E62106073DD135@daemsg02.software-ag.de>

To: public-qt-comments@w3.org

Date: Mon, 22 Sep 2003 12:22:16 +0200

Message-ID: <DFF2AC9E3583D511A21F0008C7E62106073DD135@daemsg02.software-ag.de>

To: public-qt-comments@w3.org

In comment SAG-FO-02 [1] Software AG proposed a radical simplification of the operators and functions provided for handling durations, dates, and times. [1] http://lists.w3.org/Archives/Public/public-qt-comments/2003Jun/0087.html The ideas behind the "durations" part of this proposal were discussed at the joint WG meeting on 15 September 2003. Although there were some reservations expressed both on the technical content and on the feasibility of making such a substantial change at this stage in the process, there was sufficient enthusiasm to ask for a detailed change proposal to be prepared for consideration. It was suggested that although the WG might not be able to make a decision on this change proposal in time for the next draft, it might solicit public feedback on the proposal in its own right. The proposal follows. I have used section numbers from an internal editor's draft dated 3 Sep 2003, but I believe there are no material differences from the last published WD in the affected areas. This note is a detailed proposal for implementing the replacement of functions and operators on the two data types xdt:dayTimeDuration and xdt:yearMonthDuration by functions and operators that represent these quantities by numbers. The rationale for this proposal is as follows: * It significantly reduces the number of functions, and the number of special cases that need to be handled by polymorphic functions such as sum() and avg() * It avoids the need to introduce new data types beyond the types already defined in XML Schema * It enables durations to be manipulated using the full power of all the numeric operators and functions * It thus brings durations into line with other units of measure such as distances, weights, temperatures and voltages * It makes it much easier to perform computations such as: calculating an average speed by dividing the distance travelled by the difference between the finish time and start time calculating a productivity measure by dividing the number of work items processed by the length of time taken to process them calculating a payment by multiplying a duration by an hourly rate. calculating the ratio between two durations. Two of these use cases are explored in more detail at the end of the proposal. * It is well aligned with future directions being discussed by the Schema WG, without being dependent on any changes to XML Schema. The general thrust of the proposal is that in nearly all computations involving durations, it is appropriate to use the S.I. unit of time, namely the second, and to express the number of seconds as a value of type xs:double. In some calculations involving civil time using the Gregorian calendar, it is more appropriate to express a duration as a number of calendar months, or as the combination of months and seconds. All other units of time encountered in the Gregorian calendar can readily be converted into months or seconds: for example a year is 12 months, and a day is 86400 seconds. Functions are provided to convert between values of the xs:duration type defined in XML Schema and a (months, seconds) pair. All computations involving durations, other than those that also involve dates and times, rely entirely on numeric arithmetic. Similarly, computations that add durations to a date or time express the duration as a numeric quantity. Timezones are represented as a displacement from UTC measured as an integer number of seconds. The changes proposed are as follows. DATA MODEL 3.6.1: timezones are now represented as an integer number of seconds, not as an xdt:dayTimeDuration FUNCTIONS AND OPERATORS This uses the section numbering of the 3 September 2003 internal draft. 1.6 xs:dateTime, xs:date and xs:time values Change this section as follows: xs:dateTime, xs:date and xs:time values are represented in the [XQuery 1.0 and XPath 2.0 Data Model] as tuples: a normalized value with timezone Z and a timezone represented as a number of seconds difference from UTC, expressed as a value of type xs:integer. Lexical representations of xs:dateTime, xs:date and xs:time that have a timezone are converted to timezone Z as defined by [XML Schema Part 2: Datatypes] and the timezone in the lexical representation is converted to an xs:integer value (for example, the timezone +01:00 is represented as +3600). Lexical representations that do not contain a timezone are given a normalized value with the timezone Z and the timezone part of the value set to the empty sequence "()". 1.6.1 Examples * A dateTime with lexical representation 1999-05-31T05:00:00 has a value represented by the tuple (1999-05-31T05:00:00Z, ()) * A dateTime with lexical representation 1999-05-31T13:20:00-05:00 has a value represented by the tuple (1999-05-31T18:20:00Z, -18000) 9.1 Duration Date and Time Types Delete the paragraphs: "In addition, they are defined on the [9.2 Two Totally Ordered Subtypes of Duration]: * xdt:yearMonthDuration * xdt:dayTimeDuration No operators are defined on the [XML Schema Part 2: Datatypes] datatype xs:duration. Appendix C.5 Working With xs:duration Values discusses how to work with xs:duration values. " Replace them with: The elapsed time between two dates, times, or dateTimes is generally handled as a number of seconds, expressed as an xs:double. Some functions are also provided that manipulate a duration as an integer number of months. All arithmetic, comparison, and sorting of durations is achieved by expressing the duration as an xs:integer number of months plus an xs:double number of seconds, and then manipulating these values using conventional numeric arithmetic. Note: there are two reasons that xs:double has been chosen to represent the number of seconds rather than xs:decimal. Firstly, floating point arithmetic is generally preferred when performing calculations involving units of measure on a continuous scale. Secondly, by using xs:double as the expected type of a duration value, we take advantage of the XPath numeric promotion rules, which allow the value to be supplied as an xs:integer, xs:float, or xs:decimal as well as an xs:double. 9.1.1 CONFORMANCE NOTE Delete the paragraph starting "The value spaces of the two totally ordered subtypes of xs:duration..." 9.2 Two totally ordered subtypes of Duration Delete the existing section. Replace it with a new section: (9.2) Functions on xs:duration values In [XML Schema] an xs:duration is defined as a 6-tuple with numeric components representing the number of years, months, days, hours, minutes, and seconds. Although the value representing two years is distinct in the value space from the value representing 24 months, the functions defined here treat these values as being equivalent. Thus, for all computational purposes, a duration is regarded as a 2-tuple consisting of an xs:integer number of months and an xs:double number of seconds. Either both these numbers will be positive, or both will be negative, or at least one will be zero. The number of months is obtained as (12*years + months), while the number of seconds is obtained as (((((24*days + hours)*60) + minutes)*60) + seconds). 9.2.1 get-months-from-duration fn:get-months-from-duration ($arg1 as xs:duration) as xs:integer Returns the number of months represented by the years and months components of the duration, that is, the value of 12*years + months. EXAMPLE fn:get-months-from-duration(xs:duration('P1Y8M5D')) returns 20 9.2.2 get-seconds-from-duration fn:get-seconds-from-duration ($arg1 as xs:duration) as xs:double Returns the number of seconds represented by the days, hours, minutes, and seconds components of the duration, that is, the value of (((((24*days + hours)*60) + minutes)*60) + seconds). EXAMPLE fn:get-seconds-from-duration(xs:duration('P1Y8M5DT12H30M')) returns 477000e0 9.2.3 make-duration fn:make-duration($months as xs:integer, $seconds as xs:double) returns xs:duration Returns a normalized xs:duration value containing the given number of months and the given number of seconds. An xs:duration value is normalized by ensuring that the number of months is less than 12, the number of hours is less than 24, the number of minutes is less than 60, and the number of seconds is less than 60. Note: there is no similar limit on the number of days or years. It is an error [make-duration: components have different sign] if the $months argument is greater than zero and the $seconds argument is less than zero, or if the $months argument is less than zero and the $seconds argument is greater than zero. EXAMPLES fn:make-duration(18, 477000) returns the xs:duration P1Y6M5DT12H30M fn:make-duration(240, 0) returns the xs:duration P20Y fn:make-duration(0, -90.25) returns the xs:duration -PT1M30.25S 9.3 Comparison of Duration, Date, and Time Values Delete the functions: op:yearMonthDuration-equal op:yearMonthDuration-less-than op:yearMonthDuration-greater-than op:dayTimeDuration-equal op:dayTimeDuration-less-than op:dayTimeDuration-greater-than from the table; and delete the corresponding sections that define these functions (9.3.1 to 9.3.6). In the paragraph after the table, delete the sentence: "A full complement of comparison and arithmetic functions are defined on the two subtypes of duration described in 9.2 Two Totally Ordered Subtypes of Duration.". 9.4 Component Extraction Functions on Duration, Date, and Time Values Delete the functions: fn:get-years-from-yearMonthDuration fn:get-months-from-yearMonthDuration fn:get-days-from-dayTimeDuration fn:get-hours-from-dayTimeDuration fn:get-minutes-from-dayTimeDuration fn:get-seconds-from-dayTimeDuration from the table, and delete the corresponding subsections that define these functions (9.4.1 to 9.4.6). 9.5 Arithmetic Functions on xdt:yearMonthDuration and xdt:dayTimeDuration Delete the entire section (8 functions in the op: namespace) 9.6 Adjusting timezones on dateTime, date, and time values Change these functions so that the timezone is expressed as an xs:integer number of seconds, representing the displacement from UTC. In all the function signatures, the timezone value changes type from xdt:dayTimeDuration to xs:integer. In 9.6.1, 9.6.2, and 9.6.3, change the sentence "A dynamic error is raised (invalid timezone value) if $timezone is less than -PT14H00M or greater than PT14H00M." to "A dynamic error is raised (invalid timezone value) if $timezone is less than -50400 or greater than +50400 (representing a range from 14 hours before UTC to 14 hours after UTC)". In 9.6.1.1, 9.6.1.2, and 9.6.1.3, change the examples accordingly. 9.7 Adding and Subtracting Durations From dateTime, date, and time Replace the entire section, as follows: These functions support adding or subtracting a duration value to or from an xs:dateTime, an xs:date or an xs:time value. Most of these functions handle a duration as a number of seconds, expressed as a number of type xs:double. Some functions also support durations expressed as an xs:integer number of months. A subtraction operator is provided to find the difference between two values of type xs:dateTime, xs:date or xs:time. The result is the number of seconds that separate the two instants in time, expressed as a value of type xs:double. If either of the arguments to this operator is an xs:dateTime, xs:date or xs:time that does not contain an explicit timezone then, for the purpose of the operation, an implicit timezone, provided by the evaluation context, is assumed to be present as part of the value. Operators are provided to add or subtract a duration expressed in seconds to or from an xs:dateTime, an xs:date or an xs:time value. The effect of these operations is to first convert the given number of seconds into an xs:duration value, and then apply the rules in Appendix E of [XML Schema Part 2: Datatypes]. A function is also provided to find the difference in months between two values of type xs:date. Again, if either of the arguments to this operator is an xs:date that does not contain an explicit timezone then, for the purpose of the operation, an implicit timezone, provided by the evaluation context, is assumed to be present as part of the value. An interval in months between two xs:dateTime values can be found by casting the xs:dateTime values to xs:date. A function is provided to add a duration expressed as an integer number of months to a value of type xs:date. The effect of this operation is to first convert the given number of months into an xs:duration value, and then apply the rules in Appendix E of [XML Schema Part 2: Datatypes]. 9.7.1 op:subtract-dateTimes op:subtract-dateTimes($arg1 as xs:dateTime, $arg2 as xs:dateTime) as xs:double Returns an xs:double value that corresponds to the number of seconds between the normalized value of $arg1 and the normalized value of $arg2. If either argument is the empty sequence, returns the empty sequence. If the normalized value of $arg1 precedes in time the normalized value of $arg2, the returned value is a negative number. 9.7.1.1 Examples * op:subtract-dateTimes(xs:dateTime("2000-10-30T11:12:00"), xs:dateTime("1999-11-28T09:00:00")) returns 29124720e0. 9.7.2 op:subtract-dates op:subtract-dates($arg1 as xs:date, $arg2 as xs:date) as xs:double Returns the number of seconds between the normalized value of $arg1 and the normalized value of $arg2. If either argument is the empty sequence, returns the empty sequence. If the normalized value of $arg1 precedes in time the normalized value of $arg2, the returned value is a negative number. Note: the difference in days between the two dates can be obtained by dividing the result by 86400 (that is, 24*60*60). The difference is not necessarily a whole number of days, because the dates may be in different timezones. 9.7.2.1 Examples * op:subtract-dates(xs:date("2000-10-30"), xs:date("1999-11-28")) returns 29116800e0. 9.7.3 op:subtract-times op:subtract-times($arg1 as xs:time, $arg2 as xs:time) as xs:double Returns the number of seconds between the normalized value of $arg2 and the normalized value of $arg1. If either argument is the empty sequence, returns the empty sequence. The result is greater than or equal to zero and less than 86400; that is, the subtraction is performed modulo the length of a day. 9.7.3.1 Examples Assume that the evaluation context provides an implicit timezone value of -5:00. * op:subtract-times(xs:time("11:12:00Z"), xs:time("04:00:00")) returns 7920e0 (corresponding to 2 hours and 12 minutes). 9.7.4 op:add-seconds-to-dateTime op:add-seconds-to-dateTime($arg1 as xs:dateTime, $arg2 as xs:double) as xs:dateTime Returns a value of type xs:dateTime that represents the instant in time that is $arg2 seconds later than $arg1; or if $arg2 is negative, the instant that is fn:abs($arg2) seconds earlier. The timezone of the result will be the same as the timezone of $arg1, or absent if the timezone of $arg1 is absent. 9.7.4.1 Examples op:add-seconds-to-dateTime(xs:dateTime('2003-01-31T23:00:00'), 7200) returns the xs:dateTime 2003-02-01T01:00:00 9.7.5 op:add-seconds-to-date op:add-seconds-to-date($arg1 as xs:date, $arg2 as xs:double) as xs:date Returns a value of type xs:date that contains the instant in time that is $arg2 seconds later than the start of the date represented by $arg1; or if $arg2 is negative, the instant that is fn:abs($arg2) seconds earlier. The timezone of the result will be the same as the timezone of $arg1, or absent if the timezone of $arg1 is absent. 9.7.5.1 Examples op:add-seconds-to-date(xs:date('2003-01-31'), 86400) returns the xs:date 2003-02-01 op:add-seconds-to-date(xs:date('2003-01-31'), 86399) returns the xs:date 2003-01-31 9.7.6 op:add-seconds-to-time op:add-seconds-to-time($arg1 as xs:time, $arg2 as xs:double) as xs:time Returns a value of type xs:time that represents the time that is $arg2 seconds later than the time represented by $arg1; or if $arg2 is negative, the instant that is fn:abs($arg2) seconds earlier. This effectively does arithmetic with a modulus of 24 hours. The timezone of the result will be the same as the timezone of $arg1, or absent if the timezone of $arg1 is absent. 9.7.6.1 Examples op:add-seconds-to-time(xs:time('T12:00:00'), 7200) returns the xs:time T14:00:00 op:add-seconds-to-time(xs:time('T23:00:00'), 7200) returns the xs:time T01:00:00 op:add-seconds-to-time(xs:time('T01:00:00'), -7200) returns the xs:time T23:00:00 9.7.7 op:subtract-seconds-from-dateTime op:subtract-seconds-from-dateTime($arg1 as xs:dateTime, $arg2 as xs:double) as xs:dateTime Returns the same result as op:add-seconds-to-dateTime($arg1, -$arg2). 9.7.7.1 Example op:subtract-seconds-from-dateTime(xs:dateTime('2003-01-31T23:00:00'), 7200) returns the xs:dateTime 2003-01-31T21:00:00 9.7.8 op:subtract-seconds-from-date op:subtract-seconds-from-date ($arg1 as xs:date, $arg2 as xs:double) as xs:date Returns the same result as op:add-seconds-to-date($arg1, -$arg2). 9.7.8.1 Example op:subtract-seconds-from-date(xs:date('2003-02-01'), 86400) returns the xs:date 2003-01-31 9.7.9 op:subtract-seconds-from-time op:subtract-seconds-from-time($arg1 as xs:time, $arg2 as xs:double) as xs:time Returns the same result as op:add-seconds-to-time($arg1, -$arg2). 9.7.9.1 Example op:subtract-seconds-from-time(xs:time('T01:00:00'), 3600) returns the time T00:00:00 op:subtract-seconds-from-time(xs:time('T01:00:00'), 3601) returns the time T23:59:59 9.7.10 fn:add-months-to-date fn:add-months-to-date($arg1 as xs:date, $arg2 as xs:integer) as xs:date Returns a value of type xs:date representing the date that is $arg2 months later than $arg1; or if $arg2 is negative, the instant that is fn:abs($arg2) months earlier. The algorithm used by this function is to convert the number of months to a value of type xs:duration by calling the function fn:make-duration with $arg2 as the first argument and zero as the second argument, and then to apply the algorithm given in Appendix E of [XML Schema Part 2: Datatypes]. 9.7.10.1 Examples fn:add-months-to-date(xs:date('2003-10-05'), 10) returns the date 2004-08-05 fn:add-months-to-date(xs:date('2003-10-05'), -3) returns the date 2003-07-05 fn:add-months-to-date(xs:date('2003-10-31'), 4) returns the date 2004-02-29 9.7.11 fn:subtract-dates-giving-months fn:subtract-dates-giving-months($arg1 as xs:date, $arg2 as xs:date) as xs:integer If $arg2 is later in time than $arg1, the function returns the largest integer N such that fn:add-months-to-date($arg2, N) is less than or equal to $arg1. Otherwise, returns the value of - fn:subtract-dates-giving-months($arg2, $arg1). 9.7.11.1 Examples fn:subtract-dates-giving-months(xs:date('2003-10-10'), xs:date(2003-09-09')) returns 1 fn:subtract-dates-giving-months(xs:date('2003-10-10'), xs:date(2004-09-09')) returns -10 15.3 Aggregate functions Delete all mentions of duration types in the specifications of these examples, and in the examples of their use. 16.8 implicit-timezone Change the signature to return xs:integer. Indicate in the description that the timezone is returned as an integer number of seconds displacement from UTC. 17.1 Casting Table Remove the rows and columns relating to xdt:dayTimeDuration and xdt:yearMonthDuration from the table. Remove the explanation of the labels dTD and yMD. 17.4 Casting within a branch of the type hierarchy Delete " and 17.9 Casting to duration types for rules regarding casting to xdt:yearMonthDuration and xdt:dayTimeDuration." at the end of the section. 17.9 Casting to duration types Delete this section. Appendix C.5 This section is replaced with the following: This document does not define equality on xs:duration values. Nor does it define other comparison functions on such values. Users wanting to work with xs:duration values should convert the duration into a number of seconds and/or months using the functions fn:get-months-from-duration and fn:get-seconds-from-duration; the reverse conversion can be achieved using the function fn:make-duration. One way of comparing two xs:duration values for equality is to compare their months and seconds components separately and return equal if both corresponding components are equal. This could be written as follows: XSLT implementation <xsl:function name="eg:duration-equal" as="xs:boolean"> <xsl:param name="arg1" as="xs:duration"/> <xsl:param name="arg2" as="xs:duration"/> <xsl:sequence select="get-months-from-duration($arg1) = get-months-from-duration($arg2) and get-seconds-from-duration($arg1) = get-seconds-from-duration($arg2)" /> </xsl:function> XQuery implementation declare function eg:duration-equal($arg1 as xs:duration, $arg2 as xs:duration) as xs:boolean { get-months-from-duration($arg1) = get-months-from-duration($arg2) and get-seconds-from-duration($arg1) = get-seconds-from-duration($arg2) } There is no reliable way of comparing whether one xs:duration value is greater than another, because there is no definitive answer to the question whether 30 days is greater than one month. One pragmatic approach to sorting durations is to use as a sort key the expression: get-months-from-duration(.) * 365.242199 div 12.0 + (get-seconds-from-duration(.) div 86400) Here 365.242199 is the average number of days in a year, and 86400 is the number of seconds in a normal day. XPATH/XQUERY LANGUAGE BOOK Using the 22 August 2003 published Working Draft as a baseline: In 2.1.1.1 Predefined types, delete list items 3 and 4 which refer to the xdt:dayTimeDuration and xdt:yearMonthDuration data types. In 2.1.2 Dynamic context, change the implicit timezone so it is expressed as an integer number of seconds (displacement from UTC). In 3.1.1 Literals, change the example that uses an xdt:dayTimeDuration (perhaps to use an xs:duration instead). In 3.4 Arithmetic Expressions, change the date subtraction example from: * Subtraction of two date values results in a value of type xdt:dayTimeDuration: $emp/hiredate - $emp/birthdate to: * Two date values may be subtracted to return a duration in seconds. Dividing by 86400 gives the difference in days: ($emp/hiredate - $emp/birthdate) div 86400 In 3.10.4 Constructor functions, remove the references to the types xdt:dayTimeDuration and xdt:yearMonthDuration, and the example that uses these. In Appendix B.2, the operator mapping table: (a) Delete the 37 rows that have xdt:dayTimeDuration or xdt:yearMonthDuration in the Type(A) or Type(B) column. (b) Change the three rows for subtracting date-date, time-time, and dateTime-dateTime so the return type is xs:double (c) Add the following 9 rows: A + B xs:date xs:double op:add-seconds-to-date(A,B) xs:date A + B xs:time xs:double op:add-seconds-to-time(A,B) xs:time A + B xs:dateTime xs:double op:add-seconds-to-dateTime(A,B) xs:dateTime A + B xs:double xs:date op:add-seconds-to-date(B,A) xs:date A + B xs:double xs:time op:add-seconds-to-time(B,A) xs:time A + B xs:double xs:dateTime op:add-seconds-to-dateTime(A,B) xs:dateTime A - B xs:date xs:date op-subtract-dates(A,B) xs:double A - B xs:time xs:time op-subtract-times(A,B) xs:double A - B xs:dateTime xs:dateTime op-subtract-dateTimes(A,B) xs:double FORMAL SEMANTICS 3.1.1.1: remove references to xdt:dayTimeDuration and xdt:yearMonthDuration types Appendix B.2: align the operator mapping table with the revised version in the language document USE CASES Use Case 1: Timesheets Scenario: Staff complete timesheets giving for each day, the time they start and finish work. The query calculates the total hours worked and multiplies this by an hourly rate of pay to calculate the payment due. Source document: <timesheets> <employee nr="12345" rate="10.50"> <attendance date="2003-01-15" start="T09:00:00" end="T17:00:00"/> <attendance date="2003-01-16" start="T09:00:00" end="T18:00:00"/> <attendance date="2003-01-17" start="T09:00:00" end="T17:00:00"/> <attendance date="2003-01-18" start="T09:00:00" end="T16:00:00"/> <attendance date="2003-01-19" start="T09:00:00" end="T16:00:00"/> </employee> </timesheets> Solution: sum( for $a in $emp/attendance return ($a/@end - $a/@start) div 3600) * $emp/@rate Note that this works even for shifts that cross midnight. Using the functions in the published WD, the subtraction of two times yields a dayTimeDuration. It is not possible to multiply this directly by an hourly rate to obtain the amount payable; instead it is necessary to extract the individual components of the dayTimeDuration, use these to compute the number of hours worked, and then do the multiplication. Use Case 2: Average Speed Scenario: The source document contains the start times and end times for each driver in each stage of a motor rally. The query calculates the average speed. Source document <timings> <driver name="Mansell"> <stage distance="520.5" start="2002-10-15T09:02:04.1" finish="2002-10-15T17:12:16.2"/> <stage distance="430.3" start="2002-11-15T08:32:05.7" finish="2002-11-15T15:55:13.6"/> </driver> </timings> Solution: avg(for $s in driver/stage return @distance div (@finish - @start)) div 3600 Using the functions in the published WD, the subtraction of two dateTimes yields a dayTimeDuration. It is not possible to divide a distance by a dayTimeDuration to obtain a speed; instead, it is necessary to convert the duration to a number of seconds by extracting all the components to compute the travel time in seconds. These use cases demonstrate that although under this proposal the specification has vastly fewer functions to manipulate durations, practical calculations involving durations actually become significantly easier. Michael Kay Software AGReceived on Monday, 22 September 2003 06:22:25 UTC

*
This archive was generated by hypermail 2.3.1
: Wednesday, 7 January 2015 15:45:14 UTC
*