Status of this Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document.
This document is a working draft developed and maintained by a W3C Community Group, the XQuery and XSLT Extensions Community Group unofficially known as QT4CG (where "QT" denotes Query and Transformation). This draft is work in progress and should not be considered either stable or complete. Standard W3C copyright and patent conditions apply.
The community group welcomes comments on the specification. Comments are best submitted as issues on the group's GitHub repository.
The community group maintains two extensive test suites, one oriented to XQuery and XPath, the other to XSLT. These can be found at qt4tests and xslt40-test respectively. New tests, or suggestions for correcting existing tests, are welcome. The test suites include extensive metadata describing the conditions for applicability of each test case as well as the expected results. They do not include any test drivers for executing the tests: each implementation is expected to provide its own test driver.
Dedication
The publications of this community group are dedicated to our co-chair, Michael Sperberg-McQueen (1954–2024).
This section defines operations on the [XML Schema Part 2: Datatypes Second Edition] date and time types.
See [Working With Timezones] for a disquisition on working with date and time values with and without timezones.
| Function | Meaning |
|---|
fn:adjust-dateTime-to-timezone | Adjusts an xs:dateTime value to a specific timezone, or to no timezone at all. |
fn:adjust-date-to-timezone | Adjusts an xs:date value to a specific timezone, or to no timezone at all; the result is the date in the target timezone that contains the starting instant of the supplied date. |
fn:adjust-time-to-timezone | Adjusts an xs:time value to a specific timezone, or to no timezone at all. |
fn:civil-timezone | Returns the timezone offset from UTC that is in conventional use at a given place and time. |
These functions adjust the timezone component of an xs:dateTime, xs:date or xs:time value. The $timezone argument to these functions is defined as an xs:dayTimeDuration but must be a valid timezone value.
- Summary
Returns the timezone offset from UTC that is in conventional use at a given place and time.
- Signature
fn:civil-timezone( |
$value | as xs:dateTime | |
$place | as xs:stringas xs:string?as xs:string? | := () |
) as xs:dayTimeDuration |
- Properties
The one-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on default place.
The two-argument form of this function is deterministic, context-independent, and focus-independent.
- Rules
This function uses a database of civil timezones (including daylight savings time) to return the timezone offset for a given date/time and place. For example, the timezone offset for New York on 31 December 2024 would be -PT5H.
If the $place argument is omitted or empty then the default placeXP from the dynamic context is used.
If the supplied $value has no timezone then the implicit timezone from the dynamic context is used. This is unrelated to the timezone applicable to the requested $place.
The intended use of the $place argument is to identify the place where an event represented by the $value argument took place or will take place. The value must be an IANA timezone name as defined in the IANA timezone database [IANA Timezone Database]. Examples are "America/New_York" and "Europe/Rome".
The result of the function is the civil timezone offset applicable to the given date/time and place, as determined by the IANA timezone database or an alternative authoritative source.
- Error Conditions
A dynamic error is raised [err:FODT0004] if no timezone information is available for the given date/time and place. This includes the case where the given place is not present in the timezone database, and also the case where the information available for that place does not cover a sufficient range of dates.
- Examples
| Expression: | civil-timezone(
xs:dateTime('2024-12-31T23:59:59'), 'America/New_York') |
|---|
| Result: | xs:dayTimeDuration('-PT5H') |
|---|
| Expression: | civil-timezone(
xs:dateTime('2024-06-30T23:59:59'), 'America/New_York') |
|---|
| Result: | xs:dayTimeDuration('-PT4H') |
|---|
The expression: |
adjust-dateTime-to-timezone(
current-dateTime(),
civil-timezone(current-dateTime(), 'America/New_York')
) |
returns the current civil date and time in New York. |
If the default place is a location in the same timezone as (say) Paris, then the expression |
civil-timezone(xs:dateTime('2024-07-01T09:00:00')) |
returns PT2H. |