• Functions and Operators on Dates and Times

Revision 1 as of 2007-11-21 09:09:08

Functions and Operators on Dates and Times

Date/time datatype values

As defined in Section 3.3.2 Dates and Times, xs:dateTime, xs:date, xs:time, xs:gYearMonth, xs:gYear, xs:gMonthDay, xs:gMonth, xs:gDay values, referred to collectively as date/time values, are represented as seven components or properties: year, month, day, hour, minute, second and timezone. The value of the first five components are xs:integers. The value of the second component is an xs:decimal and the value of the timezone component is an xs:dayTimeDuration. For all the date/time datatypes, the timezone property is optional and may or may not be present. Depending on the datatype, some of the remaining six properties must be present and some must be absent. Absent, or missing, properties are represented by the empty sequence. This value is referred to as the local value in that the value is in the given timezone. Before comparing or subtracting xs:dateTime values, this local value must be translated or normalized to UTC.

Comparison Operators on Date and Time Values

1. op:dateTime-equal

op:dateTime-equal($arg1 as xs:dateTime, $arg2 as xs:dateTime) as xs:boolean

Returns true if and only if the value of $arg1 is equal to the value of $arg2 according to the algorithm defined in section 3.2.7.4 of XML Schema Part 2: Datatypes Second Edition "Order relation on dateTime" for xs:dateTime values with timezones. Returns false otherwise.

2. op:dateTime-less-than

op:dateTime-less-than($arg1 as xs:dateTime, $arg2 as xs:dateTime) as xs:boolean

3. op:dateTime-greater-than

op:dateTime-greater-than( $arg1  as xs:dateTime,
                          $arg2  as xs:dateTime) as xs:boolean 

4. op:date-equal

op:date-equal($arg1 as xs:date, $arg2 as xs:date) as xs:boolean

Returns true if and only if the starting instant of $arg1 is equal to starting instant of $arg2. Returns false otherwise. The starting instant of an xs:date is the xs:dateTime at time 00:00:00 on that date.

5. op:date-less-than

op:date-less-than($arg1 as xs:date, $arg2 as xs:date) as xs:boolean

6. op:date-greater-than

op:date-greater-than($arg1 as xs:date, $arg2 as xs:date) as xs:boolean

Component Extraction Functions on Dates and Times

1. fn:year-from-dateTime

fn:year-from-dateTime($arg as xs:dateTime?) as xs:integer?

Returns an xs:integer representing the year component in the localized value of $arg. The result may be negative.

2. fn:month-from-dateTime

fn:month-from-dateTime($arg as xs:dateTime?) as xs:integer?

3. fn:day-from-dateTime

fn:day-from-dateTime($arg as xs:dateTime?) as xs:integer?

4. fn:hours-from-dateTime

fn:hours-from-dateTime($arg as xs:dateTime?) as xs:integer?

5. fn:minutes-from-dateTime

fn:minutes-from-dateTime($arg as xs:dateTime?) as xs:integer?

6. fn:seconds-from-dateTime

fn:seconds-from-dateTime($arg as xs:dateTime?) as xs:decimal?

7. fn:timezone-from-dateTime

fn:timezone-from-dateTime($arg as xs:dateTime?) as xs:dayTimeDuration?

Returns the timezone component of $arg if any. If $arg has a timezone component, then the result is an xs:dayTimeDuration that indicates deviation from UTC; its value may range from +14:00 to -14:00 hours, both inclusive. Otherwise, the result is the empty sequence.

8. fn:year-from-date

fn:year-from-date($arg as xs:date?) as xs:integer?

9. fn:month-from-date

fn:month-from-date($arg as xs:date?) as xs:integer?

10. fn:day-from-date

fn:day-from-date($arg as xs:date?) as xs:integer?

11. fn:timezone-from-date

fn:timezone-from-date($arg as xs:date?) as xs:dayTimeDuration?

12. fn:hours-from-time

fn:hours-from-time($arg as xs:time?) as xs:integer?

13. fn:minutes-from-time

fn:minutes-from-time($arg as xs:time?) as xs:integer?

14. fn:seconds-from-time

fn:seconds-from-time($arg as xs:time?) as xs:decimal?

15. fn:timezone-from-time

fn:timezone-from-time($arg as xs:time?) as xs:dayTimeDuration?

Timezone Adjustment Functions on Dates and Time Values

1. fn:adjust-dateTime-to-timezone

fn:adjust-dateTime-to-timezone($arg as xs:dateTime?) as xs:dateTime?

fn:adjust-dateTime-to-timezone( $arg      as xs:dateTime?,
                                $timezone as xs:dayTimeDuration?) as xs:dateTime?

Adjusts an xs:dateTime value to a specific timezone, or to no timezone at all. If $timezone is the empty sequence, returns an xs:dateTime without a timezone. Otherwise, returns an xs:dateTime with a timezone.

2. fn:adjust-date-to-timezone

fn:adjust-date-to-timezone($arg as xs:date?) as xs:date?

fn:adjust-date-to-timezone( $arg         as xs:date?,
                            $timezone    as xs:dayTimeDuration?) as xs:date?

Adjusts an xs:date value to a specific timezone, or to no timezone at all. If $timezone is the empty sequence, returns an xs:date without a timezone. Otherwise, returns an xs:date with a timezone. For purposes of timezone adjustment, an xs:date is treated as an xs:dateTime with time 00:00:00.

3. fn:adjust-time-to-timezone

fn:adjust-time-to-timezone($arg as xs:time?) as xs:time?

fn:adjust-time-to-timezone( $arg         as xs:time?,
                            $timezone    as xs:dayTimeDuration?) as xs:time?

Adjusts an xs:time value to a specific timezone, or to no timezone at all. If $timezone is the empty sequence, returns an xs:time without a timezone. Otherwise, returns an xs:time with a timezone.