xf:get-yearMonthDuration-from-dateTimes

Computes the time difference between $dateTime-var1 and $dateTime-var2 and returns it as a yearMonthDuration value.

If the value of $date-var1 follows in time the value of $date-var2, then the returned value is a negative duration. (The date specified in $dateTime-var1 comes before the date specified in $dateTime-var2.) To learn more, see the following Negative Difference example.

The time difference between the values of two dateTime arguments could include years, months, minutes, and seconds but a yearMonthDuration value can only contain years and months, so the time difference is rounded to nearest month. If the time difference between the two dateTime arguments is greater than or equal to 15.5 days (15 days and 12 hours), the month duration is rounded up. To learn more, see the following Round Up and Not Enough to Round Up examples.

If the value of $date-var1 or $date-var2 is the empty sequence, the following error is displayed:

Error occurred while executing XQuery: Error loading the XQuery or XSLT for this method: Type error in function subtract-dates invocation: expected type [date@http://www.w3.org/2001/XMLSchema], given type empty 

Signatures

xf:get-yearMonthDuration-from-dateTimes(xs:dateTime $dateTime-var1, xs:dateTime $dateTime-var2) —> xf:yearMonthDuration

Arguments

Data Type
Argument
Description

xs:dateTime

$dateTime-var1

Contains a representation of the date and time.

xs:dateTime

$dateTime-var2

Contains a representation of the date and time.

Returns

Returns the time difference between $dateTime-var1 and $dateTime-var2 as a yearMonthDuration value.

Returns a negative yearMonthDuration value if $dateTime-var1 follows in time $dateTime-var2. (The date specified in $dateTime-var1 comes before the date specified in $dateTime-var2.) To learn more, see the following Negative Difference example.

Examples

Positive Difference

The following example query returns a positive years and months duration because the date specified in $datetime-var1 comes after the date specified in $datetime-var2:

let $dateTime-var1 := xs:dateTime("2002-12-26T00:00:01")
return
let $dateTime-var2 := xs:dateTime("2001-11-26T00:00:01")
return
let $mydur := xf:get-yearMonthDuration-from-dateTimes($dateTime-var1, $dateTime-var2)
return
<result>
	<years>{xf:get-years-from-yearMonthDuration($mydur)}</years>
	<months>{xf:get-months-from-yearMonthDuration($mydur)}</months>
</result> 

The preceding query generates the following result:

<result>
	<years>1</years>
	<months>1</months>
</result> 

Negative Difference

The following example query returns a negative years and month duration because the date specified in $dateTime-var1 comes before the date specified in $dateTime-var2:

let $dateTime-var1 := xs:dateTime("2001-11-26T00:00:01")
return
let $dateTime-var2 := xs:dateTime("2002-12-26T00:00:01")
return
let $mydur := xf:get-yearMonthDuration-from-dateTimes($dateTime-var1, $dateTime-var2)
return
<result>
	<years>{xf:get-years-from-yearMonthDuration($mydur)}</years>
	<months>{xf:get-months-from-yearMonthDuration($mydur)}</months>
</result> 

The preceding query generates the following result:

<result>
	<years>-1</years>
	<months>-1</months>
</result> 

Round Up

The following example query returns a 1 month yearMonthDuration because there are 15.5 days (15 days and 12 hours) between $dateTime-var1 and $dateTime-var2:

let $dateTime-var1 := xs:dateTime("2002-11-16T12:00:00")
return
let $dateTime-var2 := xs:dateTime("2002-11-01T00:00:00")
return
let $mydur := xf:get-yearMonthDuration-from-dateTimes($dateTime-var1, $dateTime-var2)
return
<result>
	<years>{xf:get-years-from-yearMonthDuration($mydur)}</years>
	<months>{xf:get-months-from-yearMonthDuration($mydur)}</months>
</result> 

The preceding query generates the following result:

<result>
	<years>0</years>
	<months>1</months>
</result> 

Not Enough to Round Up

The following example query returns a 0 months yearMonthDuration because there are only 15 days, 11 hours, 59 minutes, and 59 seconds (1 second from 15.5 days) between $dateTime-var1 and $dateTime-var2:

let $dateTime-var1 := xs:dateTime("2002-11-16T11:59:59")
return
let $dateTime-var2 := xs:dateTime("2002-11-01T00:00:00")
return
let $mydur := xf:get-yearMonthDuration-from-dateTimes($dateTime-var1, $dateTime-var2)
return
<result>
	<years>{xf:get-years-from-yearMonthDuration($mydur)}</years>
	<months>{xf:get-months-from-yearMonthDuration($mydur)}</months>
</result> 

The preceding query generates the following result:

<result>
	<years>0</years>
	<months>0</months>
</result> 

Related Topics

W3C get-yearMonthDuration-from-dayTimes function description.

W3C yearMonthDuration data type description.

W3C dateTime data type description.