XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (524 page)

Usage

Values of types
xs:dateTime
,
xs:time
, and
xs:date()
either have a timezone component, or have no timezone. If they have a timezone component, it is useful to think in terms of two properties of the value, which we can call the local value and the absolute value. For example suppose you call
current-time()
and the implicit timezone is the timezone for Germany, +01:00. The value returned might be 14:54:06+ 01:00. The absolute value of this is the equivalent time in UTC (or “Zulu time”, popularly Greenwich Mean Time or GMT). This is 13:54:06. The local value is the time in its original timezone, 14:54:06.

Converting the value to a string always gives you the local value: 14:54:06+01:00. Getting the components of the value also returns a component of the local value:
hours-from-time()
applied to this value returns 14. But comparisons between two values, or calculations such as adding a duration, use the absolute value.

You can in effect freeze a value in its current timezone by calling
adjust-X-to-timezone()
with an empty sequence
()
as the second argument. Applied to this value, the result will be the time 14:54:06, with no timezone component. Calling
hours-from-time()
on this value will still return 14.

You can also determine the equivalent time in a different timezone by calling
adjust-X-to-timezone()
specifying the new timezone. If the input value is 14:54:06+01:00, and the new timezone is +00:00, the result will be a time value whose absolute value and local value are both 13:54:06. When you convert this to a string, the value is
13:54:06Z
, and when you call
hours-from-time()
, the result is
13
. Similarly, if you adjust this value to the timezone −05:00 (New York time), the absolute value will still be 13:54:06, but the local value will be 08:54:06.

If you have a value with no timezone component, you can set a timezone, either by supplying the required timezone in the second argument or by omitting the second argument, which sets the timezone to the implicit timezone taken from the evaluation context. When you do this, the local value of the result will be the same as the timezoneless input value. For example, if the input is 14:54:06, and you set the timezone to −08:00, then the local value of the result will be 14:54:06, which means that its absolute value will be 22:54:06. When you convert the result to a string, the result will be
14:54:06-08:00
, and when you extract the hours component, the result will be
14
.

The functions work slightly differently for the three types:

• For
  xs:dateTime
  , an adjustment to the time may also cause the date to change. For example, if the input time is 2008:02:29T22:00:00Z, then adjusting the timezone to +10:00 will produce the local value 2008:03:01T08:00:00+10:00.
  
• For
  xs:time
  , all adjustments are made modulo 24 hours.
  
• For
  xs:date
  , the value is treated as if it were an
  xs:dateTime
  representing 00:00:00 on the specified date. The adjustment is made to this
  xs:dateTime
  , and the time component is then removed. For example, if the input date is 2004:03:31+00:00, then adjusting the timezone to −05:00 will return the date 2004:02:29−05:00. This involves an inevitable loss of information. You can read the semantics of the function as being “tell me what the date is in a place in timezone X, at the time when the day represented by a given date has just started in timezone Y”.
  

See Also

implicit-timezone()
on page 806

avg

The
avg()
function returns the average of a sequence of numbers or durations.