The arithmetic operations performed on date and time types fall into five categories, described in the following sections:
Subtracting a date or time from another date or time to determine, for example, the elapsed time between 1:32 P.M. and 4:53 P.M.
Adding or subtracting durations from dates to determine, for example, what date is 30 days prior to April 15.
Adding or subtracting two durations to obtain a third duration, which might be used to extend a time period by 30 days.
Multiplying or dividing a duration by decimal numbers to obtain a third duration, which might be used to double a time period or to convert a numeric value to a duration.
Dividing a duration by another duration, which might be used to calculate the ratio of two durations or to convert a duration value to a number.
In addition to these operations, it is also possible to use the aggregation functions (max, min, avg, and sum) on sequences of duration values. You can also use the max and min functions on dates, times, and date/time values.
A value of type xs:date, xs:time, or xs:dateTime can be subtracted from another value of the same type. This is useful for determining the elapsed duration between two points in time. For example, if you want to calculate the response time on a customer order, you can subtract the order date from the delivery date.
The result is negative if the second date or time occurs later in time than the first date or time.
The resulting value, in all cases, is an xs:dayTimeDuration value. There is no way to determine the difference between two dates measured in months, because it's not clear that everyone would agree what the answer is if the dates are, for example, 2004-02-29 and 2005-02-28.
Time zones are taken into consideration during subtraction. If either of the values does not have a time zone, it is assumed to have the implicit time zone.
Table 19-7 shows some examples. The last example assumes that the implicit time zone is −05:00.
Table 19-7. Examples of subtracting dates and times
|
Example |
Value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
You can add or subtract durations from dates and times. This is useful for determining, for example, what date occurs 30 days after a specified date, or what time it will be when some process of fixed duration is completed.
Note that you can't add or subtract an xs:yearMonthDuration from an xs:time; attempting to do so raises a type error. This makes sense, since an xs:yearMonthDuration would not affect an xs:time anyway. Another restriction is that, when subtracting, the date/time operand must appear first (before the operator), and the duration operand second.
If the original xs:date, xs:time, or xs:dateTime has a time zone, the result has that same time zone. If it does not, the result does not. Table 19-8 shows some examples of adding and subtracting durations from dates and times.
Table 19-8. Examples of adding durations to dates and times
|
Example |
Value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Type error |
If adding a number of months to a date would result in a day value being out of range—for example, if you attempt to add P1M to 2006-05-31, the result has the last possible day of that month, e.g., 2006-06-30. This can cause surprises: if you add six months to a date and then subtract six months, you might not get the date you started with.
You can add and subtract values of type xs:yearMonthDuration or xs:dayTimeDuration (but not xs:duration). This is useful for extending time periods or adding up the durations
of various fixed-length processes.
The result of the operation has the same type as both the operands. The result will be negative if a larger duration is subtracted from a smaller duration. Table 19-9 shows some examples of adding and subtracting durations. The two operands must have the same type. If you attempt to add an xs:yearMonthDuration to an xs:dayTimeDuration, a type error is raised.
Table 19-9. Examples of adding and subtracting durations
|
Example |
Value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
Type error |
Multiplying and dividing durations by decimal numbers is useful, for example, to double a time period or reduce it by half. Another common use case is to convert a value from a number to a duration. For example, if the $numMonths variable has the integer value 10 that represents a number of months, and you want to convert it to a duration, you can use the expression:
$numMonths * xs:yearMonthDuration("P1M")This would result in a duration value of 10 months (P10M).
Table 19-10 shows some examples of multiplying and dividing durations by numbers.
Table 19-10. Examples of multiplying and dividing durations
|
Example |
Value |
Value type |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When working with an xs:yearMonthDuration value, the result is rounded to the nearest month.
Dividing a duration by another duration will calculate the ratio of two durations. This is useful if you need to convert a value from a duration to a number. For example, if the $showLength variable has the xs:dayTimeDuration value PT2H, and you want the equivalent number of minutes as a decimal number, you can use the expression:
$showLength div xs:dayTimeDuration("PT1M")This would result in the number 120, representing 120 minutes.
As with addition and subtraction, the two operands must have the same type. The result of the operation has the type xs:decimal. Table 19-11 shows some examples of dividing durations by other durations.