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.
The operators described in this section are defined on the following date and time types:
xs:dateTime
xs:date
xs:time
xs:gYearMonth
xs:gYear
xs:gMonthDay
xs:gMonth
xs:gDay
The only operation defined on
xs:gYearMonth
, xs:gYear
,
xs:gMonthDay
, xs:gMonth
and xs:gDay
values is
equality comparison.
For other types, further operations are provided, including component extraction,
order comparisons, arithmetic, formatted display, and timezone
adjustment.
All minimally conforming processors must support positive year values with a minimum of 4 digits (i.e., YYYY) and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, conforming processors may set larger ·implementation-defined· limits on the maximum number of digits they support in these two situations. Processors may also choose to support the year 0000 and years with negative values. The results of operations on dates that cross the year 0000 are ·implementation-defined·.
A processor that limits the number of digits in date and time datatype representations may encounter overflow and underflow conditions when it tries to execute the functions in 9.7 Arithmetic operators on durations, dates and times. In these situations, the processor must return 00:00:00 in case of time underflow. It must raise a dynamic error [err:FODT0001] in case of overflow.
As defined in Section
3.3.2 Dates and Times
DM31, 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 first five components are
xs:integer
values. The value of the second
component is an xs:decimal
and the value of the timezone
component is an xs:dayTimeDuration
.
For all the primitive 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 absentDM31.
Absent, or missing, properties are represented by the empty sequence.
This value is referred to as the local value in that the value retains its original timezone.
Before comparing or subtracting xs:dateTime
values, this local value must
be translated or normalized to UTC.
For xs:time
, 00:00:00
and 24:00:00
are alternate lexical forms
for the same value, whose canonical representation is 00:00:00
. For xs:dateTime
,
a time component 24:00:00
translates to 00:00:00
of the following day.
An xs:dateTime
with lexical
representation 1999-05-31T05:00:00
is represented in the datamodel by {1999, 5, 31, 5, 0, 0.0, ()}
.
An xs:dateTime
with lexical
representation 1999-05-31T13:20:00-05:00
is represented by {1999, 5, 31, 13, 20, 0.0, -PT5H}
.
An xs:dateTime
with lexical
representation 1999-12-31T24:00:00
is represented by {2000, 1, 1, 0, 0, 0.0, ()}
.
An xs:date
with lexical
representation 2005-02-28+8:00
is represented by {2005, 2, 28, (), (), (), PT8H}
.
An xs:time
with lexical
representation 24:00:00
is represented by {(), (), (), 0, 0, 0, ()}
.
A function is provided for constructing a
xs:dateTime
value from a xs:date
value and a
xs:time
value.
Function | Meaning |
---|---|
fn:dateTime |
Returns an xs:dateTime value created by combining an xs:date
and an xs:time . |
Returns an xs:dateTime
value created by combining an xs:date
and an xs:time
.
fn:dateTime ( |
||
$date |
as xs:date? , |
|
$time |
as xs:time? |
|
) as xs:dateTime? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If either $date
or $time
is the empty sequence the function
returns the empty sequence.
Otherwise, the function returns an xs:dateTime
whose date component is
equal to $date
and whose time component is equal to $time
.
The timezone of the result is computed as follows:
If neither argument has a timezone, the result has no timezone.
If exactly one of the arguments has a timezone, or if both arguments have the same timezone, the result has this timezone.
A dynamic error is raised [err:FORG0008] if the two arguments both have timezones and the timezones are different.
The expression fn:dateTime(xs:date("1999-12-31"),
xs:time("12:00:00"))
returns xs:dateTime("1999-12-31T12:00:00")
.
The expression fn:dateTime(xs:date("1999-12-31"),
xs:time("24:00:00"))
returns xs:dateTime("1999-12-31T00:00:00")
. (This is because "24:00:00"
is an alternate lexical form
for "00:00:00"
).
Function | Meaning |
---|---|
op:dateTime-equal |
Returns true if the two supplied xs:dateTime values refer to the same
instant in time. |
op:dateTime-less-than |
Returns true if the first argument represents an earlier instant in time
than the second argument. |
op:date-equal |
Returns true if and only if the starting instants of the two supplied
xs:date values are the same. |
op:date-less-than |
Returns true if and only if the starting instant of $arg1 is
less than the starting instant of $arg2 . Returns false
otherwise. |
op:time-equal |
Returns true if the two xs:time values represent the same
instant in time, when treated as being times on the same date, before adjusting the
timezone. |
op:time-less-than |
Returns true if the first xs:time value represents an earlier
instant in time than the second, when both are treated as being times on the same
date,
before adjusting the timezone. |
op:gYearMonth-equal |
Returns true if the two xs:gYearMonth values have the same starting
instant. |
op:gYear-equal |
Returns true if the two xs:gYear values have the same starting instant. |
op:gMonthDay-equal |
Returns true if the two xs:gMonthDay values have the same starting instant,
when considered as days in the same year. |
op:gMonth-equal |
Returns true if the two xs:gMonth values have the same starting instant,
when considered as months in the same year. |
op:gDay-equal |
Returns true if the two xs:gDay values have the same starting instant, when
considered as days in the same month of the same year. |
The following comparison operators are defined on the [XML Schema Part 2: Datatypes Second Edition]
date/time datatypes. Each operator takes two operands of the same
type and returns an xs:boolean
result.
[XML Schema Part 2: Datatypes Second Edition] also states that the order relation on date and time datatypes is not a total order but a partial order because these datatypes may or may not have a timezone. This is handled as follows. If either operand to a comparison function on date or time values does not have an (explicit) timezone then, for the purpose of the operation, an implicit timezone, provided by the dynamic context Section C.2 Dynamic Context Components XP31, is assumed to be present as part of the value. This creates a total order for all date and time values.
An xs:dateTime
can be considered to consist of seven components:
year
, month
, day
, hour
, minute
,
second
and timezone
. For xs:dateTime
six components (year
,
month
, day
, hour
, minute
and second
) are required
and timezone
is optional. For other date/time values, of the first six components, some are required
and others must be absentDM31.
Timezone
is always optional. For example, for xs:date
,
the year
, month
and day
components are required and hour
,
minute
and second
components must be absent; for xs:time
the hour
,
minute
and second
components are required and year
, month
and
day
are missing; for xs:gDay
, day
is required and year
,
month
, hour
, minute
and second
are missing.
Note:
In [Schema 1.1 Part 2], a new explicitTimezone
facet is available with values
optional
, required
, or prohibited
to
enable the timezone to be defined as mandatory or disallowed.
Values of the date/time datatypes xs:time
, xs:gMonthDay
, xs:gMonth
,
and xs:gDay
, can be considered to represent a sequence of recurring time instants or time periods.
An xs:time
occurs every day. An xs:gMonth
occurs every year. Comparison operators
on these datatypes compare the starting instants of equivalent occurrences in the recurring series.
These xs:dateTime
values are calculated as described below.
Comparison operators on xs:date
, xs:gYearMonth
and xs:gYear
compare
their starting instants. These xs:dateTime
values are calculated as described below.
The starting instant of an occurrence of a date/time value is an xs:dateTime
calculated by filling
in the missing components of the local value from a reference xs:dateTime
. An example of a suitable
reference xs:dateTime
is 1972-01-01T00:00:00
. Then, for example, the starting
instant corresponding to the xs:date
value 2009-03-12
is
2009-03-12T00:00:00
; the starting instant corresponding to the xs:time
value
13:30:02
is 1972-01-01T13:30:02
; and the starting instant corresponding to the
gMonthDay
value --02-29
is 1972-02-29T00:00:00
(which explains
why a leap year was chosen for the reference).
Note:
In the previous version of this specification, the reference date/time chosen was
1972-12-31T00:00:00
. While this gives the same results, it produces a "starting instant" for
a gMonth
or gMonthDay
that bears no
relation to the ordinary meaning of the term, and it also required special handling of short months.
The original choice was made to allow for leap seconds; but since leap seconds are not recognized
in date/time arithmetic, this is not actually necessary.
If the xs:time
value written as
24:00:00
is to be compared, filling in the missing components gives 1972-01-01T00:00:00
,
because 24:00:00
is an alternative representation of 00:00:00
(the lexical value
"24:00:00"
is
converted to the time components {0,0,0} before the missing components are filled
in). This has the consequence that when ordering xs:time
values,
24:00:00
is
considered to be earlier than 23:59:59
. However, when ordering
xs:dateTime
values, a time component of 24:00:00
is considered equivalent to 00:00:00
on the
following day.
Note that the reference xs:dateTime
does not have a timezone. The timezone
component
is never filled in from the reference xs:dateTime
. In some cases, if the date/time value does not
have a timezone, the implicit timezone from the dynamic context is used as the timezone.
Note:
This specification uses the reference xs:dateTime 1972-01-01T00:00:00
in the description of the
comparison operators. Implementations may use other reference xs:dateTime
values
as long as they yield the same results. The reference xs:dateTime
used must meet the following
constraints: when it is used to supply components into xs:gMonthDay
values, the year must allow
for February 29 and so must be a leap year; when it is used to supply missing components into xs:gDay
values, the month must allow for 31 days. Different reference xs:dateTime
values may be used for
different operators.
Returns true if the two supplied xs:dateTime
values refer to the same
instant in time.
Defines the
semantics of the "eq" operator when applied to two xs:dateTime
values. Also
used in the definition of the "ne", "le" and "ge" operators.
op:dateTime-equal ( |
||
$arg1 |
as xs:dateTime , |
|
$arg2 |
as xs:dateTime |
|
) as xs:boolean |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
If either $arg1
or $arg2
has no timezone component, the
effective value of the argument is obtained by substituting the implicit timezone from
the dynamic evaluation context.
The function then returns true
if and only if the effective value of
$arg1
is equal to the effective 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. Otherwise the function returns false
.
Assume that the dynamic context provides an implicit timezone value of
-05:00
The expression op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00-01:00"),
xs:dateTime("2002-04-02T17:00:00+04:00"))
returns true()
.
The expression op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"),
xs:dateTime("2002-04-02T23:00:00+06:00"))
returns true()
.
The expression op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"),
xs:dateTime("2002-04-02T17:00:00"))
returns false()
.
The expression op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"),
xs:dateTime("2002-04-02T12:00:00"))
returns true()
.
The expression op:dateTime-equal(xs:dateTime("2002-04-02T23:00:00-04:00"),
xs:dateTime("2002-04-03T02:00:00-01:00"))
returns true()
.
The expression op:dateTime-equal(xs:dateTime("1999-12-31T24:00:00"),
xs:dateTime("2000-01-01T00:00:00"))
returns true()
.
The expression op:dateTime-equal(xs:dateTime("2005-04-04T24:00:00"),
xs:dateTime("2005-04-04T00:00:00"))
returns false()
.
Returns true
if the first argument represents an earlier instant in time
than the second argument.
Defines the
semantics of the "lt" operator when applied to two xs:dateTime
values. Also
used in the definition of the "ge" operator.
op:dateTime-less-than ( |
||
$arg1 |
as xs:dateTime , |
|
$arg2 |
as xs:dateTime |
|
) as xs:boolean |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
If either $arg1
or $arg2
has no timezone component, the
effective value of the argument is obtained by substituting the implicit timezone from
the dynamic evaluation context.
The function then returns true
if and only if the effective value of
$arg1
is less than the effective 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. Otherwise the function returns false
.
Returns true
if and only if the starting instants of the two supplied
xs:date
values are the same.
Defines the
semantics of the "eq" operator when applied to two xs:date
values. Also used
in the definition of the "ne", "le" and "ge" operators.
op:date-equal ( |
||
$arg1 |
as xs:date , |
|
$arg2 |
as xs:date |
|
) as xs:boolean |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instant of an xs:date
is the xs:dateTime
at time
00:00:00
on that date.
The function returns the result of the expression:
op:dateTime-equal(xs:dateTime($arg1), xs:dateTime($arg2))
The expression op:date-equal(xs:date("2004-12-25Z"),
xs:date("2004-12-25+07:00"))
returns false()
. (The starting instants are
xs:dateTime("2004-12-25T00:00:00Z")
and
xs:dateTime("2004-12-25T00:00:00+07:00")
. These are normalized to
xs:dateTime("2004-12-25T00:00:00Z")
and
xs:dateTime("2004-12-24T17:00:00Z")
. ).
The expression op:date-equal(xs:date("2004-12-25-12:00"),
xs:date("2004-12-26+12:00"))
returns true()
.
Returns true
if and only if the starting instant of $arg1
is
less than the starting instant of $arg2
. Returns false
otherwise.
Defines the semantics
of the "lt" operator when applied to two xs:date
values. Also used in the
definition of the "ge" operator.
op:date-less-than ( |
||
$arg1 |
as xs:date , |
|
$arg2 |
as xs:date |
|
) as xs:boolean |
The starting instant of an xs:date
is the xs:dateTime
at time
00:00:00
on that date.
The function returns the result of the expression:
op:dateTime-less-than(xs:dateTime($arg1), xs:dateTime($arg2))
The expression op:date-less-than(xs:date("2004-12-25Z"),
xs:date("2004-12-25-05:00"))
returns true()
.
The expression op:date-less-than(xs:date("2004-12-25-12:00"),
xs:date("2004-12-26+12:00"))
returns false()
.
Returns true
if the two xs:time
values represent the same
instant in time, when treated as being times on the same date, before adjusting the
timezone.
Defines the
semantics of the "eq" operator when applied to two xs:time
values. Also used
in the definition of the "ne", "le" and "ge" operators.
op:time-equal ( |
||
$arg1 |
as xs:time , |
|
$arg2 |
as xs:time |
|
) as xs:boolean |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
Each of the supplied xs:time
values is expanded to an
xs:dateTime
value by associating the time with an arbitrary date. The
function returns the result of comparing these two xs:dateTime
values using
op:dateTime-equal
.
The result of the function is thus the same as the value of the expression:
op:dateTime-equal( fn:dateTime(xs:date('1972-12-31'), $arg1), fn:dateTime(xs:date('1972-12-31'), $arg2))
Assume that the date components from the reference xs:dateTime
correspond to 1972-12-31
.
The expression op:time-equal(xs:time("08:00:00+09:00"),
xs:time("17:00:00-06:00"))
returns false()
. (The xs:dateTime
s calculated using the reference date
components are 1972-12-31T08:00:00+09:00
and
1972-12-31T17:00:00-06:00
. These normalize to
1972-12-30T23:00:00Z
and 1972-12-31T23:00:00Z
.
).
The expression op:time-equal(xs:time("21:30:00+10:30"),
xs:time("06:00:00-05:00"))
returns true()
.
The expression op:time-equal(xs:time("24:00:00+01:00"),
xs:time("00:00:00+01:00"))
returns true()
. (This not the result one might expect. For xs:dateTime
values, a time of 24:00:00
is equivalent to 00:00:00
on
the following day. For xs:time
, the normalization from
24:00:00
to 00:00:00
happens before the
xs:time
is converted into an xs:dateTime
for the
purpose of the equality comparison. For xs:time
, any operation on
24:00:00
produces the same result as the same operation on
00:00:00
because these are two different lexical representations
of the same value. ).
Returns true
if the first xs:time
value represents an earlier
instant in time than the second, when both are treated as being times on the same date,
before adjusting the timezone.
Defines the semantics
of the "lt" operator when applied to two xs:time
values. Also used in the
definition of the "ge" operator.
op:time-less-than ( |
||
$arg1 |
as xs:time , |
|
$arg2 |
as xs:time |
|
) as xs:boolean |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
Each of the supplied xs:time
values is expanded to an
xs:dateTime
value by associating the time with an arbitrary date. The
function returns the result of comparing these two xs:dateTime
values using
op:dateTime-less-than
.
The result of the function is thus the same as the value of the expression:
op:dateTime-less-than( fn:dateTime(xs:date('1972-12-31'), $arg1), fn:dateTime(xs:date('1972-12-31'), $arg2))
Assume that the dynamic context provides an implicit timezone value of
-05:00
.
The expression op:time-less-than(xs:time("12:00:00"),
xs:time("23:00:00+06:00"))
returns false()
.
The expression op:time-less-than(xs:time("11:00:00"),
xs:time("17:00:00Z"))
returns true()
.
The expression op:time-less-than(xs:time("23:59:59"),
xs:time("24:00:00"))
returns false()
.
Returns true if the two xs:gYearMonth
values have the same starting
instant.
Defines the
semantics of the "eq" operator when applied to two xs:gYearMonth
values. Also
used in the definition of the "ne" operator.
op:gYearMonth-equal ( |
||
$arg1 |
as xs:gYearMonth , |
|
$arg2 |
as xs:gYearMonth |
|
) as xs:boolean |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template xxxx-xx-01T00:00:00
. The function
returns the result of comparing these two starting instants using
op:dateTime-equal
.
Assume that the dynamic context provides an implicit timezone value of
-05:00
.
op:gYearMonth-equal(xs:gYearMonth("1986-02"), xs:gYearMonth("1986-03"))
returns false()
. The starting instants are
1986-02-01T00:00:00-05:00
and 1986-03-01T00:00:00
,
respectively.
op:gYearMonth-equal(xs:gYearMonth("1978-03"), xs:gYearMonth("1986-03Z"))
returns false()
. The starting instants are
1978-03-01T00:00:00-05:00
and 1986-03-01T00:00:00Z
,
respectively.
Returns true if the two xs:gYear
values have the same starting instant.
Defines the semantics
of the "eq" operator when applied to two xs:gYear
values. Also used in the
definition of the "ne" operator.
op:gYear-equal ( |
||
$arg1 |
as xs:gYear , |
|
$arg2 |
as xs:gYear |
|
) as xs:boolean |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template xxxx-01-01T00:00:00
. The function
returns the result of comparing these two starting instants using
op:dateTime-equal
.
Assume that the dynamic context provides an implicit timezone value of
-05:00
. Assume, also, that the xs:dateTime
template is
xxxx-01-01T00:00:00
.
op:gYear-equal(xs:gYear("2005-12:00"), xs:gYear("2005+12:00"))
returns
false()
. The starting instants are
2005-01-01T00:00:00-12:00
and 2005-01-01T00:00:00+12:00
,
respectively, and normalize to 2005-01-01T12:00:00Z
and
2004-12-31T12:00:00Z
.
The expression op:gYear-equal(xs:gYear("1976-05:00"),
xs:gYear("1976"))
returns true()
.
Returns true if the two xs:gMonthDay
values have the same starting instant,
when considered as days in the same year.
Defines the
semantics of the "eq" operator when applied to two xs:gMonthDay
values. Also
used in the definition of the "ne" operator.
op:gMonthDay-equal ( |
||
$arg1 |
as xs:gMonthDay , |
|
$arg2 |
as xs:gMonthDay |
|
) as xs:boolean |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 1972-xx-xxT00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTime-equal
.
Assume that the dynamic context provides an implicit timezone value of
-05:00
. Assume for the purposes of illustration that the
xs:dateTime
template used is 1972-xx-xxT00:00:00
(this
does not affect the result).
The expression op:gMonthDay-equal(xs:gMonthDay("--12-25-14:00"),
xs:gMonthDay("--12-26+10:00"))
returns true()
. ( The starting instants are 1972-12-25T00:00:00-14:00
and
1972-12-26T00:00:00+10:00
, respectively, and normalize to
1972-12-25T14:00:00Z
and 1972-12-25T14:00:00Z
.
).
The expression op:gMonthDay-equal(xs:gMonthDay("--12-25"),
xs:gMonthDay("--12-26Z"))
returns false()
.
Returns true if the two xs:gMonth
values have the same starting instant,
when considered as months in the same year.
Defines the
semantics of the "eq" operator when applied to two xs:gMonth
values. Also used
in the definition of the "ne" operator.
op:gMonth-equal ( |
||
$arg1 |
as xs:gMonth , |
|
$arg2 |
as xs:gMonth |
|
) as xs:boolean |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 1972-xx-01T00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTime-equal
.
Assume that the dynamic context provides an implicit timezone value of
-05:00
. Assume, also, that the xs:dateTime
template
chosen is 1972-xx-01T00:00:00
.
The expression op:gMonth-equal(xs:gMonth("--12-14:00"),
xs:gMonth("--12+10:00"))
returns false()
. ( The starting instants are 1972-12-01T00:00:00-14:00
and
1972-12-01T00:00:00+10:00
, respectively, and normalize to
1972-11-30T14:00:00Z
and 1972-12-01T14:00:00Z
.
).
The expression op:gMonth-equal(xs:gMonth("--12"),
xs:gMonth("--12Z"))
returns false()
.
Returns true if the two xs:gDay
values have the same starting instant, when
considered as days in the same month of the same year.
Defines the semantics
of the "eq" operator when applied to two xs:gDay
values. Also used in the
definition of the "ne" operator.
op:gDay-equal ( |
||
$arg1 |
as xs:gDay , |
|
$arg2 |
as xs:gDay |
|
) as xs:boolean |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The starting instants of $arg1
and $arg2
are calculated by
supplying the missing components of $arg1
and $arg2
from the
xs:dateTime
template 1972-12-xxT00:00:00
or an equivalent.
The function returns the result of comparing these two starting instants using
op:dateTime-equal
.
Assume that the dynamic context provides an implicit timezone value of
-05:00
. Assume, also, that the xs:dateTime
template is
1972-12-xxT00:00:00
.
The expression op:gDay-equal(xs:gDay("---25-14:00"),
xs:gDay("---25+10:00"))
returns false()
. ( The starting instants are 1972-12-25T00:00:00-14:00
and
1972-12-25T00:00:00+10:00
, respectively, and normalize to
1972-12-25T14:00:00Z
and 1972-12-24T14:00:00Z
.
).
The expression op:gDay-equal(xs:gDay("---12"), xs:gDay("---12Z"))
returns false()
.
The date and time datatypes may be considered to be composite datatypes in that they contain distinct properties or components. The extraction functions specified below extract a single component from a date or time value. In all cases the local value (that is, the original value as written, without any timezone adjustment) is used.
Note:
A time written as 24:00:00
is treated as 00:00:00
on the
following day.
Function | Meaning |
---|---|
fn:year-from-dateTime |
Returns the year component of an xs:dateTime . |
fn:month-from-dateTime |
Returns the month component of an xs:dateTime . |
fn:day-from-dateTime |
Returns the day component of an xs:dateTime . |
fn:hours-from-dateTime |
Returns the hours component of an xs:dateTime . |
fn:minutes-from-dateTime |
Returns the minute component of an xs:dateTime . |
fn:seconds-from-dateTime |
Returns the seconds component of an xs:dateTime . |
fn:timezone-from-dateTime |
Returns the timezone component of an xs:dateTime . |
fn:year-from-date |
Returns the year component of an xs:date . |
fn:month-from-date |
Returns the month component of an xs:date . |
fn:day-from-date |
Returns the day component of an xs:date . |
fn:timezone-from-date |
Returns the timezone component of an xs:date . |
fn:hours-from-time |
Returns the hours component of an xs:time . |
fn:minutes-from-time |
Returns the minutes component of an xs:time . |
fn:seconds-from-time |
Returns the seconds component of an xs:time . |
fn:timezone-from-time |
Returns the timezone component of an xs:time . |
Returns the year component of an xs:dateTime
.
fn:year-from-dateTime ( |
||
$value |
as xs:dateTime? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the year
component in the local value of $value
. The result may be negative.
Ignoring complications that arise with midnight on the last day of the year, the year returned is the same numeric value that appears in the lexical representation, which for negative years means the meaning may vary depending on whether XSD 1.0 or XSD 1.1 conventions are in use.
The expression fn:year-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns 1999
.
The expression fn:year-from-dateTime(xs:dateTime("1999-05-31T21:30:00-05:00"))
returns 1999
.
The expression fn:year-from-dateTime(xs:dateTime("1999-12-31T19:20:00"))
returns 1999
.
The expression fn:year-from-dateTime(xs:dateTime("1999-12-31T24:00:00"))
returns 2000
.
The expression fn:year-from-dateTime(xs:dateTime("-0002-06-06T00:00:00"))
returns -2
. (The result is the same whether XSD 1.0 or 1.1 is in use, despite
the absence of a year 0 in the XSD 1.0 value space.)
Returns the month component of an xs:dateTime
.
fn:month-from-dateTime ( |
||
$value |
as xs:dateTime? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 1 and 12, both
inclusive, representing the month component in the local value of $value
.
The expression fn:month-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns 5
.
The expression fn:month-from-dateTime(xs:dateTime("1999-12-31T19:20:00-05:00"))
returns 12
.
The expression fn:month-from-dateTime(fn:adjust-dateTime-to-timezone(xs:dateTime("1999-12-31T19:20:00-05:00"),
xs:dayTimeDuration("PT0S")))
returns 1
.
Returns the day component of an xs:dateTime
.
fn:day-from-dateTime ( |
||
$value |
as xs:dateTime? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 1 and 31, both
inclusive, representing the day component in the local value of $value
.
The expression fn:day-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns 31
.
The expression fn:day-from-dateTime(xs:dateTime("1999-12-31T20:00:00-05:00"))
returns 31
.
The expression fn:day-from-dateTime(fn:adjust-dateTime-to-timezone(xs:dateTime("1999-12-31T19:20:00-05:00"),
xs:dayTimeDuration("PT0S")))
returns 1
.
Returns the hours component of an xs:dateTime
.
fn:hours-from-dateTime ( |
||
$value |
as xs:dateTime? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 0 and 23, both
inclusive, representing the hours component in the local value of $value
.
The expression fn:hours-from-dateTime(xs:dateTime("1999-05-31T08:20:00-05:00"))
returns 8
.
The expression fn:hours-from-dateTime(xs:dateTime("1999-12-31T21:20:00-05:00"))
returns 21
.
The expression fn:hours-from-dateTime(fn:adjust-dateTime-to-timezone(xs:dateTime("1999-12-31T21:20:00-05:00"),
xs:dayTimeDuration("PT0S")))
returns 2
.
The expression fn:hours-from-dateTime(xs:dateTime("1999-12-31T12:00:00"))
returns 12
.
The expression fn:hours-from-dateTime(xs:dateTime("1999-12-31T24:00:00"))
returns 0
.
Returns the minute component of an xs:dateTime
.
fn:minutes-from-dateTime ( |
||
$value |
as xs:dateTime? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
value between 0 and 59, both
inclusive, representing the minute component in the local value of
$value
.
The expression fn:minutes-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns 20
.
The expression fn:minutes-from-dateTime(xs:dateTime("1999-05-31T13:30:00+05:30"))
returns 30
.
Returns the seconds component of an xs:dateTime
.
fn:seconds-from-dateTime ( |
||
$value |
as xs:dateTime? |
|
) as xs:decimal? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal
value greater than or equal
to zero and less than 60, representing the seconds and fractional seconds in the local
value of $value
.
The expression fn:seconds-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns 0
.
Returns the timezone component of an xs:dateTime
.
fn:timezone-from-dateTime ( |
||
$value |
as xs:dateTime? |
|
) as xs:dayTimeDuration? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value
, if any. If
$value
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. If $value
has no timezone
component, the result is the empty sequence.
The expression fn:timezone-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns xs:dayTimeDuration("-PT5H")
.
The expression fn:timezone-from-dateTime(xs:dateTime("2000-06-12T13:20:00Z"))
returns xs:dayTimeDuration("PT0S")
.
The expression fn:timezone-from-dateTime(xs:dateTime("2004-08-27T00:00:00"))
returns ()
.
Returns the year component of an xs:date
.
fn:year-from-date ( |
||
$value |
as xs:date? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the year in the
local value of $value
. The value may be negative.
The year returned is the same numeric value that appears in the lexical representation, which for negative years means the meaning may vary depending on whether XSD 1.0 or XSD 1.1 conventions are in use.
The expression fn:year-from-date(xs:date("1999-05-31"))
returns 1999
.
The expression fn:year-from-date(xs:date("2000-01-01+05:00"))
returns 2000
.
The expression fn:year-from-date(xs:date("-0002-06-01"))
returns -2
. (The result is the same whether XSD 1.0 or 1.1 is in use, despite
the absence of a year 0 in the XSD 1.0 value space.)
Returns the month component of an xs:date
.
fn:month-from-date ( |
||
$value |
as xs:date? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 1 and 12, both
inclusive, representing the month component in the local value of $value
.
The expression fn:month-from-date(xs:date("1999-05-31-05:00"))
returns 5
.
The expression fn:month-from-date(xs:date("2000-01-01+05:00"))
returns 1
.
Returns the day component of an xs:date
.
fn:day-from-date ( |
||
$value |
as xs:date? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 1 and 31, both
inclusive, representing the day component in the localized value of
$value
.
The expression fn:day-from-date(xs:date("1999-05-31-05:00"))
returns 31
.
The expression fn:day-from-date(xs:date("2000-01-01+05:00"))
returns 1
.
Returns the timezone component of an xs:date
.
fn:timezone-from-date ( |
||
$value |
as xs:date? |
|
) as xs:dayTimeDuration? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value
, if any. If
$value
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. If $value
has no timezone
component, the result is the empty sequence.
The expression fn:timezone-from-date(xs:date("1999-05-31-05:00"))
returns xs:dayTimeDuration("-PT5H")
.
The expression fn:timezone-from-date(xs:date("2000-06-12Z"))
returns xs:dayTimeDuration("PT0S")
.
Returns the hours component of an xs:time
.
fn:hours-from-time ( |
||
$value |
as xs:time? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
between 0 and 23, both
inclusive, representing the value of the hours component in the local value of
$value
.
Assume that the dynamic context provides an implicit timezone value of
-05:00
.
The expression fn:hours-from-time(xs:time("11:23:00"))
returns 11
.
The expression fn:hours-from-time(xs:time("21:23:00"))
returns 21
.
The expression fn:hours-from-time(xs:time("01:23:00+05:00"))
returns 1
.
The expression fn:hours-from-time(fn:adjust-time-to-timezone(xs:time("01:23:00+05:00"),
xs:dayTimeDuration("PT0S")))
returns 20
.
The expression fn:hours-from-time(xs:time("24:00:00"))
returns 0
.
Returns the minutes component of an xs:time
.
fn:minutes-from-time ( |
||
$value |
as xs:time? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
value between 0 and 59, both
inclusive, representing the value of the minutes component in the local value of
$value
.
The expression fn:minutes-from-time(xs:time("13:00:00Z"))
returns 0
.
Returns the seconds component of an xs:time
.
fn:seconds-from-time ( |
||
$value |
as xs:time? |
|
) as xs:decimal? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal
value greater than or equal
to zero and less than 60, representing the seconds and fractional seconds in the local
value of $value
.
The expression fn:seconds-from-time(xs:time("13:20:10.5"))
returns 10.5
.
Returns the timezone component of an xs:time
.
fn:timezone-from-time ( |
||
$value |
as xs:time? |
|
) as xs:dayTimeDuration? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns the timezone component of $value
, if any. If
$value
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. If $value
has no timezone
component, the result is the empty sequence.
The expression fn:timezone-from-time(xs:time("13:20:00-05:00"))
returns xs:dayTimeDuration("-PT5H")
.
The expression fn:timezone-from-time(xs:time("13:20:00"))
returns ()
.
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. |
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.
Adjusts an xs:dateTime
value to a specific timezone, or to no timezone at
all.
fn:adjust-dateTime-to-timezone ( |
||
$value |
as xs:dateTime? |
|
) as xs:dateTime? |
fn:adjust-dateTime-to-timezone ( |
||
$value |
as xs:dateTime? , |
|
$timezone |
as xs:dayTimeDuration? |
|
) as xs:dateTime? |
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the local value of $value
without its timezone
component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then the result is the xs:dateTime
value that is equal to
$value
and that has a timezone component equal to
$timezone
.
A dynamic error is raised [err:FODT0003] if $timezone
is less than -PT14H
or greater than PT14H
or is not an
integral number of minutes.
Assume the dynamic context provides an implicit timezone of -05:00
(-PT5H0M)
.
let $tz-10 := xs:dayTimeDuration("-PT10H")
The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00'))
returns xs:dateTime('2002-03-07T10:00:00-05:00')
.
The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00-07:00'))
returns xs:dateTime('2002-03-07T12:00:00-05:00')
.
The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00'),
$tz-10)
returns xs:dateTime('2002-03-07T10:00:00-10:00')
.
The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00-07:00'),
$tz-10)
returns xs:dateTime('2002-03-07T07:00:00-10:00')
.
The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00-07:00'),
xs:dayTimeDuration("PT10H"))
returns xs:dateTime('2002-03-08T03:00:00+10:00')
.
The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T00:00:00+01:00'),
xs:dayTimeDuration("-PT8H"))
returns xs:dateTime('2002-03-06T15:00:00-08:00')
.
The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00'),
())
returns xs:dateTime('2002-03-07T10:00:00')
.
The expression fn:adjust-dateTime-to-timezone(xs:dateTime('2002-03-07T10:00:00-07:00'),
())
returns xs:dateTime('2002-03-07T10:00:00')
.
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-date-to-timezone ( |
||
$value |
as xs:date? |
|
) as xs:date? |
fn:adjust-date-to-timezone ( |
||
$value |
as xs:date? , |
|
$timezone |
as xs:dayTimeDuration? |
|
) as xs:date? |
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the local value of $value
without its timezone
component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then the function returns the value of the expression:
Let $dt
be the value of fn:dateTime($arg,
xs:time('00:00:00'))
.
Let $adt
be the value of fn:adjust-dateTime-to-timezone($dt,
$timezone)
The function returns the value of xs:date($adt)
A dynamic error is raised [err:FODT0003] if $timezone
is less than -PT14H
or greater than PT14H
or is not an
integral number of minutes.
Assume the dynamic context provides an implicit timezone of -05:00
(-PT5H0M)
.
let $tz-10 := xs:dayTimeDuration("-PT10H")
The expression fn:adjust-date-to-timezone(xs:date("2002-03-07"))
returns xs:date("2002-03-07-05:00")
.
The expression fn:adjust-date-to-timezone(xs:date("2002-03-07-07:00"))
returns xs:date("2002-03-07-05:00")
. ($value
is converted to
xs:dateTime("2002-03-07T00:00:00-07:00")
. This is adjusted to the
implicit timezone, giving "2002-03-07T02:00:00-05:00"
.
).
The expression fn:adjust-date-to-timezone(xs:date("2002-03-07"),
$tz-10)
returns xs:date("2002-03-07-10:00")
.
The expression fn:adjust-date-to-timezone(xs:date("2002-03-07-07:00"),
$tz-10)
returns xs:date("2002-03-06-10:00")
. ($value
is converted to the xs:dateTime
"2002-03-07T00:00:00-07:00"
. This is adjusted to the given timezone,
giving "2002-03-06T21:00:00-10:00"
. ).
The expression fn:adjust-date-to-timezone(xs:date("2002-03-07"),
())
returns xs:date("2002-03-07")
.
The expression fn:adjust-date-to-timezone(xs:date("2002-03-07-07:00"),
())
returns xs:date("2002-03-07")
.
Adjusts an xs:time
value to a specific timezone, or to no timezone at
all.
fn:adjust-time-to-timezone ( |
||
$value |
as xs:time? |
|
) as xs:time? |
fn:adjust-time-to-timezone ( |
||
$value |
as xs:time? , |
|
$timezone |
as xs:dayTimeDuration? |
|
) as xs:time? |
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $timezone
is not specified, then the effective value of
$timezone
is the value of the implicit timezone in the dynamic
context.
If $value
is the empty sequence, then the function returns the empty
sequence.
If $value
does not have a timezone component and $timezone
is
the empty sequence, then the result is $value
.
If $value
does not have a timezone component and $timezone
is
not the empty sequence, then the result is $value
with $timezone
as the timezone component.
If $value
has a timezone component and $timezone
is the empty
sequence, then the result is the localized value of $value
without its
timezone component.
If $value
has a timezone component and $timezone
is not the
empty sequence, then:
Let $dt
be the xs:dateTime
value
fn:dateTime(xs:date('1972-12-31'), $value)
.
Let $adt
be the value of fn:adjust-dateTime-to-timezone($dt,
$timezone)
The function returns the xs:time
value
xs:time($adt)
.
A dynamic error is raised [err:FODT0003] if $timezone
is less than -PT14H
or greater than PT14H
or if does not
contain an integral number of minutes.
Assume the dynamic context provides an implicit timezone of -05:00
(-PT5H0M)
.
let $tz-10 := xs:dayTimeDuration("-PT10H")
The expression fn:adjust-time-to-timezone(xs:time("10:00:00"))
returns xs:time("10:00:00-05:00")
.
The expression fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"))
returns xs:time("12:00:00-05:00")
.
The expression fn:adjust-time-to-timezone(xs:time("10:00:00"),
$tz-10)
returns xs:time("10:00:00-10:00")
.
The expression fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"),
$tz-10)
returns xs:time("07:00:00-10:00")
.
The expression fn:adjust-time-to-timezone(xs:time("10:00:00"), ())
returns xs:time("10:00:00")
.
The expression fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"),
())
returns xs:time("10:00:00")
.
The expression fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"),
xs:dayTimeDuration("PT10H"))
returns xs:time("03:00:00+10:00")
.
These functions support adding or subtracting a duration value to or from an
xs:dateTime
, an xs:date
or an xs:time
value. Appendix E of [XML Schema Part 2: Datatypes Second Edition] describes an algorithm for
performing such operations.
Function | Meaning |
---|---|
op:subtract-dateTimes |
Returns an xs:dayTimeDuration representing the amount of elapsed time
between the instants arg2 and arg1 . |
op:subtract-dates |
Returns the xs:dayTimeDuration that corresponds to the elapsed time between
the starting instant of $arg2 and the starting instant of
$arg2 . |
op:subtract-times |
Returns the xs:dayTimeDuration that corresponds to the elapsed time between
the values of $arg2 and $arg1 treated as times on the same
date. |
op:add-yearMonthDuration-to-dateTime |
Returns the xs:dateTime that is a given duration after a specified
xs:dateTime (or before, if the duration is negative). |
op:add-dayTimeDuration-to-dateTime |
Returns the xs:dateTime that is a given duration after a specified
xs:dateTime (or before, if the duration is negative). |
op:subtract-yearMonthDuration-from-dateTime |
Returns the xs:dateTime that is a given duration before a specified
xs:dateTime (or after, if the duration is negative). |
op:subtract-dayTimeDuration-from-dateTime |
Returns the xs:dateTime that is a given duration before a specified
xs:dateTime (or after, if the duration is negative). |
op:add-yearMonthDuration-to-date |
Returns the xs:date that is a given duration after a specified
xs:date (or before, if the duration is negative). |
op:add-dayTimeDuration-to-date |
Returns the xs:date that is a given duration after a specified
xs:date (or before, if the duration is negative). |
op:subtract-yearMonthDuration-from-date |
Returns the xs:date that is a given duration before a specified
xs:date (or after, if the duration is negative). |
op:subtract-dayTimeDuration-from-date |
Returns the xs:date that is a given duration before a specified
xs:date (or after, if the duration is negative). |
op:add-dayTimeDuration-to-time |
Returns the xs:time value that is a given duration after a specified
xs:time (or before, if the duration is negative or causes wrap-around
past midnight) |
op:subtract-dayTimeDuration-from-time |
Returns the xs:time value that is a given duration before a specified
xs:time (or after, if the duration is negative or causes wrap-around
past midnight) |
A processor that limits the number of digits in date and time datatype representations may encounter overflow and underflow conditions when it tries to execute the functions in this section. In these situations, the processor must return P0M or PT0S in case of duration underflow and 00:00:00 in case of time underflow. It must raise a dynamic error [err:FODT0001] in case of overflow.
The value spaces of the two totally ordered subtypes of
xs:duration
described in 8.1 Two totally ordered subtypes of duration are
xs:integer
months for xs:yearMonthDuration
and xs:decimal
seconds for xs:dayTimeDuration
. If
a processor limits the number of digits allowed in the representation of
xs:integer
and xs:decimal
then overflow and
underflow situations can arise when it tries to execute the functions in
8.4 Arithmetic operators on durations. In these situations the processor
must return zero in case of numeric underflow and P0M
or PT0S in case of duration underflow. It must raise a
dynamic error [err:FODT0002] in case of overflow.
Returns an xs:dayTimeDuration
representing the amount of elapsed time
between the instants arg2
and arg1
.
Defines the semantics of the "-"
operator when applied to two xs:dateTime
values.
op:subtract-dateTimes ( |
||
$arg1 |
as xs:dateTime , |
|
$arg2 |
as xs:dateTime |
|
) as xs:dayTimeDuration |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
If either $arg1
or $arg2
do not contain an explicit timezone
then, for the purpose of the operation, the implicit timezone provided by the dynamic
context (See Section
C.2 Dynamic Context Components
XP31.) is
assumed to be present as part of the value.
The function returns the elapsed time between the date/time instant arg2
and the date/time instant arg1
, computed according to the algorithm given
in Appendix E of [XML Schema Part 2: Datatypes Second Edition], and expressed as a
xs:dayTimeDuration
.
If the normalized value of $arg1
precedes in time the normalized value of
$arg2
, then the returned value is a negative duration.
Assume that the dynamic context provides an implicit timezone value of
-05:00
.
The expression op:subtract-dateTimes(xs:dateTime("2000-10-30T06:12:00"),
xs:dateTime("1999-11-28T09:00:00Z"))
returns xs:dayTimeDuration("P337DT2H12M")
.
Returns the xs:dayTimeDuration
that corresponds to the elapsed time between
the starting instant of $arg2
and the starting instant of
$arg2
.
Defines the semantics of the "-" operator
when applied to two xs:date
values.
op:subtract-dates ( |
||
$arg1 |
as xs:date , |
|
$arg2 |
as xs:date |
|
) as xs:dayTimeDuration |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
If either $arg1
or $arg2
do not contain an explicit timezone
then, for the purpose of the operation, the implicit timezone provided by the dynamic
context (See Section
C.2 Dynamic Context Components
XP31.) is
assumed to be present as part of the value.
The starting instant of an xs:date
is the xs:dateTime
at
00:00:00
on that date.
The function returns the result of subtracting the two starting instants using
op:subtract-dateTimes
.
If the starting instant of $arg1
precedes in time the starting instant of
$arg2
, then the returned value is a negative duration.
Assume that the dynamic context provides an implicit timezone value of
Z
.
The expression op:subtract-dates(xs:date("2000-10-30"),
xs:date("1999-11-28"))
returns xs:dayTimeDuration("P337D")
. (The normalized values of the two starting instants are {2000,
10, 30, 0, 0, 0, PT0S}
and {1999, 11, 28, 0, 0, 0,
PT0S}
.)
Now assume that the dynamic context provides an implicit timezone value of
+05:00
.
The expression op:subtract-dates(xs:date("2000-10-30"),
xs:date("1999-11-28Z"))
returns xs:dayTimeDuration("P336DT19H")
. ( The normalized values of the two starting instants are {2000,
10, 29, 19, 0, 0, PT0S}
and {1999, 11, 28, 0, 0, 0,
PT0S}
.)
The expression op:subtract-dates(xs:date("2000-10-15-05:00"),
xs:date("2000-10-10+02:00"))
returns xs:dayTimeDuration("P5DT7H")
.
Returns the xs:dayTimeDuration
that corresponds to the elapsed time between
the values of $arg2
and $arg1
treated as times on the same
date.
Defines the semantics of the "-" operator
when applied to two xs:time
values.
op:subtract-times ( |
||
$arg1 |
as xs:time , |
|
$arg2 |
as xs:time |
|
) as xs:dayTimeDuration |
This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone.
The function returns the result of the expression:
op-subtract-dateTimes( fn:dateTime(xs:date('1972-12-31'), $arg1), fn:dateTime(xs:date('1972-12-31'), $arg2))
Any other reference date would work equally well.
Assume that the dynamic context provides an implicit timezone value of
-05:00
. Assume, also, that the date components of the reference
xs:dateTime
correspond to "1972-12-31"
.
The expression op:subtract-times(xs:time("11:12:00Z"),
xs:time("04:00:00"))
returns xs:dayTimeDuration("PT2H12M")
. (This is obtained by subtracting from the xs:dateTime
value {1972, 12, 31, 11, 12, 0, PT0S}
the xs:dateTime
value {1972, 12, 31, 9, 0, 0, PT0S}
.)
The expression op:subtract-times(xs:time("11:00:00-05:00"),
xs:time("21:30:00+05:30"))
returns xs:dayTimeDuration("PT0S")
. (The two xs:dateTime
values are {1972, 12, 31, 11,
0, 0, -PT5H}
and {1972, 12, 31, 21, 30, 0, PT5H30M}
. These
normalize to {1972, 12, 31, 16, 0, 0, PT0S}
and {1972, 12, 31,
16, 0, 0, PT0S}
. ).
The expression op:subtract-times(xs:time("17:00:00-06:00"),
xs:time("08:00:00+09:00"))
returns xs:dayTimeDuration("P1D")
. (The two normalized xs:dateTime
values are {1972,
12, 31, 23, 0, 0, PT0S}
and {1972, 12, 30, 23, 0, 0,
PT0S}
.)
The expression op:subtract-times(xs:time("24:00:00"),
xs:time("23:59:59"))
returns xs:dayTimeDuration("-PT23H59M59S")
. (The two normalized xs:dateTime
values are {1972,
12, 31, 0, 0, 0, ()}
and {1972, 12, 31, 23, 59, 59.0,
()}
.)
Returns the xs:dateTime
that is a given duration after a specified
xs:dateTime
(or before, if the duration is negative).
Defines the
semantics of the "+" operator when applied to an xs:dateTime
and an
xs:yearMonthDuration
value.
op:add-yearMonthDuration-to-dateTime ( |
||
$arg1 |
as xs:dateTime , |
|
$arg2 |
as xs:yearMonthDuration |
|
) as xs:dateTime |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the result of adding $arg2
to the value of
$arg1
using the algorithm described in Appendix E of [XML Schema Part 2: Datatypes Second Edition], disregarding the rule about leap seconds. If $arg2
is negative, then the result xs:dateTime
precedes $arg1
.
The result has the same timezone as $arg1
. If $arg1
has no
timezone, the result has no timezone.
The expression op:add-yearMonthDuration-to-dateTime(xs:dateTime("2000-10-30T11:12:00"),
xs:yearMonthDuration("P1Y2M"))
returns xs:dateTime("2001-12-30T11:12:00")
.
Returns the xs:dateTime
that is a given duration after a specified
xs:dateTime
(or before, if the duration is negative).
Defines the semantics
of the "+" operator when applied to an xs:dateTime
and an
xs:dayTimeDuration
value.
op:add-dayTimeDuration-to-dateTime ( |
||
$arg1 |
as xs:dateTime , |
|
$arg2 |
as xs:dayTimeDuration |
|
) as xs:dateTime |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the result of adding $arg2
to the value of
$arg1
using the algorithm described in Appendix E of [XML Schema Part 2: Datatypes Second Edition], disregarding the rule about leap seconds. If $arg2
is negative, then the result xs:dateTime
precedes $arg1
.
The result has the same timezone as $arg1
. If $arg1
has no
timezone, the result has no timezone.
The expression op:add-dayTimeDuration-to-dateTime(xs:dateTime("2000-10-30T11:12:00"),
xs:dayTimeDuration("P3DT1H15M"))
returns xs:dateTime("2000-11-02T12:27:00")
.
Returns the xs:dateTime
that is a given duration before a specified
xs:dateTime
(or after, if the duration is negative).
Defines the
semantics of the "-" operator when applied to an xs:dateTime
and an
xs:yearMonthDuration
value.
op:subtract-yearMonthDuration-from-dateTime ( |
||
$arg1 |
as xs:dateTime , |
|
$arg2 |
as xs:yearMonthDuration |
|
) as xs:dateTime |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the xs:dateTime
computed by negating
$arg2
and adding the result to $arg1
using the
function op:add-yearMonthDuration-to-dateTime
.
The expression op:subtract-yearMonthDuration-from-dateTime(xs:dateTime("2000-10-30T11:12:00"),
xs:yearMonthDuration("P1Y2M"))
returns xs:dateTime("1999-08-30T11:12:00")
.
Returns the xs:dateTime
that is a given duration before a specified
xs:dateTime
(or after, if the duration is negative).
Defines the semantics
of the "-" operator when applied to an xs:dateTime
an and
xs:dayTimeDuration
values
op:subtract-dayTimeDuration-from-dateTime ( |
||
$arg1 |
as xs:dateTime , |
|
$arg2 |
as xs:dayTimeDuration |
|
) as xs:dateTime |
The function returns the xs:dateTime
computed by negating
$arg2
and adding the result to $arg1
using the
function op:add-dayTimeDuration-to-dateTime
.
The expression op:subtract-dayTimeDuration-from-dateTime(xs:dateTime("2000-10-30T11:12:00"),
xs:dayTimeDuration("P3DT1H15M"))
returns xs:dateTime("2000-10-27T09:57:00")
.
Returns the xs:date
that is a given duration after a specified
xs:date
(or before, if the duration is negative).
Defines the semantics
of the "+" operator when applied to an xs:date
and an
xs:yearMonthDuration
value.
op:add-yearMonthDuration-to-date ( |
||
$arg1 |
as xs:date , |
|
$arg2 |
as xs:yearMonthDuration |
|
) as xs:date |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the result of casting $arg1
to an
xs:dateTime
, adding $arg2
using the function
op:add-yearMonthDuration-to-dateTime
, and casting the result back to an
xs:date
.
The expression op:add-yearMonthDuration-to-date(xs:date("2000-10-30"),
xs:yearMonthDuration("P1Y2M"))
returns xs:date("2001-12-30")
.
Returns the xs:date
that is a given duration after a specified
xs:date
(or before, if the duration is negative).
Defines the semantics of
the "+" operator when applied to an xs:date
and an
xs:dayTimeDuration
value.
op:add-dayTimeDuration-to-date ( |
||
$arg1 |
as xs:date , |
|
$arg2 |
as xs:dayTimeDuration |
|
) as xs:date |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the result of casting $arg1
to an
xs:dateTime
, adding $arg2
using the function
op:add-dayTimeDuration-to-dateTime
, and casting the result back to an
xs:date
.
The expression op:add-dayTimeDuration-to-date(xs:date("2004-10-30Z"),
xs:dayTimeDuration("P2DT2H30M0S"))
returns xs:date("2004-11-01Z")
. ( The starting instant of the first argument is the
xs:dateTime
value {2004, 10, 30, 0, 0, 0, PT0S}
.
Adding the second argument to this gives the xs:dateTime
value
{2004, 11, 1, 2, 30, 0, PT0S}
. The time components are then
discarded. ).
Returns the xs:date
that is a given duration before a specified
xs:date
(or after, if the duration is negative).
Defines the semantics
of the "-" operator when applied to an xs:date
and an
xs:yearMonthDuration
value.
op:subtract-yearMonthDuration-from-date ( |
||
$arg1 |
as xs:date , |
|
$arg2 |
as xs:yearMonthDuration |
|
) as xs:date |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Returns the xs:date
computed by negating $arg2
and adding the
result to $arg1
using the function
op:add-yearMonthDuration-to-date
.
The expression op:subtract-yearMonthDuration-from-date(xs:date("2000-10-30"),
xs:yearMonthDuration("P1Y2M"))
returns xs:date("1999-08-30")
.
The expression op:subtract-yearMonthDuration-from-date(xs:date("2000-02-29Z"),
xs:yearMonthDuration("P1Y"))
returns xs:date("1999-02-28Z")
.
The expression op:subtract-yearMonthDuration-from-date(xs:date("2000-10-31-05:00"),
xs:yearMonthDuration("P1Y1M"))
returns xs:date("1999-09-30-05:00")
.
Returns the xs:date
that is a given duration before a specified
xs:date
(or after, if the duration is negative).
Defines the semantics of
the "-" operator when applied to an xs:date
and an
xs:dayTimeDuration
.
op:subtract-dayTimeDuration-from-date ( |
||
$arg1 |
as xs:date , |
|
$arg2 |
as xs:dayTimeDuration |
|
) as xs:date |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Returns the xs:date
computed by negating $arg2
and adding the
result to $arg1
using the function
op:add-dayTimeDuration-to-date
.
The expression op:subtract-dayTimeDuration-from-date(xs:date("2000-10-30"),
xs:dayTimeDuration("P3DT1H15M"))
returns xs:date("2000-10-26")
.
Returns the xs:time
value that is a given duration after a specified
xs:time
(or before, if the duration is negative or causes wrap-around
past midnight)
Defines the semantics of
the "+" operator when applied to an xs:time
and an
xs:dayTimeDuration
value.
op:add-dayTimeDuration-to-time ( |
||
$arg1 |
as xs:time , |
|
$arg2 |
as xs:dayTimeDuration |
|
) as xs:time |
First, the days component in the canonical lexical representation of $arg2
is set to zero (0) and the value of the resulting xs:dayTimeDuration
is
calculated. Alternatively, the value of $arg2
modulus 86,400 is used as the
second argument. This value is added to the value of $arg1
converted to an
xs:dateTime
using a reference date such as 1972-12-31
, and
the time component of the result is returned. Note that the xs:time
returned may occur in a following or preceding day and may be less than
$arg1
.
The result has the same timezone as $arg1
. If $arg1
has no
timezone, the result has no timezone.
The expression op:add-dayTimeDuration-to-time(xs:time("11:12:00"),
xs:dayTimeDuration("P3DT1H15M"))
returns xs:time("12:27:00")
.
The expression op:add-dayTimeDuration-to-time(xs:time("23:12:00+03:00"),
xs:dayTimeDuration("P1DT3H15M"))
returns xs:time("02:27:00+03:00")
. (That is, {0, 0, 0, 2, 27, 0, PT3H}
).
Returns the xs:time
value that is a given duration before a specified
xs:time
(or after, if the duration is negative or causes wrap-around
past midnight)
Defines the semantics of
the "-" operator when applied to an xs:time
and an
xs:dayTimeDuration
value.
op:subtract-dayTimeDuration-from-time ( |
||
$arg1 |
as xs:time , |
|
$arg2 |
as xs:dayTimeDuration |
|
) as xs:time |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the result of negating $arg2
and adding the result to
$arg1
using the function op:add-dayTimeDuration-to-time
.
The expression op:subtract-dayTimeDuration-from-time(xs:time("11:12:00"),
xs:dayTimeDuration("P3DT1H15M"))
returns xs:time("09:57:00")
.
The expression op:subtract-dayTimeDuration-from-time(xs:time("08:20:00-05:00"),
xs:dayTimeDuration("P23DT10H10M"))
returns xs:time("22:10:00-05:00")
.
Function | Meaning |
---|---|
fn:format-dateTime |
Returns a string containing an xs:dateTime value formatted for display. |
fn:format-date |
Returns a string containing an xs:date value formatted for display. |
fn:format-time |
Returns a string containing an xs:time value formatted for display. |
Three functions are provided to represent dates and times as a string, using the conventions of a selected calendar, language, and country. The signatures are presented first, followed by the rules which apply to each of the functions.
Returns a string containing an xs:dateTime
value formatted for display.
fn:format-dateTime ( |
||
$value |
as xs:dateTime? , |
|
$picture |
as xs:string |
|
) as xs:string? |
fn:format-dateTime ( |
||
$value |
as xs:dateTime? , |
|
$picture |
as xs:string , |
|
$language |
as xs:string? , |
|
$calendar |
as xs:string? , |
|
$place |
as xs:string? |
|
) as xs:string? |
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.
The five-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone, and namespaces.
Returns a string containing an xs:date
value formatted for display.
fn:format-date ( |
||
$value |
as xs:date? , |
|
$picture |
as xs:string |
|
) as xs:string? |
fn:format-date ( |
||
$value |
as xs:date? , |
|
$picture |
as xs:string , |
|
$language |
as xs:string? , |
|
$calendar |
as xs:string? , |
|
$place |
as xs:string? |
|
) as xs:string? |
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.
The five-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone, and namespaces.
Returns a string containing an xs:time
value formatted for display.
fn:format-time ( |
||
$value |
as xs:time? , |
|
$picture |
as xs:string |
|
) as xs:string? |
fn:format-time ( |
||
$value |
as xs:time? , |
|
$picture |
as xs:string , |
|
$language |
as xs:string? , |
|
$calendar |
as xs:string? , |
|
$place |
as xs:string? |
|
) as xs:string? |
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default calendar, and default language, and default place, and implicit timezone.
The five-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on implicit timezone, and namespaces.
The fn:format-dateTime
, fn:format-date
,
and fn:format-time
functions format $value
as a string using
the picture string specified by the $picture
argument,
the calendar specified by the $calendar
argument,
the language specified by the $language
argument,
and the country or other place name specified by the $place
argument.
The result of the function is the formatted string representation of the supplied
xs:dateTime
, xs:date
, or xs:time
value.
[Definition] The three
functions fn:format-dateTime
, fn:format-date
,
and fn:format-time
are referred to collectively as the
date formatting functions.
If $value
is the empty sequence, the function returns the empty sequence.
Calling the two-argument form of each of the three functions is equivalent to calling the five-argument form with each of the last three arguments set to an empty sequence.
For details of the $language
, $calendar
, and
$place
arguments, see 9.8.4.8 The language, calendar, and place arguments.
In general, the use of an invalid $picture
,
$language
, $calendar
, or
$place
argument results in a dynamic error [err:FOFD1340]. By contrast,
use of an option in any of these arguments that is valid but not supported by the implementation is
not an error, and in these cases the implementation is required to output the value in a fallback
representation. More detailed rules are given below.
The picture consists of a sequence of variable markers and literal substrings. A substring enclosed in square brackets is interpreted as a variable marker; substrings not enclosed in square brackets are taken as literal substrings. The literal substrings are optional and if present are rendered unchanged, including any whitespace. If an opening or closing square bracket is required within a literal substring, it must be doubled. The variable markers are replaced in the result by strings representing aspects of the date and/or time to be formatted. These are described in detail below.
A variable marker consists of a component specifier followed optionally by one or two presentation modifiers and/or optionally by a width modifier. Whitespace within a variable marker is ignored.
The variable marker may be separated into its components by applying the following rules:
The component specifier is always present and is always a single letter.
The width modifier may be recognized by the presence of a comma.
The substring between the component specifier and the comma (if present) or the end of the string (if there is no comma) contains the first and second presentation modifiers, both of which are optional. If this substring contains a single character, this is interpreted as the first presentation modifier. If it contains more than one character, the last character is examined: if it is valid as a second presentation modifier then it is treated as such, and the preceding part of the substring constitutes the first presentation modifier. Otherwise, the second presentation modifier is presumed absent and the whole substring is interpreted as the first presentation modifier.
The component specifier indicates the component of the date or time that is required, and takes the following values:
Specifier | Meaning | Default Presentation Modifier |
---|---|---|
Y | year (absolute value) | 1 |
M | month in year | 1 |
D | day in month | 1 |
d | day in year | 1 |
F | day of week | n |
W | week in year | 1 |
w | week in month | 1 |
H | hour in day (24 hours) | 1 |
h | hour in half-day (12 hours) | 1 |
P | am/pm marker | n |
m | minute in hour | 01 |
s | second in minute | 01 |
f | fractional seconds | 1 |
Z | timezone | 01:01 |
z | timezone (same as Z, but modified where appropriate to include a prefix
as a time offset using GMT, for example GMT+1 or GMT-05:00. For this component there
is a fixed
prefix of GMT , or a localized
variation thereof for the chosen language, and the remainder of the value is formatted
as for specifier Z .
|
01:01 |
C | calendar: the name or abbreviation of a calendar name | n |
E | era: the name of a baseline for the numbering of years, for example the reign of a monarch | n |
A dynamic error is reported [err:FOFD1340] if the syntax of the picture is incorrect.
A dynamic error is reported [err:FOFD1350]
if a component specifier within the picture
refers to components that are not available in the given type of $value
,
for example if the picture supplied to the fn:format-time
refers
to the year, month, or day component.
It is not an error to include a timezone component when the supplied value has no timezone. In these circumstances the timezone component will be ignored.
The first presentation modifier indicates the style in which the value of a component is to be represented. Its value may be either:
any format token permitted as a primary format token in the second argument
of the fn:format-integer
function, indicating
that the value of the component is to be output numerically using the specified number format (for example,
1
, 01
, i
, I
, w
, W
,
or Ww
) or
the format token n
, N
,
or Nn
, indicating that the value of the component is to be output by name,
in lower-case, upper-case, or title-case respectively. Components that can be output by name
include (but are not limited to) months, days of the week, timezones, and eras.
If the processor cannot output these components by name for the chosen calendar and language
then it must use an ·implementation-defined· fallback representation.
If a comma is to be used as a grouping separator within the format token, then there must be a width
specifier. More specifically: if a variable marker
contains one or more commas, then the last comma is treated as introducing the width modifier, and all others
are treated as grouping separators. So [Y9,999,*]
will output the year as 2,008
.
It is not possible to use a closing square bracket as a grouping separator within the format token.
If the implementation does not support the use of the requested format token, it must use the default presentation modifier for that component.
If the first presentation modifier is present, then it may optionally be followed by a second presentation modifier as follows:
Modifier | Meaning |
---|---|
either a or t |
indicates alphabetic or traditional numbering respectively,
the default being ·implementation-defined·.
This has the same meaning as in the second argument of fn:format-integer . |
either c or o |
indicates cardinal or ordinal numbering respectively, for example
7 or seven for a cardinal number, or 7th ,
seventh , or 7º
for an ordinal number.
This has the same meaning as
in the second argument of fn:format-integer .
The actual representation of the ordinal form of a number
may depend not only on the language, but also on the grammatical context (for example,
in some languages it must agree in gender). |
Note:
Although the formatting rules are expressed in terms of the rules
for format tokens in fn:format-integer
, the formats actually used may be specialized
to the numbering of date components where appropriate. For example, in Italian, it is conventional to
use an ordinal number (primo
) for the first day of the month, and cardinal numbers
(due, tre, quattro ...
) for the remaining days. A processor may therefore use
this convention to number days of the month, ignoring the presence or absence of the ordinal
presentation modifier.
Whether or not a presentation modifier is included, a width modifier may be supplied. This indicates the number of characters to be included in the representation of the value.
The width modifier, if present, is introduced by a comma. It takes the form:
"," min-width ("-" max-width)?
where min-width
is either an unsigned integer indicating the minimum number of characters to
be output, or *
indicating that there is no explicit minimum, and
max-width
is either an unsigned integer indicating the maximum number of characters to
be output, or *
indicating that there is no explicit maximum; if max-width
is omitted then *
is assumed.
A dynamic error ([err:FOFD1340]) is raised if
min-width
is present and less than one, or if
max-width
is present and less than one or less than min-width
.
A format token containing more than one digit, such as 001
or 9999
, sets the
minimum and maximum width to the number of digits appearing in the format token; if a width
modifier is also present, then the width modifier takes precedence.
The rules in this section apply to the majority of integer-valued components: specifically M D d F W w H h m s
.
In the rules below, the term decimal digit pattern has the meaning given in 4.6.1 fn:format-integer.
If the first presentation modifier takes the form of a decimal digit pattern:
If there is no width modifier, then the value is formatted according to
the rules of the format-integer
function.
If there is a width modifier, then the first presentation modifier is adjusted as follows:
If the decimal digit pattern includes a grouping separator, the output is implementation-defined (but this is not an error).
Note:
Use of a width modifier together with grouping separators is inadvisable for this reason. It is never necessary to use a width modifier with a decimal digit pattern, since the same effect can be achieved by use of optional digit signs.
Otherwise, the number of mandatory-digit-sign characters in the presentation modifier is increased if necessary. This is done first by replacing optional-digit-signs with mandatory-digit-signs, starting from the right, and then prepending mandatory-digit-signs to the presentation modifier, until the number of mandatory-digit-signs is equal to the minimum width. Any mandatory-digit-signs that are added by this process must use the same decimal digit family as existing mandatory-digit-signs in the presentation modifier if there are any, or ASCII digits otherwise.
The maximum width, if specified, is ignored.
The output is then as defined using the format-integer
function with this adjusted decimal digit pattern.
If the first presentation modifiers is one of N
, n
, or Nn
:
Let FN be the full name of the component, that is, the form of the name that would be used in the absence of any width modifier.
If FN is shorter than the minimum width, then it is padded by appending spaces to the end of the name.
If FN is longer than the maximum width, then it is abbreviated, either by choosing a conventional abbreviation that fits within the maximum width (for example, "Wednesday" might be abbreviated to "Weds"), or by removing characters from the end of FN until it fits within the maximum width.
For other presentation modifiers:
Any adjustment of the value to fit within the requested width range is implementation-defined.
The value should not be truncated if this results in output that will not be meaningful to users (for example, there is no sensible way to truncate Roman numerals).
If shorter than the minimum width, the value should be padded to the minimum width, either by appending spaces, or in some other way appropriate to the numbering scheme.
The rules for the year component (Y) are the same as those in 9.8.4.3 Formatting Integer-Valued Date/Time Components, except that the value of the year as output is the value of the year component of the supplied value modulo ten to the power N where N is determined as follows:
If the width modifier is present and defines a finite maximum width, then that maximum width.
Otherwise, if the first presentation modifier takes the form of a decimal-digit-pattern, then:
Let W be the number of optional-digit-signs and mandatory-digit-signs in that decimal-digit-pattern.
If W is 2 or more, then W.
Otherwise, N is infinity (that is, the year is output in full).
The output for the fractional seconds component (f
) is equivalent to the result of the following algorithm:
If the first presentation modifier contains no Unicode digit, then the output is implementation-defined.
Otherwise, the value of the fractional seconds is output as follows:
If there is no width modifier and the first presentation modifier comprises in its
entirety a single mandatory-digit-sign (for example the default 1
), then
the presentation modifier is extended on the right with as many optional-digit-signs as
are needed to accommodate the actual fractional seconds precision encountered in the
value to be formatted.
If there is a width modifier, then the first presentation modifier is adjusted as follows:
If a minimum width is specified, and if this exceeds the number of mandatory-digit-sign characters in the first presentation modifier, then the first presentation modifier is adjusted. This is done first by replacing optional-digit-signs with mandatory-digit-signs, starting from the left, and then appending mandatory-digit-signs to the presentation modifier, until the number of mandatory-digit-signs is equal to the minimum width. Any mandatory-digit-signs that are added by this process must use the same decimal digit family as existing mandatory-digit-signs in the presentation modifier.
If a maximum width is specified, the first presentation modifier is extended on the right with as many optional-digit-signs as are needed to ensure that the number of mandatory-digit-signs and optional-digit-signs is at least equal to the maximum width.
The sequence of characters in the (adjusted) first presentation modifier is reversed (for example,
999'###
becomes ###'999
).
If the result is not a valid decimal digit pattern, then the output is
·implementation-defined·.
The sequence of digits in the conventional decimal representation of the fractional seconds component
is reversed, with insignificant zeroes removed, and the result is treated as an integer. For example, if the
seconds value is 25.8235
, the reversed fractional seconds value is 5328
.
The reversed fractional seconds value is formatted using the reversed decimal digit pattern according to the
rules of the fn:format-integer
function. Given the examples above, the result is 5'328
The resulting string is reversed. In our example, the result is 823'5
.
If the result contains more digits than the number of mandatory-digit-signs and optional-digit-signs in the decimal digit pattern, then excess digits are removed from the right hand end (that is, the value is truncated towards zero rather than being rounded). Any grouping separator that immediately precedes a removed digit is also removed.
Note:
The reason for presenting the algorithm in this way is that it enables maximum re-use of the rules defined for
fn:format-integer
. Since the fractional seconds value is not properly an integer, the rules do not
work if used directly: for example, the positions of grouping separators need to be counted from the left rather
than from the right. Implementations, as always, are free to use a different algorithm that yields the same result.
Note:
A format token consisting of a single digit,
such as 1
, does not constrain the number of digits in the output.
In the case of fractional seconds in particular, [f001]
requests three decimal digits,
[f01]
requests two digits, but [f1]
will retain all digits in the
supplied date/time value (the maximum number of digits is implementation-defined).
If exactly one digit is required, this can be achieved using the component specifier
[f1,1-1]
.
Special rules apply to the formatting of timezones. When the component specifiers Z
or z
are used, the rules in this section override any rules given elsewhere in the case of
discrepancies.
If the date/time value to be formatted does not include a timezone offset, then the timezone component specifier is generally ignored (results in no output). The exception is where military timezones are used (format ZZ) in which case the string "J" is output, indicating local time.
When the component specifier is z
, the output is the same as for component specifier
Z
, except that it is prefixed by the characters GMT
or some localized
equivalent. The prefix is omitted, however, in cases where the timezone is identified by name rather than by
a numeric offset from UTC.
If the first presentation modifier is numeric and comprises one or two digits
with no grouping-separator (for example 1
or 01
), then the timezone is formatted as a displacement from UTC in hours, preceded by a plus or minus
sign: for example -5
or +03
. If the actual timezone offset is not an integral number of hours,
then the minutes part of the offset is appended, separated by a colon: for example +10:30
or
-1:15
.
If the first presentation modifier is numeric with a grouping-separator (for example 1:01
or 01.01
), then the timezone offset is output in hours and minutes, separated by the grouping separator,
even if the number of minutes is zero: for example +5:00
or +10.30
.
If the first presentation modifier is numeric and comprises three or four digits with no
grouping-separator, for example 001
or 0001
, then the timezone offset
is shown in hours and minutes with no separator, for example -0500
or +1030
.
If the first presentation modifier is numeric, in any of the above formats, and the second
presentation modifier is t
, then a zero timezone offset (that is, UTC) is output as Z
instead
of a signed numeric value. In this presentation modifier is absent or if the timezone offset is non-zero,
then the displayed timezone offset is preceded by a "-" sign for negative offsets
or a "+" sign for non-negative offsets.
If the first presentation modifier is Z
, then the timezone is formatted
as a military timezone letter, using the convention Z = +00:00, A = +01:00, B = +02:00, ..., M = +12:00,
N = -01:00, O = -02:00, ... Y = -12:00. The letter J (meaning local time) is used in the case of a
value that does not specify a timezone offset. Timezone offsets that have no representation in this system
(for example Indian Standard Time, +05:30) are output as if the format 01:01
had been requested.
If the first presentation modifier is N
, then the timezone is output
(where possible) as a timezone name, for example EST
or CET
. The same timezone
offset has different names in different places; it is therefore recommended that this option
should be used only if a country code (see [ISO 3166-1]) or IANA timezone name (see [IANA Timezone Database]) is supplied in the $place
argument.
In the absence of this information, the implementation may apply a default, for example by using the timezone
names that are conventional in North America. If no timezone name can be identified, the timezone offset is
output using the fallback format +01:01
.
The following examples illustrate options for timezone formatting.
Variable marker | $place |
Timezone offsets (with time = 12:00:00) | ||||
---|---|---|---|---|---|---|
-10:00 | -05:00 | +00:00 | +05:30 | +13:00 | ||
[Z] | () | -10:00 | -05:00 | +00:00 | +05:30 | +13:00 |
[Z0] | () | -10 | -5 | +0 | +5:30 | +13 |
[Z0:00] | () | -10:00 | -5:00 | +0:00 | +5:30 | +13:00 |
[Z00:00] | () | -10:00 | -05:00 | +00:00 | +05:30 | +13:00 |
[Z0000] | () | -1000 | -0500 | +0000 | +0530 | +1300 |
[Z00:00t] | () | -10:00 | -05:00 | Z | +05:30 | +13:00 |
[z] | () | GMT‑10:00 | GMT‑05:00 | GMT+00:00 | GMT+05:30 | GMT+13:00 |
[ZZ] | () | W | R | Z | +05:30 | +13:00 |
[ZN] | "us" | HST | EST | GMT | IST | +13:00 |
[H00]:[M00] [ZN] | "America/New_York" | 06:00 EST | 12:00 EST | 07:00 EST | 01:30 EST | 18:00 EST |
If a width specifier is present when formatting a timezone, then the representation as defined in this section is padded to the minimum width as described in 9.8.4.2 The Width Modifier, but it is never shortened.
This section applies to the remaining components: P
(am/pm marker), C
(calendar),
and E
(era).
The output for these components is entirely ·implementation-defined·.
The default presentation modifier for these components is n
, indicating that they are output as names (or
conventional abbreviations), and the chosen names will in many cases depend on the chosen language: see 9.8.4.8 The language, calendar, and place arguments.
The set of languages, calendars, and places that are supported in the ·date formatting functions· is ·implementation-defined·. When any of these arguments is omitted or is an empty sequence, an ·implementation-defined· default value is used.
If the fallback representation uses a different calendar from that requested,
the output string must identify the calendar actually used, for example by
prefixing the string with [Calendar: X]
(where X is the calendar actually used),
localized as appropriate to the
requested language. If the fallback representation uses a different language
from that requested, the output string must identify the language actually
used, for example by prefixing the string with [Language: Y]
(where Y is the language
actually used) localized in an
implementation-dependent way. If a particular component of the value cannot be output in
the requested format, it should be output in the default format for
that component.
The $language
argument specifies the language to be used for the result string
of the function. The value of the argument should be either the empty sequence
or a value that would be valid for the xml:lang
attribute (see [XML]).
Note that this permits the identification of sublanguages
based on country codes (from [ISO 3166-1]) as well as identification of dialects
and of regions within a country.
If the $language
argument is omitted or is set to an empty sequence, or if it is set to an invalid value or a
value that the implementation does not recognize,
then the processor uses the default language defined in the dynamic context.
The language is used to select the appropriate language-dependent forms of:
names (for example, of months)
numbers expressed as words or as ordinals (twenty, 20th, twentieth
)
hour convention (0-23 vs 1-24, 0-11 vs 1-12)
first day of week, first week of year
Where appropriate this choice may also take into account the value of the
$place
argument, though this should not be used to override the
language or any sublanguage that is specified as part of the language
argument.
The choice of the names and abbreviations used in any given language is
·implementation-defined·. For example,
one implementation might abbreviate July as Jul
while another uses Jly
. In German,
one implementation might represent Saturday as Samstag
while another
uses Sonnabend
. Implementations may provide mechanisms allowing users to
control such choices.
Where ordinal numbers are used, the selection of the correct representation of the ordinal (for example, the linguistic gender) may depend on the component being formatted and on its textual context in the picture string.
The calendar
attribute specifies that the dateTime
, date
,
or time
supplied in the $value
argument must be
converted to a value in the specified calendar and then converted to a string using the
conventions of that calendar.
The calendar value if present must be a valid EQName
(dynamic error: [err:FOFD1340]).
If it is a lexical QName
then it is expanded into an expanded QName
using the statically known namespaces; if it has no prefix then it represents an expanded-QName in no namespace.
If the expanded QName is in no namespace,
then it must identify a calendar with a designator specified below
(dynamic error: [err:FOFD1340]).
If the expanded QName is in a namespace then it identifies the calendar in an ·implementation-defined· way.
If the $calendar
argument is omitted or is set to an empty sequence
then the default calendar defined in the dynamic context is used.
Note:
The calendars listed below were known to be in use during the last hundred years. Many other calendars have been used in the past.
This specification does not define any of these calendars, nor the way that they
map to the value space of the xs:date
datatype in [XML Schema Part 2: Datatypes Second Edition].
There may be ambiguities when dates are recorded using different calendars.
For example, the start of a new day is not simultaneous in different calendars,
and may also vary geographically (for example, based on the time of sunrise or sunset).
Translation of dates is therefore more reliable when the time of day is also known, and
when the geographic location is known.
When translating dates between
one calendar and another, the processor may take account of the values
of the $place
and/or $language
arguments, with the
$place
argument taking precedence.
Information about some of these calendars, and algorithms for converting between them, may be found in [Calendrical Calculations].
Designator | Calendar |
---|---|
AD | Anno Domini (Christian Era) |
AH | Anno Hegirae (Muhammedan Era) |
AME | Mauludi Era (solar years since Mohammed's birth) |
AM | Anno Mundi (Jewish Calendar) |
AP | Anno Persici |
AS | Aji Saka Era (Java) |
BE | Buddhist Era |
CB | Cooch Behar Era |
CE | Common Era |
CL | Chinese Lunar Era |
CS | Chula Sakarat Era |
EE | Ethiopian Era |
FE | Fasli Era |
ISO | ISO 8601 calendar |
JE | Japanese Calendar |
KE | Khalsa Era (Sikh calendar) |
KY | Kali Yuga |
ME | Malabar Era |
MS | Monarchic Solar Era |
NS | Nepal Samwat Era |
OS | Old Style (Julian Calendar) |
RS | Rattanakosin (Bangkok) Era |
SE | Saka Era |
SH | Mohammedan Solar Era (Iran) |
SS | Saka Samvat |
TE | Tripurabda Era |
VE | Vikrama Era |
VS | Vikrama Samvat Era |
At least one of the above calendars must be supported. It is ·implementation-defined· which calendars are supported.
The ISO 8601 calendar ([ISO 8601]),
which is included in the above list and designated ISO
,
is very similar to the Gregorian calendar designated AD
, but it
differs in several ways. The ISO calendar
is intended to ensure that date and time formats can be read
easily by other software, as well as being legible for human
users. The ISO calendar
prescribes the use of particular numbering conventions as defined in
ISO 8601, rather than allowing these to be localized on a per-language basis.
In particular it
provides a numeric 'week date' format which identifies dates by
year, week of the year, and day in the week;
in the ISO calendar the days of the week are numbered from 1 (Monday) to 7 (Sunday), and
week 1 in any calendar year is the week (from Monday to Sunday) that includes the first Thursday
of that year. The numeric values of the components year, month, day, hour, minute, and second
are the same in the ISO calendar as the values used in the lexical representation of the date and
time as defined in [XML Schema Part 2: Datatypes Second Edition]. The era ("E" component)
with this calendar is either a minus sign (for negative years) or a zero-length string (for positive years).
For dates before 1 January, AD 1, year numbers in
the ISO and AD calendars are off by one from each other: ISO year
0000 is 1 BC, -0001 is 2 BC, etc.
ISO 8601 does not define a numbering for weeks within a month. When the w
component is used, the convention to be adopted is that each Monday-to-Sunday week is considered to
fall within a particular month if its Thursday occurs in that month; the weeks that fall in a particular
month under this definition are numbered starting from 1. Thus, for example,
29 January 2013 falls in week 5 because the Thursday of the week (31 January 2013) is the fifth Thursday
in January, and 1 February 2013 is also in week 5 for the same reason.
Note:
The value space of the date and time datatypes, as defined in XML Schema, is based on
absolute points in time. The lexical space of these datatypes defines a
representation of these absolute points in time using the proleptic Gregorian calendar,
that is, the modern Western calendar extrapolated into the past and the future; but the value space
is calendar-neutral. The
·date formatting functions· produce a representation
of this absolute point in time, but denoted in a possibly different calendar. So,
for example, the date whose lexical representation in XML Schema is 1502-01-11
(the day on which Pope Gregory XIII was born) might be
formatted using the Old Style (Julian) calendar as 1 January 1502
. This reflects the fact
that there was at that time a ten-day difference between the two calendars. It would be
incorrect, and would produce incorrect results, to represent this date in an element or attribute
of type xs:date
as 1502-01-01
, even though this might reflect the way
the date was recorded in contemporary documents.
When referring to years occurring in antiquity, modern historians generally
use a numbering system in which there is no year zero (the year before 1 CE
is thus 1 BCE). This is the convention that should be used when the
requested calendar is OS (Julian) or AD (Gregorian). When the requested
calendar is ISO, however, the conventions of ISO 8601 should be followed:
here the year before +0001 is numbered zero. In [XML Schema Part 2: Datatypes Second Edition] (version 1.0),
the value space for xs:date
and xs:dateTime
does not include a year zero: however, XSD 1.1 endorses the ISO 8601 convention. This means that the date on
which Julius Caesar was assassinated has the ISO 8601 lexical representation
-0043-03-13, but will be formatted as 15 March 44 BCE in the Julian calendar
or 13 March 44 BCE in the Gregorian calendar (dependent on the chosen
localization of the names of months and eras).
The intended use of the $place
argument is to identify
the place where an event
represented by the dateTime
, date
,
or time
supplied in the $value
argument took place or will take place.
If the $place
argument is omitted or is set
to an empty sequence, then the default place defined in the dynamic context is used.
If the value is supplied, and is not the empty sequence, then it should
either be a country code or an IANA timezone name.
If the value does not take this form, or if its value is not recognized
by the implementation, then the default place defined in the dynamic context is used.
Country codes are defined in [ISO 3166-1]. Examples are "de" for Germany and "jp" for Japan. Implementations may also allow the use of codes representing subdivisions of a country from ISO 3166-2, or codes representing formerly used names of countries from ISO 3166-3
IANA timezone names are defined in the IANA timezone database [IANA Timezone Database]. Examples are "America/New_York" and "Europe/Rome".
This argument is not intended to identify the location of the user
for whom the date or time is being formatted;
that should be done by means of the $language
attribute.
This information
may be used to provide additional information when converting dates between
calendars or when deciding how individual components of the date and time are to be formatted.
For example, different countries using the Old Style (Julian) calendar started the new year on different
days, and some countries used variants of the calendar that were out of synchronization as a result of
differences in calculating leap years.
The geographical area identified by a country code is defined by the boundaries as they existed at the time of the date to be formatted, or the present-day boundaries for dates in the future.
If the $place
argument is supplied in the form
of an IANA timezone name that is recognized by the implementation, then the date or
time being formatted is adjusted to the timezone offset applicable in that timezone.
For example, if the xs:dateTime
value 2010-02-15T12:00:00Z
is formatted with the $place
argument set to
America/New_York
, then the output will be as if the value
2010-02-15T07:00:00-05:00
had been supplied. This adjustment takes daylight
savings time into account where possible; if the date in question falls during
daylight savings time in New York, then it is adjusted to timezone offset -PT4H
rather than -PT5H
. Adjustment using daylight savings time is only possible
where the value includes a date, and where the date is within the range covered
by the timezone database.
The following examples show a selection of dates and times and the way they might be formatted. These examples assume the use of the Gregorian calendar as the default calendar.
Required Output | Expression |
---|---|
2002-12-31
|
format-date($d, "[Y0001]-[M01]-[D01]")
|
12-31-2002
|
format-date($d, "[M]-[D]-[Y]")
|
31-12-2002
|
format-date($d, "[D]-[M]-[Y]")
|
31 XII 2002
|
format-date($d, "[D1] [MI] [Y]")
|
31st December, 2002
|
format-date($d, "[D1o] [MNn], [Y]", "en", (), ())
|
31 DEC 2002
|
format-date($d, "[D01] [MN,*-3] [Y0001]", "en", (), ())
|
December 31, 2002
|
format-date($d, "[MNn] [D], [Y]", "en", (), ())
|
31 Dezember, 2002
|
format-date($d, "[D] [MNn], [Y]", "de", (), ())
|
Tisdag 31 December 2002
|
format-date($d, "[FNn] [D] [MNn] [Y]", "sv", (), ())
|
[2002-12-31]
|
format-date($d, "[[[Y0001]-[M01]-[D01]]]")
|
Two Thousand and Three
|
format-date($d, "[YWw]", "en", (), ())
|
einunddreißigste Dezember
|
format-date($d, "[Dwo] [MNn]", "de", (), ())
|
3:58 PM
|
format-time($t, "[h]:[m01] [PN]", "en", (), ())
|
3:58:45 pm
|
format-time($t, "[h]:[m01]:[s01] [Pn]", "en", (), ())
|
3:58:45 PM PDT
|
format-time($t, "[h]:[m01]:[s01] [PN] [ZN,*-3]", "en", (), ())
|
3:58:45 o'clock PM PDT
|
format-time($t, "[h]:[m01]:[s01] o'clock [PN] [ZN,*-3]", "en", (), ())
|
15:58
|
format-time($t,"[H01]:[m01]")
|
15:58:45.762
|
format-time($t,"[H01]:[m01]:[s01].[f001]")
|
15:58:45 GMT+02:00
|
format-time($t,"[H01]:[m01]:[s01] [z,6-6]", "en", (), ())
|
15.58 Uhr GMT+2
|
format-time($t,"[H01]:[m01] Uhr [z]", "de", (), ())
|
3.58pm on Tuesday, 31st December
|
format-dateTime($dt, "[h].[m01][Pn] on [FNn], [D1o] [MNn]")
|
12/31/2002 at 15:58:45
|
format-dateTime($dt, "[M01]/[D01]/[Y0001] at [H01]:[m01]:[s01]")
|
The following examples use calendars other than the Gregorian calendar.
Description | Request | Result |
---|---|---|
Islamic |
format-date($d, "[D١] [Mn] [Y١]", "ar", "AH", ())
|
٢٦ ﺸﻭّﺍﻝ ١٤٢٣ |
Jewish (with Western numbering) |
format-date($d, "[D] [Mn] [Y]", "he", "AM", ())
|
26 טבת 5763 |
Jewish (with traditional numbering) |
format-date($d, "[Dאt] [Mn] [Yאt]", "he", "AM", ())
|
כ״ו טבת תשס״ג |
Julian (Old Style) |
format-date($d, "[D] [MNn] [Y]", "en", "OS", ())
|
18 December 2002 |
Thai |
format-date($d, "[D๑] [Mn] [Y๑]", "th", "BE", ())
|
๓๑ ธันวาคม ๒๕๔๕ |
Function | Meaning |
---|---|
fn:parse-ietf-date |
Parses a string containing the date and time in IETF format, returning the corresponding
xs:dateTime value. |
A function is provided to parse dates and times expressed using syntax that is commonly encountered in internet protocols.
Parses a string containing the date and time in IETF format, returning the corresponding
xs:dateTime
value.
fn:parse-ietf-date ( |
||
$value |
as xs:string? |
|
) as xs:dateTime? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function accepts a string matching the production input
in the
following grammar:
input
|
::=
|
S? (dayname ","? S)? ((datespec S time) | asctime) S?
|
dayname
|
::=
|
"Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun" | "Monday | "Tuesday"
| "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"
|
datespec
|
::=
|
daynum dsep monthname dsep year
|
asctime
|
::=
|
monthname dsep daynum S time S year
|
dsep
|
::=
|
S | (S? "-" S?)
|
daynum
|
::=
|
digit digit?
|
year
|
::=
|
digit digit (digit digit)?
|
digit
|
::=
|
[0-9]
|
monthname
|
::=
|
"Jan" | "Feb" | "Mar" | "Apr" | "May" | "Jun" | "Jul" | "Aug" | "Sep" |
"Oct" | "Nov" | "Dec"
|
time
|
::=
|
hours ":" minutes (":" seconds)? (S? timezone)?
|
hours
|
::=
|
digit digit?
|
minutes
|
::=
|
digit digit
|
seconds
|
::=
|
digit digit ("." digit+)?
|
timezone
|
::=
|
tzname | tzoffset (S? "(" S? tzname S? ")")?
|
tzname
|
::=
|
"UT" | "UTC" | "GMT" | "EST" | "EDT" | "CST" | "CDT" | "MST" | "MDT" | "PST"
| "PDT"
|
tzoffset
|
::=
|
("+"|"-") hours ":"? minutes?
|
S
|
::=
|
( x09 | x0A | x0D | x20 )+
|
The input is case-insensitive: upper-case and lower-case distinctions in the above grammar show the conventional usage, but otherwise have no significance.
If the input is an empty sequence, the result is an empty sequence.
The dayname
, if present, is ignored.
The daynum
, monthname
, and year
supply the day,
month, and year of the resulting xs:dateTime
value. A two-digit year
must have 1900 added to it. A year such as 0070 is to be treated
as given; negative years are not permitted.
The hours
, minutes
, and seconds
(including
fractional seconds) values supply the corresponding components of the resulting
xs:dateTime
value; if the seconds
value
or the fractional seconds value is absent then zero
is assumed.
If both a tzoffset
and a tzname
are supplied then the
tzname
is ignored.
If a tzoffset
is supplied then this defines the hours and minutes parts of the timezone offset:
If it contains a colon, this separates the hours part from the minutes part.
Otherwise, the grammar allows a sequence of from one to four digits. These are interpreted
as H
, HH
, HMM
, or HHMM
respectively, where H
or HH
is the hours part, and MM
(if present) is the minutes part.
If the minutes part is absent it defaults to 00
.
If a tzname
is supplied with no tzoffset
then it is translated
to a timezone offset as follows:
tzname | Offset |
---|---|
UT, UTC, GMT | 00:00 |
EST | -05:00 |
EDT | -04:00 |
CST | -06:00 |
CDT | -05:00 |
MST | -07:00 |
MDT | -06:00 |
PST | -08:00 |
PDT | -07:00 |
If neither a tzoffset
nor tzname
is supplied, a timezone
offset of 00:00
is assumed.
A dynamic error is raised [err:FORG0010] if the input does not match the grammar, or if the resulting date/time value is invalid (for example, 31 February).
The parse-ietf-date
function attempts to interpret its input as a date
in any of the three formats specified by HTTP [RFC 2616].
These formats are used widely on the Internet to represent timestamps, and were specified in:
[RFC 822] (electronic mail), extended in [RFC 1123] to allow four-digit years;
[RFC 850] (Usenet Messages), obsoleted by [RFC 1036];
POSIX asctime()
format
[RFC 2616] (HTTP) officially uses a subset of those three formats restricted to GMT.
The grammar for this function is slightly more liberal than the RFCs (reflecting the internet tradition of being liberal in what is accepted). For example the function:
Accepts a single-digit value where appropriate in place of a two-digit value with a leading zero (so "Wed 1 Jun" is acceptable in place of "Wed 01 Jun", and the timezone offset "-5:00" is equivalent to "-05:00")
Accepts one or more whitespace characters (x20, x09, x0A, x0D) wherever a single space is required, and allows whitespace to be omitted where it is not required for parsing
Accepts and ignores whitespace characters (x20, x09, x0A, x0D) at the start or end of the string.
In new protocols IETF recommends the format of [RFC 3339] which is based on a profile of ISO 8601 similar to that already used in XPath and XSD, but the "approximate" [RFC 822] format described here is very widely used.
An [RFC 1123] date can be generated approximately using fn:format-dateTime
with a picture
string of "[FNn3], [D01] [MNn3] [Y04] [H01]:[m01]:[s01] [Z0000]"
.
The expression fn:parse-ietf-date("Wed, 06 Jun 1994 07:29:35 GMT")
returns xs:dateTime("1994-06-06T07:29:35Z")
.
The expression fn:parse-ietf-date("Wed, 6 Jun 94 07:29:35 GMT")
returns xs:dateTime("1994-06-06T07:29:35Z")
.
The expression fn:parse-ietf-date("Wed Jun 06 11:54:45 EST 2013")
returns xs:dateTime("2013-06-06T11:54:45-05:00")
.
The expression fn:parse-ietf-date("Sunday, 06-Nov-94 08:49:37 GMT")
returns xs:dateTime("1994-11-06T08:49:37Z")
.
The expression fn:parse-ietf-date("Wed, 6 Jun 94 07:29:35 +0500")
returns xs:dateTime("1994-06-06T07:29:35+05:00")
.