XPath and XQuery Functions and Operators 4.0

8 Processing durations

Operators are defined on the following type:

xs:duration

and on the two defined subtypes (see 8.1.1 Subtypes of duration):

xs:yearMonthDuration
xs:dayTimeDuration

Arithmetic on durations is defined only on these subtypes: this is because the results of some operations (for example one month minus one day) have no representation in the value space.

Two xs:duration values may however be compared.

8.4 Constructing durations

This section decribes the fn:seconds function, which constructs an xs:dayTimeDuration value representing a decimal number of seconds.

Function	Meaning
`fn:seconds`	Returns an `xs:dayTimeDuration` whose length is a given number of seconds.

8.4.1 fn:seconds

Changes in 4.0 (next | previous)

New in 4.0 [Issue 959 PR 984 6 February 2024]

Summary

Returns an xs:dayTimeDuration whose length is a given number of seconds.

Signature

`fn:seconds`(
`$value`	`as` `xs:decimal?`
) `as` `xs:dayTimeDuration?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns an xs:dayTimeDuration value whose length in seconds is equal to $value.

If $value is negative then the result will be a negative duration.

For handling of overflow and underflow, see 9.7.1 Limits and precision9.8.1 Limits and precision9.7.19.8.1 Limits and precision.

Notes

The result of seconds($n) is approximately equal to the result of the expression xs:dayTimeDuration('PT1S') * $n. The equivalence is only approximate, because seconds($n) uses the exact xs:decimal value supplied, whereas multiplying a duration by a number first converts the number to an xs:double value, which may lose precision.

Examples

Expression:	seconds(1)
Result:	xs:dayTimeDuration('PT1S')
Expression:	seconds(0.001)
Result:	xs:dayTimeDuration('PT0.001S')
Expression:	seconds(60)
Result:	xs:dayTimeDuration('PT1M')
Expression:	seconds(86400)
Result:	xs:dayTimeDuration('P1D')
Expression:	seconds(-5400)
Result:	xs:dayTimeDuration('-PT1H30M')
Expression:	xs:dateTime('1970-01-01T00:00:00Z') + 1706702400 * seconds(1)
Result:	xs:dateTime('2024-01-31T12:00:00Z') (The expression converts a Unix timestamp to an `xs:dateTime` value).
Expression:	( xs:dateTime('2024-01-31T12:00:00Z') - xs:dateTime('1970-01-01T00:00:00Z') ) div seconds(1)
Result:	1706702400 (The expression converts an `xs:dateTime` value to a Unix timestamp).

8.5 Arithmetic operators on durations

Function	Meaning
`op:add-yearMonthDurations`	Returns the result of adding two `xs:yearMonthDuration` values.
`op:subtract-yearMonthDurations`	Returns the result of subtracting one `xs:yearMonthDuration` value from another.
`op:multiply-yearMonthDuration`	Returns the result of multiplying `$arg1` by `$arg2`. The result is rounded to the nearest month.
`op:divide-yearMonthDuration`	Returns the result of dividing `$arg1` by `$arg2`. The result is rounded to the nearest month.
`op:divide-yearMonthDuration-by-yearMonthDuration`	Returns the ratio of two `xs:yearMonthDuration` values.
`op:add-dayTimeDurations`	Returns the sum of two `xs:dayTimeDuration` values.
`op:subtract-dayTimeDurations`	Returns the result of subtracting one `xs:dayTimeDuration` from another.
`op:multiply-dayTimeDuration`	Returns the result of multiplying a `xs:dayTimeDuration` by a number.
`op:divide-dayTimeDuration`	Returns the result of multiplying a `xs:dayTimeDuration` by a number.
`op:divide-dayTimeDuration-by-dayTimeDuration`	Returns the ratio of two `xs:dayTimeDuration` values, as a decimal number.

For operators that combine a duration and a date/time value, see 9.79.8 Arithmetic operators on durations, dates and times.

8.5.3 op:multiply-yearMonthDuration

Summary

Returns the result of multiplying $arg1 by $arg2. The result is rounded to the nearest month.

Operator Mapping

Defines the semantics of the * operator when applied to an xs:yearMonthDuration and a numeric value.

Signature

`op:multiply-yearMonthDuration`(
`$arg1`	`as` `xs:yearMonthDuration`,
`$arg2`	`as` `xs:double`
) `as` `xs:yearMonthDuration`

Rules

The result is the xs:yearMonthDuration whose length in months is equal to the result of applying the fn:round function to the value obtained by multiplying the length in months of $arg1 by the value of $arg2.

If $arg2 is positive or negative zero, the result is a zero-length duration. If $arg2 is positive or negative infinity, the result overflows and is handled as described in 9.7.1 Limits and precision9.8.1 Limits and precision9.7.19.8.1 Limits and precision.

For handling of overflow, underflow, and rounding, see 8.1.2 Limits and precision.

Error Conditions

A dynamic error is raised [err:FOCA0005] if $arg2 is NaN.

Notes

Either duration (and therefore the result) may be negative.

Examples

Expression:	op:multiply-yearMonthDuration( xs:yearMonthDuration("P2Y11M"), 2.3 )
Result:	xs:yearMonthDuration("P6Y9M")

8.5.4 op:divide-yearMonthDuration

Summary

Returns the result of dividing $arg1 by $arg2. The result is rounded to the nearest month.

Operator Mapping

Defines the semantics of the div operator when applied to an xs:yearMonthDuration and a numeric value.

Signature

`op:divide-yearMonthDuration`(
`$arg1`	`as` `xs:yearMonthDuration`,
`$arg2`	`as` `xs:double`
) `as` `xs:yearMonthDuration`

Rules

The result is the xs:yearMonthDuration whose length in months is equal to the result of applying the fn:round function to the value obtained by dividing the length in months of $arg1 by the value of $arg2.

If $arg2 is positive or negative infinity, the result is a zero-length duration. If $arg2 is positive or negative zero, the result overflows and is handled as described in 9.7.1 Limits and precision9.8.1 Limits and precision9.7.19.8.1 Limits and precision.

For handling of overflow, underflow, and rounding, see 8.1.2 Limits and precision.

Error Conditions

A dynamic error is raised [err:FOCA0005] if $arg2 is NaN.

Notes

Either operand (and therefore the result) may be negative.

Examples

Expression:	op:divide-yearMonthDuration( xs:yearMonthDuration("P2Y11M"), 1.5 )
Result:	xs:yearMonthDuration("P1Y11M")

9 Processing dates and times

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.

9.1 Date and time types

[Definition] The eight primitive types xs:dateTime, xs:date, xs:time, xs:gYearMonth, xs:gYear, xs:gMonthDay, xs:gMonth, xs:gDay are referred to collectively as the Gregorian types.

This section describes operations on atomic items of these types.

Values of these types are modeled as comprising one or more of the seven components year, month, day, hour, minute, second, and timezone.

The only operations defined on xs:gYearMonth, xs:gYear, xs:gMonthDay, xs:gMonth and xs:gDay values are equality comparison and component extraction. For other types, further operations are provided, including order comparisons, arithmetic, formatted display, and timezone adjustment.

9.1.1 Limits and precision

All conforming processors must support year values in the range 1 to 9999, and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, 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 0 and years with negative values. The results of operations on dates that cross the year 0 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.79.8 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.

Similarly, a processor that limits the precision of the seconds component of date and time or duration values may need to deliver a rounded result for arithmetic operations. Such a processor must deliver a result that is as close as possible to the mathematically precise result, given these limits: if two values are equally close, the one that is chosen is implementation-defined.

9.3 Record fn:dateTime-record

This record type is used to represent the components of a value of type xs:dateTime, xs:date, xs:time, xs:gYear, xs:gYearMonth, xs:gMonth, xs:gMonthDay, or xs:gDay.

Name	Meaning
`year?`	The value of the `year` component. Range is implementation-defined. Type: `xs:integer`
`month?`	The value of the `month` component. Range 1 to 12 inclusive. Type: `xs:integer`
`day?`	The value of the `day` component. Range 1 to 31 inclusive. Type: `xs:integer`
`hours?`	The value of the `hours` component. Range 0 to 23 inclusive. Type: `xs:integer`
`minutes?`	The value of the `minutes` component. Range 0 to 59 inclusive. Type: `xs:integer`
`seconds?`	The value of the `seconds` component. Range 0 (inclusive) to 60 (exclusive). Type: `xs:decimal`
`timezone?`	The timezone offset, if the value has a timezone. Type: `xs:dayTimeDuration`

9.39.4 Constructing a dateTime

Function	Meaning
`fn:dateTime`	Returns an `xs:dateTime` value created by combining an `xs:date` and an `xs:time`.
`fn:build-dateTime`	Constructs a Gregorian value from the values of its components.
`fn:build-dateTime`	Constructs a Gregorian value from the values of its components.
`fn:unix-dateTime`	Returns a dateTime value for a Unix time.

9.3.19.4.1 fn:dateTime

Summary

Returns an xs:dateTime value created by combining an xs:date and an xs:time.

Signature

`fn:dateTime`(
`$date`	`as` `xs:date?`,
`$time`	`as` `xs:time?`
) `as` `xs:dateTime?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Error Conditions

A dynamic error is raised [err:FORG0008] if the two arguments both have timezones and the timezones are different.

Examples

Expression	Result
dateTime( xs:date("1999-12-31"), xs:time("12:00:00") )	xs:dateTime("1999-12-31T12:00:00")
dateTime( xs:date("1999-12-31"), xs:time("24:00:00") )	xs:dateTime("1999-12-31T00:00:00") (This is because `"24:00:00"` is an alternate lexical form for `"00:00:00"`).

9.4.2 fn:build-dateTime

Changes in 4.0 (next | previous)

New in 4.0

Summary

Constructs a Gregorian value from the values of its components.

Signature

`fn:build-dateTime`(
`$value`	`as` `dateTime-record?`
) `as` `(xs:dateTime \| xs:date \| xs:time \| xs:gYear \| xs:gYearMonth \| xs:gMonth \| xs:gMonthDay \| xs:gDay)?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns a Gregorian value based on the supplied component values. The result will be the Gregorian value $R such that deep-equal( $significant(parts-of-dateTime($R)), $significant($value) ), where $significant is the function map:filter(?, fn($K, $V){$K eq "timezone" or exists($V)}), that is, a function that discards entries in a map whose value is the empty sequence, other than the entry with key "timezone".

If all seven components are present (year, month, day, hours, minutes, seconds, and timezone) then the result will be of type xs:dateTimeStamp.

Error Conditions

A dynamic error is raised [err:FODT0005] if the set of fields that are present and non-empty in $value is not one of the sets:

year, month, day, hours, minutes, seconds, and optional timezone (delivering an xs:dateTime)
year, month, day, and optional timezone (delivering an xs:date)
year, and optional timezone (delivering an xs:gYear)
year, month, and optional timezone (delivering an xs:gYearMonth)
month, and optional timezone (delivering an xs:gMonth)
month, day, and optional timezone (delivering an xs:gMonthDay)
day, and optional timezone (delivering an xs:gDay)
hours, minutes, seconds, and optional timezone (delivering an xs:time)

A dynamic error is raised [err:FODT0006] if any of the components in $value is outside the permitted range (for example if the value of the minutes component is less than zero or greater than 59), or if the combination of fields is not a valid date/time (for example, if month is 4 and day is 31).

Notes

Components that are present in $value but with an empty value are treated as if they were absent.

Midnight must be expressed with the hours value set to zero, not 24.

Examples

Expression:	build-dateTime({ "year": 1999, "month": 5, "day": 31, "hours": 13, "minutes": 20, "seconds": 0, "timezone": xs:dayTimeDuration("-PT5H")})
Result:	xs:dateTime("1999-05-31T13:20:00-05:00")
Expression:	build-dateTime({"hours": 13, "minutes": 30, "seconds": 4.2678})
Result:	xs:time("13:30:04.2678")
Expression:	build-dateTime({ "year": 2007, "month": 5, "timezone": xs:dayTimeDuration("PT0S")})
Result:	xs:gYearMonth("2007-05Z")

9.3.29.4.3 fn:unix-dateTime

Changes in 4.0 (next | previous)

New in 4.0 [Issue 959 PR 1358 1 August 2024]

Summary

Returns a dateTime value for a Unix time.

Signature

`fn:unix-dateTime`(
`$value`	`as` `xs:nonNegativeInteger?`	`:=` `0`
) `as` `xs:dateTimeStamp`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

The function returns a dateTime value in UTC timezone for the Unix time specified by $value in milliseconds. If the value is absent or an empty sequence, 0 is used. The Unix time is defined in [IEEE 1003.1-2024].

If the implementation supports data types from XSD 1.1 then the returned value will be an instance of xs:dateTimeStamp. Otherwise, the only guarantees are that it will be an instance of xs:dateTime and will have a timezone component.

Formal Equivalent

The effect of the function is equivalent to the result of the following XPath expression.

xs:dateTime('1970-01-01T00:00:00Z') + ($value otherwise 0) * seconds(0.001)

Notes

By calling this convenience function, it can be ensured that the correct timezone is used for computing the Unix time.

Note that Unix time does not account for leap seconds. It assumes that every day has 86,400 seconds.

Examples

Expression:	unix-dateTime()
Result:	xs:dateTime('1970-01-01T00:00:00Z')
Expression:	unix-dateTime(1)
Result:	xs:dateTime('1970-01-01T00:00:00.001Z')
Expression:	unix-dateTime(86400000)
Result:	xs:dateTime('1970-01-02T00:00:00Z')
Calculate the Unix time associated with a `xs:dateTime` value:
let $value := current-dateTime() return ($value - unix-dateTime()) div seconds(0.001)

9.49.5 Comparing date and time values

Date and time values can be compared using the function fn:compare.

[XML Schema Part 2: Datatypes Second Edition] 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 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 absent^DM31. 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 [XSD 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.

9.59.6 Extracting components of dates and times

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 a Gregorian value.
`fn:month-from-dateTime`	Returns the month component of a Gregorian value.
`fn:day-from-dateTime`	Returns the day component of a Gregorian value.
`fn:hours-from-dateTime`	Returns the hours component of a Gregorian value.
`fn:minutes-from-dateTime`	Returns the minute component of a Gregorian value.
`fn:seconds-from-dateTime`	Returns the seconds component of a Gregorian value.
`fn:timezone-from-dateTime`	Returns the timezone component of a Gregorian value.
`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`.
`fn:parts-of-dateTime`	Returns all the components of a Gregorian value.
`fn:parts-of-dateTime`	Returns all the components of a Gregorian value.

9.5.19.6.1 fn:year-from-dateTime

Changes in 4.0 (next | previous)

The function has been extended to handle other Gregorian types such as xs:gYearMonth. [Issue 1448 PR 1481 8 October 2024]

Summary

Returns the year component of a Gregorian value.

Signature

`fn:year-from-dateTime`(
`$value`	`as` `(xs:dateTime \| xs:date \| xs:time \| xs:gYear \| xs:gYearMonth \| xs:gMonth \| xs:gMonthDay \| xs:gDay)?`
) `as` `xs:integer?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $value is the empty sequence, or if the year component is absent, the function returns the empty sequence.

Otherwise, the function returns an xs:integer representing the year component in $value. The result may be negative.

Notes

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.

Examples

Expression:	year-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") )
Result:	1999
Expression:	year-from-dateTime( xs:dateTime("1999-05-31T21:30:00-05:00") )
Result:	1999
Expression:	year-from-dateTime( xs:dateTime("1999-12-31T19:20:00") )
Result:	1999
Expression:	year-from-dateTime( xs:dateTime("1999-12-31T24:00:00") )
Result:	2000
Expression:	year-from-dateTime( xs:dateTime("-0002-06-06T00:00:00") )
Result:	-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.)
Expression:	year-from-dateTime( xs:gYearMonth("2007-05Z") )
Result:	2007
Expression:	year-from-dateTime( xs:time("12:30:00") )
Result:	()

9.5.29.6.2 fn:month-from-dateTime

Changes in 4.0 (next | previous)

The function has been extended to handle other Gregorian types such as xs:gYearMonth. [Issue 1448 PR 1481 8 October 2024]

Summary

Returns the month component of a Gregorian value.

Signature

`fn:month-from-dateTime`(
`$value`	`as` `(xs:dateTime \| xs:date \| xs:time \| xs:gYear \| xs:gYearMonth \| xs:gMonth \| xs:gMonthDay \| xs:gDay)?`
) `as` `xs:integer?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $value is the empty sequence, or if it contains no month component, the function returns the empty sequence.

Otherwise, the function returns an xs:integer between 1 and 12, both inclusive, representing the month component in $value.

Examples

Expression:	month-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") )
Result:	5
Expression:	month-from-dateTime( xs:dateTime("1999-12-31T19:20:00-05:00") )
Result:	12
Expression:	month-from-dateTime( adjust-dateTime-to-timezone( xs:dateTime("1999-12-31T19:20:00-05:00"), xs:dayTimeDuration("PT0S") ) )
Result:	1
Expression:	month-from-dateTime( xs:gYearMonth("2007-05Z") )
Result:	5
Expression:	month-from-dateTime( xs:time("12:30:00") )
Result:	()

9.5.39.6.3 fn:day-from-dateTime

Changes in 4.0 (next | previous)

The function has been extended to handle other Gregorian types such as xs:gMonthDay. [Issue 1448 PR 1481 8 October 2024]

Summary

Returns the day component of a Gregorian value.

Signature

`fn:day-from-dateTime`(
`$value`	`as` `(xs:dateTime \| xs:date \| xs:time \| xs:gYear \| xs:gYearMonth \| xs:gMonth \| xs:gMonthDay \| xs:gDay)?`
) `as` `xs:integer?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $value is the empty sequence, or if it contains no day component, 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.

Examples

Expression:	day-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") )
Result:	31
Expression:	day-from-dateTime( xs:dateTime("1999-12-31T20:00:00-05:00") )
Result:	31
Expression:	day-from-dateTime( adjust-dateTime-to-timezone( xs:dateTime("1999-12-31T19:20:00-05:00"), xs:dayTimeDuration("PT0S") ) )
Result:	1
Expression:	day-from-dateTime( xs:gMonthDay("--05-31Z") )
Result:	31
Expression:	day-from-dateTime( xs:time("12:30:00") )
Result:	()

9.5.49.6.4 fn:hours-from-dateTime

Changes in 4.0 (next | previous)

The function has been extended to handle other types including xs:time. [Issue 1448 PR 1481 8 October 2024]

Summary

Returns the hours component of a Gregorian value.

Signature

`fn:hours-from-dateTime`(
`$value`	`as` `(xs:dateTime \| xs:date \| xs:time \| xs:gYear \| xs:gYearMonth \| xs:gMonth \| xs:gMonthDay \| xs:gDay)?`
) `as` `xs:integer?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $value is the empty sequence, or if it contains no hours component, the function returns the empty sequence.

Otherwise, the function returns an xs:integer between 0 and 23, both inclusive, representing the hours component in $value.

Examples

Expression:	hours-from-dateTime( xs:dateTime("1999-05-31T08:20:00-05:00") )
Result:	8
Expression:	hours-from-dateTime( xs:dateTime("1999-12-31T21:20:00-05:00") )
Result:	21
Expression:	hours-from-dateTime( adjust-dateTime-to-timezone( xs:dateTime("1999-12-31T21:20:00-05:00"), xs:dayTimeDuration("PT0S") ) )
Result:	2
Expression:	hours-from-dateTime( xs:dateTime("1999-12-31T12:00:00") )
Result:	12
Expression:	hours-from-dateTime( xs:dateTime("1999-12-31T24:00:00") )
Result:	0
Expression:	hours-from-dateTime( xs:gYearMonth("2007-05Z") )
Result:	()
Expression:	hours-from-dateTime( xs:time("12:30:00") )
Result:	12

9.5.59.6.5 fn:minutes-from-dateTime

Changes in 4.0 (next | previous)

The function has been extended to handle other types including xs:time. [Issue 1448 PR 1481 8 October 2024]

Summary

Returns the minute component of a Gregorian value.

Signature

`fn:minutes-from-dateTime`(
`$value`	`as` `(xs:dateTime \| xs:date \| xs:time \| xs:gYear \| xs:gYearMonth \| xs:gMonth \| xs:gMonthDay \| xs:gDay)?`
) `as` `xs:integer?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $value is the empty sequence, or if it contains no minutes component, 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.

Examples

Expression:	minutes-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") )
Result:	20
Expression:	minutes-from-dateTime( xs:dateTime("1999-05-31T13:30:00+05:30") )
Result:	30
Expression:	minutes-from-dateTime( xs:gYearMonth("2007-05Z") )
Result:	()
Expression:	minutes-from-dateTime( xs:time("12:30:00") )
Result:	30

9.5.69.6.6 fn:seconds-from-dateTime

Summary

Returns the seconds component of a Gregorian value.

Signature

`fn:seconds-from-dateTime`(
`$value`	`as` `(xs:dateTime \| xs:date \| xs:time \| xs:gYear \| xs:gYearMonth \| xs:gMonth \| xs:gMonthDay \| xs:gDay)?`
) `as` `xs:decimal?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $value is the empty sequence, or if it contains no seconds component, 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 $value.

Examples

Expression:	seconds-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") )
Result:	0
Expression:	seconds-from-dateTime( xs:gYearMonth("2007-05Z") )
Result:	()
Expression:	seconds-from-dateTime( xs:time("12:30:14.5") )
Result:	14.5

9.5.79.6.7 fn:timezone-from-dateTime

Changes in 4.0 (next | previous)

The function has been extended to handle other types such as xs:gYearMonth. [Issue 1448 PR 1481 8 October 2024]

Summary

Returns the timezone component of a Gregorian value.

Signature

`fn:timezone-from-dateTime`(
`$value`	`as` `(xs:dateTime \| xs:date \| xs:time \| xs:gYear \| xs:gYearMonth \| xs:gMonth \| xs:gMonthDay \| xs:gDay)?`
) `as` `xs:dayTimeDuration?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Examples

Expression:	timezone-from-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") )
Result:	xs:dayTimeDuration("-PT5H")
Expression:	timezone-from-dateTime( xs:dateTime("2000-06-12T13:20:00Z") )
Result:	xs:dayTimeDuration("PT0S")
Expression:	timezone-from-dateTime( xs:dateTime("2004-08-27T00:00:00") )
Result:	()
Expression:	timezone-from-dateTime( xs:gYearMonth("2007-05Z") )
Result:	xs:dayTimeDuration("PT0S")
Expression:	timezone-from-dateTime( xs:time("12:30:00") )
Result:	()

9.5.89.6.8 fn:year-from-date

Summary

Returns the year component of an xs:date.

Signature

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

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Notes

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.

Examples

Expression	Result
year-from-date( xs:date("1999-05-31") )	1999
year-from-date( xs:date("2000-01-01+05:00") )	2000
year-from-date( xs:date("-0002-06-01") )	-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.)

9.5.99.6.9 fn:month-from-date

Summary

Returns the month component of an xs:date.

Signature

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

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Examples

Expression	Result
month-from-date( xs:date("1999-05-31-05:00") )	5
month-from-date( xs:date("2000-01-01+05:00") )	1

9.5.109.6.10 fn:day-from-date

Summary

Returns the day component of an xs:date.

Signature

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

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Examples

Expression	Result
day-from-date( xs:date("1999-05-31-05:00") )	31
day-from-date( xs:date("2000-01-01+05:00") )	1

9.5.119.6.11 fn:timezone-from-date

Summary

Returns the timezone component of an xs:date.

Signature

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

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Examples

Expression	Result
timezone-from-date( xs:date("1999-05-31-05:00") )	xs:dayTimeDuration("-PT5H")
timezone-from-date( xs:date("2000-06-12Z") )	xs:dayTimeDuration("PT0S")

9.5.129.6.12 fn:hours-from-time

Summary

Returns the hours component of an xs:time.

Signature

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

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Examples

Expression	Result
Assume that the dynamic context provides an implicit timezone value of `-05:00`.
`hours-from-time(xs:time("11:23:00"))`	`11`
`hours-from-time(xs:time("21:23:00"))`	`21`
`hours-from-time(xs:time("01:23:00+05:00"))`	`1`
hours-from-time( adjust-time-to-timezone( xs:time("01:23:00+05:00"), xs:dayTimeDuration("PT0S") ) )	20
`hours-from-time(xs:time("24:00:00"))`	`0`

9.5.139.6.13 fn:minutes-from-time

Summary

Returns the minutes component of an xs:time.

Signature

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

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Examples

Expression	Result
`minutes-from-time(xs:time("13:00:00Z"))`	`0`

9.5.149.6.14 fn:seconds-from-time

Summary

Returns the seconds component of an xs:time.

Signature

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

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Examples

Expression	Result
`seconds-from-time(xs:time("13:20:10.5"))`	`10.5`

9.5.159.6.15 fn:timezone-from-time

Summary

Returns the timezone component of an xs:time.

Signature

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

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Examples

Expression	Result
`timezone-from-time(xs:time("13:20:00-05:00"))`	`xs:dayTimeDuration("-PT5H")`
`timezone-from-time(xs:time("13:20:00"))`	`()`

9.6.16 fn:parts-of-dateTime

Changes in 4.0 (next | previous)

New in 4.0

Summary

Returns all the components of a Gregorian value.

Signature

`fn:parts-of-dateTime`(
`$value`	`as` `(xs:dateTime \| xs:date \| xs:time \| xs:gYear \| xs:gYearMonth \| xs:gMonth \| xs:gMonthDay \| xs:gDay)?`
) `as` `dateTime-record?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

If $value is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns a record whose fields are as follows. All entries will be present, even when the value is an empty sequence.

Key	Value
`year`	The value of `fn:year-from-dateTime($value)`
`month`	The value of `fn:month-from-dateTime($value)`
`day`	The value of `fn:day-from-dateTime($value)`
`hours`	The value of `fn:hours-from-dateTime($value)`
`minutes`	The value of `fn:minutes-from-dateTime($value)`
`seconds`	The value of `fn:seconds-from-dateTime($value)`
`timezone`	The value of `fn:timezone-from-dateTime($value)`

Examples

Expression:	parts-of-dateTime( xs:dateTime("1999-05-31T13:20:00-05:00") )
Result:	{ "year": 1999, "month": 5, "day": 31, "hours": 13, "minutes": 20, "seconds": 0, "timezone": xs:dayTimeDuration("-PT5H") }
Expression:	parts-of-dateTime( xs:time("13:30:04.2678") )
Result:	{ "year": (), "month": (), "day": (), "hours": 13, "minutes": 30, "seconds": 4.2678, "timezone": () }
Expression:	parts-of-dateTime( xs:gYearMonth("2007-05Z") )
Result:	{ "year": 2007, "month": 5, "day": (), "hours": (), "minutes": (), "seconds": (), "timezone": xs:dayTimeDuration("-PT0S") }

9.69.7 Adjusting timezones on dates and times

Function	Meaning
`fn:adjust-dateTime-to-timezone`	Adjusts an `xs:dateTime` value to a specific timezone, or to no timezone at all.
`fn:adjust-date-to-timezone`	Adjusts an `xs:date` value to a specific timezone, or to no timezone at all; the result is the date in the target timezone that contains the starting instant of the supplied date.
`fn:adjust-time-to-timezone`	Adjusts an `xs:time` value to a specific timezone, or to no timezone at all.
`fn:civil-timezone`	Returns the timezone offset from UTC that is in conventional use at a given place and time.

These functions adjust the timezone component of an xs:dateTime, xs:date or xs:time value. The $timezone argument to these functions is defined as an xs:dayTimeDuration but must be a valid timezone value.

9.6.19.7.1 fn:adjust-dateTime-to-timezone

Summary

Adjusts an xs:dateTime value to a specific timezone, or to no timezone at all.

Signature

`fn:adjust-dateTime-to-timezone`(
`$value`	`as` `xs:dateTime?`,
`$timezone`	`as` `xs:dayTimeDuration?`	`:=` `fn:implicit-timezone()`
) `as` `xs:dateTime?`

Properties

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.

Rules

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.

Error Conditions

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.

Examples

Variables
let $tz-10 := xs:dayTimeDuration("-PT10H")

Assume the dynamic context provides an implicit timezone of `-05:00 (-PT5H0M)`.
Expression:	adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00') )
Result:	xs:dateTime('2002-03-07T10:00:00-05:00')
Expression:	adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00') )
Result:	xs:dateTime('2002-03-07T12:00:00-05:00')
Expression:	adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00'), $tz-10 )
Result:	xs:dateTime('2002-03-07T10:00:00-10:00')
Expression:	adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00'), $tz-10 )
Result:	xs:dateTime('2002-03-07T07:00:00-10:00')
Expression:	adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00'), xs:dayTimeDuration("PT10H") )
Result:	xs:dateTime('2002-03-08T03:00:00+10:00')
Expression:	adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T00:00:00+01:00'), xs:dayTimeDuration("-PT8H") )
Result:	xs:dateTime('2002-03-06T15:00:00-08:00')
Expression:	adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00'), () )
Result:	xs:dateTime('2002-03-07T10:00:00')
Expression:	adjust-dateTime-to-timezone( xs:dateTime('2002-03-07T10:00:00-07:00'), () )
Result:	xs:dateTime('2002-03-07T10:00:00')

9.6.29.7.2 fn:adjust-date-to-timezone

Summary

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.

Signature

`fn:adjust-date-to-timezone`(
`$value`	`as` `xs:date?`,
`$timezone`	`as` `xs:dayTimeDuration?`	`:=` `fn:implicit-timezone()`
) `as` `xs:date?`

Properties

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.

Rules

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:

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)

Error Conditions

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.

Examples

Variables
let $tz-10 := xs:dayTimeDuration("-PT10H")

Expression	Result
Assume the dynamic context provides an implicit timezone of `-05:00 (-PT5H0M)`.
adjust-date-to-timezone( xs:date("2002-03-07") )	xs:date("2002-03-07-05:00")
adjust-date-to-timezone( xs:date("2002-03-07-07:00") )	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"`. ).
adjust-date-to-timezone( xs:date("2002-03-07"), $tz-10 )	xs:date("2002-03-07-10:00")
adjust-date-to-timezone( xs:date("2002-03-07-07:00"), $tz-10 )	xs:date("2002-03-06-10:00") (`$value` is converted to `xs:dateTime("2002-03-07T00:00:00-07:00")`. This is adjusted to the given timezone, giving `"2002-03-06T21:00:00-10:00"`. ).
adjust-date-to-timezone( xs:date("2002-03-07"), () )	xs:date("2002-03-07")
adjust-date-to-timezone( xs:date("2002-03-07-07:00"), () )	xs:date("2002-03-07")

9.6.39.7.3 fn:adjust-time-to-timezone

Summary

Adjusts an xs:time value to a specific timezone, or to no timezone at all.

Signature

`fn:adjust-time-to-timezone`(
`$value`	`as` `xs:time?`,
`$timezone`	`as` `xs:dayTimeDuration?`	`:=` `fn:implicit-timezone()`
) `as` `xs:time?`

Properties

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.

Rules

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).

Error Conditions

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.

Examples

Variables
let $tz-10 := xs:dayTimeDuration("-PT10H")

Expression	Result
Assume the dynamic context provides an implicit timezone of `-05:00 (-PT5H0M)`.
adjust-time-to-timezone( xs:time("10:00:00") )	xs:time("10:00:00-05:00")
adjust-time-to-timezone( xs:time("10:00:00-07:00") )	xs:time("12:00:00-05:00")
adjust-time-to-timezone( xs:time("10:00:00"), $tz-10 )	xs:time("10:00:00-10:00")
adjust-time-to-timezone( xs:time("10:00:00-07:00"), $tz-10 )	xs:time("07:00:00-10:00")
adjust-time-to-timezone( xs:time("10:00:00"), () )	xs:time("10:00:00")
adjust-time-to-timezone( xs:time("10:00:00-07:00"), () )	xs:time("10:00:00")
adjust-time-to-timezone( xs:time("10:00:00-07:00"), xs:dayTimeDuration("PT10H") )	xs:time("03:00:00+10:00")

9.6.49.7.4 fn:civil-timezone

Changes in 4.0 (next | previous)

New in 4.0 [Issue 1539 PR 1545 5 November 2024]

Summary

Returns the timezone offset from UTC that is in conventional use at a given place and time.

Signature

`fn:civil-timezone`(
`$value`	`as` `xs:dateTime`,
`$place`	`as` `xs:string?`	`:=` `()`
) `as` `xs:dayTimeDuration`

Properties

The one-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on default place.

The two-argument form of this function is deterministic, context-independent, and focus-independent.

Rules

This function uses a database of civil timezones (including daylight savings time) to return the timezone offset for a given date/time and place. For example, the timezone offset for New York on 31 December 2024 would be -PT5H.

If the $place argument is omitted or empty then the default place^XP from the dynamic context is used.

If the supplied $value has no timezone then the implicit timezone from the dynamic context is used. This is unrelated to the timezone applicable to the requested $place.

The intended use of the $place argument is to identify the place where an event represented by the $value argument took place or will take place. The value must be an IANA timezone name as defined in the IANA timezone database [IANA Timezone Database]. Examples are "America/New_York" and "Europe/Rome".

The result of the function is the civil timezone offset applicable to the given date/time and place, as determined by the IANA timezone database or an alternative authoritative source.

Error Conditions

A dynamic error is raised [err:FODT0004] if no timezone information is available for the given date/time and place. This includes the case where the given place is not present in the timezone database, and also the case where the information available for that place does not cover a sufficient range of dates.

Examples

Expression:	civil-timezone( xs:dateTime('2024-12-31T23:59:59'), 'America/New_York')
Result:	xs:dayTimeDuration('-PT5H')
Expression:	civil-timezone( xs:dateTime('2024-06-30T23:59:59'), 'America/New_York')
Result:	xs:dayTimeDuration('-PT4H')
The expression:
adjust-dateTime-to-timezone( current-dateTime(), civil-timezone(current-dateTime(), 'America/New_York') )
returns the current civil date and time in New York.
If the default place is a location in the same timezone as (say) Paris, then the expression
civil-timezone(xs:dateTime('2024-07-01T09:00:00'))
returns PT2H.

9.79.8 Arithmetic operators on durations, dates and times

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)

9.7.19.8.1 Limits and precision

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.1 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.5 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.

9.7.29.8.2 op:subtract-dateTimes

Summary

Returns an xs:dayTimeDuration representing the amount of elapsed time between the instants arg2 and arg1.

Operator Mapping

Defines the semantics of the - operator when applied to two xs:dateTime values.

Signature

`op:subtract-dateTimes`(
`$arg1`	`as` `xs:dateTime`,
`$arg2`	`as` `xs:dateTime`
) `as` `xs:dayTimeDuration`

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on implicit timezone.

Rules

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 [XML Path Language (XPath) 4.0] section B.2 Dynamic Context Components.) 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.

Examples

Assume that the dynamic context provides an implicit timezone value of `-05:00`.
Expression:	op:subtract-dateTimes( xs:dateTime("2000-10-30T06:12:00"), xs:dateTime("1999-11-28T09:00:00Z") )
Result:	xs:dayTimeDuration("P337DT2H12M")

9.7.39.8.3 op:subtract-dates

Summary

Returns the xs:dayTimeDuration that corresponds to the elapsed time between the starting instant of $arg2 and the starting instant of $arg2.

Operator Mapping

Defines the semantics of the - operator when applied to two xs:date values.

Signature

`op:subtract-dates`(
`$arg1`	`as` `xs:date`,
`$arg2`	`as` `xs:date`
) `as` `xs:dayTimeDuration`

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on implicit timezone.

Rules

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.

Examples

Expression	Result
Assume that the dynamic context provides an implicit timezone value of `Z`.
op:subtract-dates( xs:date("2000-10-30"), xs:date("1999-11-28") )	xs:dayTimeDuration("P337D") (The normalized values of the two starting instants are `{ 2000, 10, 30, 0, 0, 0, xs:dayTimeDuration("PT0S") }` and `{ 1999, 11, 28, 0, 0, 0, xs:dayTimeDuration("PT0S") }`.)
Now assume that the dynamic context provides an implicit timezone value of `+05:00`.
op:subtract-dates( xs:date("2000-10-30"), xs:date("1999-11-28Z") )	xs:dayTimeDuration("P336DT19H") ( The normalized values of the two starting instants are `{ 2000, 10, 29, 19, 0, 0, xs:dayTimeDuration("PT0S") }` and `{ 1999, 11, 28, 0, 0, 0, xs:dayTimeDuration("PT0S") }`.)
op:subtract-dates( xs:date("2000-10-15-05:00"), xs:date("2000-10-10+02:00") )	xs:dayTimeDuration("P5DT7H")

9.7.49.8.4 op:subtract-times

Summary

Returns the xs:dayTimeDuration that corresponds to the elapsed time between the values of $arg2 and $arg1 treated as times on the same date.

Operator Mapping

Defines the semantics of the - operator when applied to two xs:time values.

Signature

`op:subtract-times`(
`$arg1`	`as` `xs:time`,
`$arg2`	`as` `xs:time`
) `as` `xs:dayTimeDuration`

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on implicit timezone.

Rules

The function returns the result of the expression:

op-subtract-dateTimes(
        dateTime(xs:date('1972-12-31'), $arg1),
        dateTime(xs:date('1972-12-31'), $arg2))

Notes

Any other reference date would work equally well.

Examples

Expression	Result
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"`.
op:subtract-times( xs:time("11:12:00Z"), xs:time("04:00:00") )	xs:dayTimeDuration("PT2H12M") (This is obtained by subtracting from the `xs:dateTime` value `{ 1972, 12, 31, 11, 12, 0, xs:dayTimeDuration("PT0S") }` the `xs:dateTime` value `{ 1972, 12, 31, 9, 0, 0, xs:dayTimeDuration("PT0S") }`.)
op:subtract-times( xs:time("11:00:00-05:00"), xs:time("21:30:00+05:30") )	xs:dayTimeDuration("PT0S") (The two `xs:dateTime` values are `{ 1972, 12, 31, 11, 0, 0, xs:dayTimeDuration("-PT5H") }` and `{ 1972, 12, 31, 21, 30, 0, xs:dayTimeDuration("PT5H30M") }`. These normalize to `{ 1972, 12, 31, 16, 0, 0, xs:dayTimeDuration("PT0S") }` and `{ 1972, 12, 31, 16, 0, 0, xs:dayTimeDuration("PT0S") }`. ).
op:subtract-times( xs:time("17:00:00-06:00"), xs:time("08:00:00+09:00") )	xs:dayTimeDuration("P1D") (The two normalized `xs:dateTime` values are `{ 1972, 12, 31, 23, 0, 0, xs:dayTimeDuration("PT0S") }` and `{ 1972, 12, 30, 23, 0, 0, xs:dayTimeDuration("PT0S") }`.)
op:subtract-times( xs:time("24:00:00"), xs:time("23:59:59") )	xs:dayTimeDuration("-PT23H59M59S") (The two normalized `xs:dateTime` values are `{ 1972, 12, 31, 0, 0, 0, () }` and `{ 1972, 12, 31, 23, 59, 59.0, () }`.)

9.7.59.8.5 op:add-yearMonthDuration-to-dateTime

Summary

Returns the xs:dateTime that is a given duration after a specified xs:dateTime (or before, if the duration is negative).

Operator Mapping

Defines the semantics of the + operator when applied to an xs:dateTime and an xs:yearMonthDuration value.

Signature

`op:add-yearMonthDuration-to-dateTime`(
`$arg1`	`as` `xs:dateTime`,
`$arg2`	`as` `xs:yearMonthDuration`
) `as` `xs:dateTime`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Examples

Expression:	op:add-yearMonthDuration-to-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:yearMonthDuration("P1Y2M") )
Result:	xs:dateTime("2001-12-30T11:12:00")

9.7.69.8.6 op:add-dayTimeDuration-to-dateTime

Summary

Returns the xs:dateTime that is a given duration after a specified xs:dateTime (or before, if the duration is negative).

Operator Mapping

Defines the semantics of the + operator when applied to an xs:dateTime and an xs:dayTimeDuration value.

Signature

`op:add-dayTimeDuration-to-dateTime`(
`$arg1`	`as` `xs:dateTime`,
`$arg2`	`as` `xs:dayTimeDuration`
) `as` `xs:dateTime`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

The result has the same timezone as $arg1. If $arg1 has no timezone, the result has no timezone.

Examples

Expression:	op:add-dayTimeDuration-to-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:dayTimeDuration("P3DT1H15M") )
Result:	xs:dateTime("2000-11-02T12:27:00")

9.7.79.8.7 op:subtract-yearMonthDuration-from-dateTime

Summary

Returns the xs:dateTime that is a given duration before a specified xs:dateTime (or after, if the duration is negative).

Operator Mapping

Defines the semantics of the - operator when applied to an xs:dateTime and an xs:yearMonthDuration value.

Signature

`op:subtract-yearMonthDuration-from-dateTime`(
`$arg1`	`as` `xs:dateTime`,
`$arg2`	`as` `xs:yearMonthDuration`
) `as` `xs:dateTime`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

The function returns the xs:dateTime computed by negating $arg2 and adding the result to $arg1 using the function op:add-yearMonthDuration-to-dateTime.

Examples

Expression:	op:subtract-yearMonthDuration-from-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:yearMonthDuration("P1Y2M") )
Result:	xs:dateTime("1999-08-30T11:12:00")

9.7.89.8.8 op:subtract-dayTimeDuration-from-dateTime

Summary

Returns the xs:dateTime that is a given duration before a specified xs:dateTime (or after, if the duration is negative).

Operator Mapping

Defines the semantics of the - operator when applied to an xs:dateTime an and xs:dayTimeDuration values

Signature

`op:subtract-dayTimeDuration-from-dateTime`(
`$arg1`	`as` `xs:dateTime`,
`$arg2`	`as` `xs:dayTimeDuration`
) `as` `xs:dateTime`

Rules

The function returns the xs:dateTime computed by negating $arg2 and adding the result to $arg1 using the function op:add-dayTimeDuration-to-dateTime.

Examples

Expression:	op:subtract-dayTimeDuration-from-dateTime( xs:dateTime("2000-10-30T11:12:00"), xs:dayTimeDuration("P3DT1H15M") )
Result:	xs:dateTime("2000-10-27T09:57:00")

9.7.99.8.9 op:add-yearMonthDuration-to-date

Summary

Returns the xs:date that is a given duration after a specified xs:date (or before, if the duration is negative).

Operator Mapping

Defines the semantics of the + operator when applied to an xs:date and an xs:yearMonthDuration value.

Signature

`op:add-yearMonthDuration-to-date`(
`$arg1`	`as` `xs:date`,
`$arg2`	`as` `xs:yearMonthDuration`
) `as` `xs:date`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Examples

Expression:	op:add-yearMonthDuration-to-date( xs:date("2000-10-30"), xs:yearMonthDuration("P1Y2M") )
Result:	xs:date("2001-12-30")

9.7.109.8.10 op:add-dayTimeDuration-to-date

Summary

Returns the xs:date that is a given duration after a specified xs:date (or before, if the duration is negative).

Operator Mapping

Defines the semantics of the + operator when applied to an xs:date and an xs:dayTimeDuration value.

Signature

`op:add-dayTimeDuration-to-date`(
`$arg1`	`as` `xs:date`,
`$arg2`	`as` `xs:dayTimeDuration`
) `as` `xs:date`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Examples

Expression:	op:add-dayTimeDuration-to-date( xs:date("2004-10-30Z"), xs:dayTimeDuration("P2DT2H30M0S") )
Result:	xs:date("2004-11-01Z") ( The starting instant of the first argument is the `xs:dateTime` value `{ 2004, 10, 30, 0, 0, 0, xs:dayTimeDuration("PT0S") }`. Adding the second argument to this gives the `xs:dateTime` value `{ 2004, 11, 1, 2, 30, 0, xs:dayTimeDuration("PT0S") }`. The time components are then discarded. ).

9.7.119.8.11 op:subtract-yearMonthDuration-from-date

Summary

Returns the xs:date that is a given duration before a specified xs:date (or after, if the duration is negative).

Operator Mapping

Defines the semantics of the - operator when applied to an xs:date and an xs:yearMonthDuration value.

Signature

`op:subtract-yearMonthDuration-from-date`(
`$arg1`	`as` `xs:date`,
`$arg2`	`as` `xs:yearMonthDuration`
) `as` `xs:date`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

Returns the xs:date computed by negating $arg2 and adding the result to $arg1 using the function op:add-yearMonthDuration-to-date.

Examples

Expression:	op:subtract-yearMonthDuration-from-date( xs:date("2000-10-30"), xs:yearMonthDuration("P1Y2M") )
Result:	xs:date("1999-08-30")
Expression:	op:subtract-yearMonthDuration-from-date( xs:date("2000-02-29Z"), xs:yearMonthDuration("P1Y") )
Result:	xs:date("1999-02-28Z")
Expression:	op:subtract-yearMonthDuration-from-date( xs:date("2000-10-31-05:00"), xs:yearMonthDuration("P1Y1M") )
Result:	xs:date("1999-09-30-05:00")

9.7.129.8.12 op:subtract-dayTimeDuration-from-date

Summary

Returns the xs:date that is a given duration before a specified xs:date (or after, if the duration is negative).

Operator Mapping

Defines the semantics of the - operator when applied to an xs:date and an xs:dayTimeDuration.

Signature

`op:subtract-dayTimeDuration-from-date`(
`$arg1`	`as` `xs:date`,
`$arg2`	`as` `xs:dayTimeDuration`
) `as` `xs:date`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

Returns the xs:date computed by negating $arg2 and adding the result to $arg1 using the function op:add-dayTimeDuration-to-date.

Examples

Expression:	op:subtract-dayTimeDuration-from-date( xs:date("2000-10-30"), xs:dayTimeDuration("P3DT1H15M") )
Result:	xs:date("2000-10-26")

9.7.139.8.13 op:add-dayTimeDuration-to-time

Summary

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)

Operator Mapping

Defines the semantics of the + operator when applied to an xs:time and an xs:dayTimeDuration value.

Signature

`op:add-dayTimeDuration-to-time`(
`$arg1`	`as` `xs:time`,
`$arg2`	`as` `xs:dayTimeDuration`
) `as` `xs:time`

Rules

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.

Examples

Expression:	op:add-dayTimeDuration-to-time( xs:time("11:12:00"), xs:dayTimeDuration("P3DT1H15M") )
Result:	xs:time("12:27:00")
Expression:	op:add-dayTimeDuration-to-time( xs:time("23:12:00+03:00"), xs:dayTimeDuration("P1DT3H15M") )
Result:	xs:time("02:27:00+03:00") (That is, `{ 0, 0, 0, 2, 27, 0, xs:dayTimeDuration("PT3H") }`).

9.7.149.8.14 op:subtract-dayTimeDuration-from-time

Summary

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)

Operator Mapping

Defines the semantics of the - operator when applied to an xs:time and an xs:dayTimeDuration value.

Signature

`op:subtract-dayTimeDuration-from-time`(
`$arg1`	`as` `xs:time`,
`$arg2`	`as` `xs:dayTimeDuration`
) `as` `xs:time`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

The function returns the result of negating $arg2 and adding the result to $arg1 using the function op:add-dayTimeDuration-to-time.

Examples

Expression:	op:subtract-dayTimeDuration-from-time( xs:time("11:12:00"), xs:dayTimeDuration("P3DT1H15M") )
Result:	xs:time("09:57:00")
Expression:	op:subtract-dayTimeDuration-from-time( xs:time("08:20:00-05:00"), xs:dayTimeDuration("P23DT10H10M") )
Result:	xs:time("22:10:00-05:00")

9.89.9 Formatting dates and times

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 functions are presented in their customary fashion, except for the rules and examples, which are described en bloc at 9.8.49.9.4 The date/time formatting functions and 9.8.59.9.5 Examples of date and time formatting.

9.8.19.9.1 fn:format-dateTime

Changes in 4.0 (next | previous)

The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments. [Issue 895 PR 901 16 December 2023]

Summary

Returns a string containing an xs:dateTime value formatted for display.

Signature

`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?`

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on default calendar, and default language, and default place, and implicit timezone.

Rules

See 9.8.49.9.4 The date/time formatting functions.

9.8.29.9.2 fn:format-date

Changes in 4.0 (next | previous)

The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments. [Issue 895 PR 901 16 December 2023]

Summary

Returns a string containing an xs:date value formatted for display.

Signature

`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?`

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on default calendar, and default language, and default place, and implicit timezone.

Rules

See 9.8.49.9.4 The date/time formatting functions.

9.8.39.9.3 fn:format-time

Changes in 4.0 (next | previous)

The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments. [Issue 895 PR 901 16 December 2023]

Summary

Returns a string containing an xs:time value formatted for display.

Signature

`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?`

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on default calendar, and default language, and default place, and implicit timezone.

Rules

See 9.8.49.9.4 The date/time formatting functions.

9.8.49.9.4 The date/time formatting functions

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.89.9.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.

9.8.4.19.9.4.1 The picture string

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.

9.8.4.29.9.4.2 The Width 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.

9.8.4.39.9.4.3 Formatting Integer-Valued Date/Time Components

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:
1. If there is no width modifier, then the value is formatted according to the rules of the format-integer function.
2. If there is a width modifier, then the first presentation modifier is adjusted as follows:
  1. 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.
  2. 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.
  3. The maximum width, if specified, is ignored.
  4. 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:
1. 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.
2. If FN is shorter than the minimum width, then it is padded by appending spaces to the end of the name.
3. 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:
1. Any adjustment of the value to fit within the requested width range is implementation-defined.
2. 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).
3. 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.

9.8.4.49.9.4.4 Formatting the Year Component

The rules for the year component (Y) are the same as those in 9.8.4.39.9.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:
1. Let W be the number of optional-digit-signs and mandatory-digit-signs in that decimal-digit-pattern.
2. If W is 2 or more, then W.
Otherwise, N is infinity (that is, the year is output in full).

9.8.4.59.9.4.5 Formatting Fractional Seconds

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:
1. 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.
2. If there is a width modifier, then the first presentation modifier is adjusted as follows:
  1. 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.
  2. 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.
3. 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.
4. 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.
5. 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
6. The resulting string is reversed. In our example, the result is 823'5.
7. 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 reuse 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].

9.8.4.69.9.4.6 Formatting timezones

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 Modifier9.9.4.2 The Width Modifier9.8.4.29.9.4.2 The Width Modifier, but it is never shortened.

9.8.4.79.9.4.7 Formatting Other Components

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.89.9.4.8 The language, calendar, and place arguments.

9.8.4.89.9.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 [Extensible Markup Language (XML) 1.0 (Fifth Edition)]). 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 grammatical 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 (Islamic Era)
AME	Mauludi Era (solar years since Muhammad’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	Solar Hijri (Islamic Era, used in Iran and Afghanistan)
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.

9.8.59.9.5 Examples of date and time formatting

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", ())`	๓๑ ธันวาคม ๒๕๔๕

9.99.10 Parsing dates and times

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.

9.9.19.10.1 fn:parse-ietf-date

Summary

Parses a string containing the date and time in IETF format, returning the corresponding xs:dateTime value.

Signature

`fn:parse-ietf-date`(
`$value`	`as` `xs:string?`
) `as` `xs:dateTime?`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

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.

Error Conditions

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").

Notes

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]".

Examples

Expression	Result
`parse-ietf-date("Wed, 06 Jun 1994 07:29:35 GMT")`	`xs:dateTime("1994-06-06T07:29:35Z")`
`parse-ietf-date("Wed, 6 Jun 94 07:29:35 GMT")`	`xs:dateTime("1994-06-06T07:29:35Z")`
`parse-ietf-date("Wed Jun 06 11:54:45 EST 2013")`	`xs:dateTime("2013-06-06T11:54:45-05:00")`
`parse-ietf-date("Sunday, 06-Nov-94 08:49:37 GMT")`	`xs:dateTime("1994-11-06T08:49:37Z")`
`parse-ietf-date("Wed, 6 Jun 94 07:29:35 +0500")`	`xs:dateTime("1994-06-06T07:29:35+05:00")`

18 Dynamic evaluation

The following functions allow dynamic loading and evaluation of XQuery queries, XSLT stylesheets, and XPath binary operators.

Function	Meaning
`fn:load-xquery-module`	Provides access to the public functions and global variables of a dynamically loaded XQuery library module.
`fn:transform`	Invokes a transformation using a dynamically loaded XSLT stylesheet.
`fn:op`	Returns a function whose effect is to apply a supplied binary operator to two arguments.

18.1 Record fn:load-xquery-module-record

This record type is used to hold the result of the fn:load-xquery-module function.

Name Meaning

variables

global variable declared in the library module. The key of the

This map (V ) contains one entry for each public global variable declared in the library module. The key of the entry is the name of the variable, as an xs:QName value; the associated value is the value of the variable.

Type: map(xs:QName, item()*)

functions

This map (F ) contains one entry for each distinct QName Q that represents the name of a public and non-external function declared in the library module. The key of the entry is Q, as an xs:QName value; the associated value is a map A. This map (A) contains one entry for each arity N within the arity range of any of the function declarations with the given name; its key is N, as an xs:integer value, and its associated value is a function item obtained as if by evaluating a named function reference Q#N, using the static and dynamic context of the call on fn:load-xquery-module. The function item can be invoked using the rules for dynamic function invocation.

Type: map(xs:QName, map(xs:integer, function(*)))

B Error codes

The error text provided with these errors is non-normative.

err:FOAP0001, Wrong number of arguments.: Raised when fn:apply is called and the arity of the supplied function is not the same as the number of members in the supplied array.
err:FOAR0001, Division by zero.: This error is raised whenever an attempt is made to divide by zero.
err:FOAR0002, Numeric operation overflow/underflow.: This error is raised whenever numeric operations result in an overflow or underflow.
err:FOAY0001, Array index out of bounds.: This error is raised when an integer used to select a member of an array is outside the range of values for that array.
err:FOAY0002, Negative array length.: This error is raised when the $length argument to array:subarray is negative.
err:FOCA0001, Input value too large for decimal.: Raised when casting to xs:decimal if the supplied value exceeds the implementation-defined limits for the datatype.
err:FOCA0002, Invalid lexical value.: Raised by fn:resolve-QName and fn:QName when a supplied value does not have the lexical form of a QName or URI respectively; and when casting to decimal, if the supplied value is NaN or Infinity.
err:FOCA0003, Input value too large for integer.: Raised when casting to xs:integer if the supplied value exceeds the implementation-defined limits for the datatype.
err:FOCA0005, NaN supplied as float/double value.: Raised when multiplying or dividing a duration by a number, if the number supplied is NaN.
err:FOCA0006, String to be cast to decimal has too many digits of precision.: Raised when casting a string to xs:decimal if the string has more digits of precision than the implementation can represent (the implementation also has the option of rounding).
err:FOCH0001, Codepoint not valid.: Raised by fn:codepoints-to-string if the input contains an integer that is not the codepoint of a permitted character.
err:FOCH0002, Unsupported collation.: Raised by any function that uses a collation if the requested collation is not recognized.
err:FOCH0003, Unsupported normalization form.: Raised by fn:normalize-unicode if the requested normalization form is not supported by the implementation.
err:FOCH0004, Collation does not support collation units.: Raised by functions such as fn:contains if the requested collation does not operate on a character-by-character basis.
err:FOCH0005, Unrecognized or invalid character name.: Raised by fn:char if the supplied character name is not recognized, or if it represents a codepoint that is not a permitted character.
err:FOCV0001, CSV field quoting error.: Raised when parsing CSV input if a syntax error in the input CSV is found.
err:FOCV0002, Invalid CSV delimiter error.: Raised when parsing CSV input if the field-separator, record-separator, or quote-character option is set to an invalid value.
err:FOCV0003, Duplicate CSV delimiter error.: Raised when parsing CSV input if the same delimiter character is assigned to more than one role.
err:FOCV0004, Argument supplied is not a known column name.: Raised by the function from the get entry of csv-columns-record, if its $key argument is an xs:string and is not one of the known column names.
err:FODC0001, No context document.: Raised by fn:id, fn:idref, and fn:element-with-id if the node that identifies the tree to be searched is a node in a tree whose root is not a document node.
err:FODC0002, Error retrieving resource.: Raised by fn:doc, fn:collection, and fn:uri-collection to indicate that either the supplied URI cannot be dereferenced to obtain a resource, or the resource that is returned is not parseable as XML.
err:FODC0003, Function not defined as deterministic.: Raised by fn:doc, fn:collection, and fn:uri-collection to indicate that it is not possible to return a result that is guaranteed deterministic.
err:FODC0004, Invalid collection URI.: Raised by fn:collection and fn:uri-collection if the argument is not a valid xs:anyURI.
err:FODC0005, Invalid URI reference.: Raised (optionally) by fn:doc if the argument is not a valid xs:anyURI.
err:FODC0006, String passed to fn:parse-xml is not a well-formed XML document.: Raised by fn:parse-xml if the supplied string is not a well-formed and namespace-well-formed XML document; or if DTD validation is requested and the document is not valid against its DTD.
err:FODC0007, String passed to fn:parse-xml is not a DTD-valid XML document.: Raised by fn:parse-xml if DTD validation is requested and the supplied string has no DTD or is not valid against the DTD.
err:FODC0008, Invalid value for the xsd-validation option of fn:parse-xml.: Raised when the xsd-validation option to fn:parse-xml is supplied, and the value is not one of the permitted values; for example if the option type Q{U}NNN is used, and Q{U}NNN does not identify a type in the static context.
err:FODC0009, Processor is not schema-aware.: Raised when the xsd-validation option to fn:parse-xml is set to a value other than skip, if the processor is not schema-aware.
err:FODC0010, The processor does not support serialization.: Raised when fn:serialize is called and the processor does not support serialization, in cases where the host language makes serialization an optional feature.
err:FODC0011, String passed to fn:parse-html is not a well-formed HTML document.: Raised by fn:parse-html if the supplied string is not a well-formed HTML document.
err:FODC0013, No validating XML parser available.: Raised when the dtd-validation option to fn:parse-xml is set, if no validating XML parser is available. Note: it is recommended that all processors should support the dtd-validation option, but there may be environments (such as web browsers) where this is not practically feasible.
err:FODC0014, String passed to fn:parse-xml is not a schema-valid XML document.: Raised by fn:parse-xml if XSD validation is requested and the XML document represented by the supplied string is not valid against the relevant XSD schema.
err:FODC0015, Unable to compile schema for fn:xsd-validator.: Raised by fn:xsd-validator if it is not possible to assemble a valid and consistent schema.
err:FODF1280, Invalid decimal format name.: This error is raised if the decimal format name supplied to fn:format-number is not a valid QName, or if the prefix in the QName is undeclared, or if there is no decimal format in the static context with a matching name.
err:FODF1290, Invalid decimal format property.: This error is raised if a decimal format value supplied to fn:format-number is not valid for the associated property, or if the properties of the decimal format resulting from a supplied map do not have distinct values.
err:FODF1310, Invalid decimal format picture string.: This error is raised if the picture string supplied to fn:format-number or fn:format-integer has invalid syntax.
err:FODT0001, Overflow/underflow in date/time operation.: Raised when casting to date/time datatypes, or performing arithmetic with date/time values, if arithmetic overflow or underflow occurs.
err:FODT0002, Overflow/underflow in duration operation.: Raised when casting to duration datatypes, or performing arithmetic with duration values, if arithmetic overflow or underflow occurs.
err:FODT0003, Invalid timezone value.: Raised by adjust-date-to-timezone and related functions if the supplied timezone is invalid.
err:FODT0004, No timezone data available: Raised by civil-timezone if no timezone data is available for the given date/time and place.
err:FODT0005, Invalid combination of date/time fields: Raised by build-dateTime if the set of fields supplied does not correspond to those present in one of the Gregorian types.
err:FODT0006, Invalid component of date/time vallue: Raised by build-dateTime if one of the fields supplied has a value that is outside the supported range.
err:FOER0000, Unidentified error.: Error code used by fn:error when no other error code is provided.
err:FOFD1340, Invalid date/time formatting parameters.: This error is raised if the picture string or calendar supplied to fn:format-date, fn:format-time, or fn:format-dateTime has invalid syntax.
err:FOFD1350, Invalid date/time formatting component.: This error is raised if the picture string supplied to fn:format-date selects a component that is not present in a date, or if the picture string supplied to fn:format-time selects a component that is not present in a time.
err:FOHA0001, Invalid algorithm.: Raised by fn:hash if the effective value of the supplied algorithm is not one of the values supported by the implementation.
err:FOJS0001, JSON syntax error.: Raised by functions such as fn:json-doc, fn:parse-json or fn:json-to-xml if the string supplied as input does not conform to the JSON grammar (optionally with implementation-defined extensions).
err:FOJS0003, JSON duplicate keys.: Raised by functions such as map:merge, fn:json-doc, fn:parse-json or fn:json-to-xml if the input contains duplicate keys, when the chosen policy is to reject duplicates.
err:FOJS0004, JSON: not schema-aware.: Raised by fn:json-to-xml if validation is requested when the processor does not support schema validation or typed nodes.
err:FOJS0005, Invalid options.: Raised by functions such as map:merge, fn:parse-json, and fn:xml-to-json if the $options map contains an invalid entry.
err:FOJS0006, Invalid XML representation of JSON.: Raised by fn:xml-to-json if the XML input does not conform to the rules for the XML representation of JSON.
err:FOJS0007, Bad JSON escape sequence.: Raised by fn:xml-to-json if the XML input uses the attribute escaped="true" or escaped-key="true", and the corresponding string or key contains an invalid JSON escape sequence.
err:FOJS0008, Cannot convert element to map.: Raised by fn:element-to-map if the layout selected for converting elements of a given name is unsuitable for an element node with that name, or if the conversion plan explicitly defines the processing of a particular element as an error.
err:FONS0004, No namespace found for prefix.: Raised by fn:resolve-QName and analogous functions if a supplied QName has a prefix that has no binding to a namespace.
err:FONS0005, Base-uri not defined in the static context.: Raised by fn:resolve-uri if no base URI is available for resolving a relative URI.
err:FOPA0001, Origin node is not an ancestor of the target node.: Raised by fn:path if the node supplied in the origin option is not an ancestor of the $node whose relative path is required.
err:FOQM0001, Module URI is a zero-length string.: Raised by fn:load-xquery-module if the supplied module URI is zero-length.
err:FOQM0002, Module URI not found.: Raised by fn:load-xquery-module if no module can be found with the supplied module URI.
err:FOQM0003, Static error in dynamically loaded XQuery module.: Raised by fn:load-xquery-module if a static error (including a statically detected type error) is encountered when processing the library module.
err:FOQM0005, Parameter for dynamically loaded XQuery module has incorrect type.: Raised by fn:load-xquery-module if a value is supplied for the initial context item or for an external variable, and the value does not conform to the required type declared in the dynamically loaded module.
err:FOQM0006, No suitable XQuery processor available.: Raised by fn:load-xquery-module if no XQuery processor is available supporting the requested XQuery version (or if none is available at all).
err:FORG0001, Invalid value for cast/constructor.: A general-purpose error raised when casting, if a cast between two datatypes is allowed in principle, but the supplied value cannot be converted: for example when attempting to cast the string "nine" to an integer.
err:FORG0002, Invalid argument to fn:resolve-uri.: Raised when either argument to fn:resolve-uri is not a valid URI/IRI.
err:FORG0003, fn:zero-or-one called with a sequence containing more than one item.: Raised by fn:zero-or-one if the supplied value contains more than one item.
err:FORG0004, fn:one-or-more called with a sequence containing no items.: Raised by fn:one-or-more if the supplied value is an empty sequence.
err:FORG0005, fn:exactly-one called with a sequence containing zero or more than one item.: Raised by fn:exactly-one if the supplied value is not a singleton sequence.
err:FORG0006, Invalid argument type.: Raised by functions such as fn:max, fn:min, fn:avg, fn:sum if the supplied sequence contains values inappropriate to this function.
err:FORG0008, The two arguments to fn:dateTime have inconsistent timezones.: Raised by fn:dateTime if the two arguments both have timezones and the timezones are different.
err:FORG0009, Error in resolving a relative URI against a base URI in fn:resolve-uri.: A catch-all error for fn:resolve-uri, recognizing that the implementation can choose between a variety of algorithms and that some of these may fail for a variety of reasons.
err:FORG0010, Invalid date/time.: Raised when the input to fn:parse-ietf-date does not match the prescribed grammar, or when it represents an invalid date/time such as 31 February.
err:FORG0011, Invalid radix.: Raised when the radix supplied to fn:parse-integer is not in the range 2 to 36.
err:FORG0012, Invalid digits.: Raised when the digits in the string supplied to fn:parse-integer are not in the range appropriate to the chosen radix.
err:FORX0001, Invalid regular expression flags.: Raised by regular expression functions such as fn:matches and fn:replace if the regular expression flags contain a character other than i, m, q, s, or x.
err:FORX0002, Invalid regular expression.: Raised by regular expression functions such as fn:matches and fn:replace if the regular expression is syntactically invalid.
err:FORX0004, Invalid replacement string.: Raised by fn:replace to report errors in the replacement string.
err:FORX0005, Incompatible arguments for fn:replace.: Raised by fn:replace if both the $replacement and $action arguments are supplied.
err:FOTY0012, Argument to fn:data contains a node that does not have a typed value.: Raised by fn:data, or by implicit atomization, if applied to a node with no typed value, the main example being an element validated against a complex type that defines it to have element-only content.
err:FOTY0013, The argument to fn:data contains a function item.: Raised by fn:data, or by implicit atomization, if the sequence to be atomized contains a function item other than an array.
err:FOTY0014, The argument to fn:string is a function item.: Raised by fn:string, or by implicit string conversion, if the input sequence contains a function item.
err:FOUR0001, Invalid IPv6/IPvFuture authority: A dynamic error is raised if the authority component of a URI contains an open square bracket but no corresponding close square bracket.
err:FOUT1170, Invalid URI reference.: Raised by fn:unparsed-text or fn:unparsed-text-lines if the $source argument contains a fragment identifier, or if it cannot be resolved to an absolute URI (for example, because the base-URI property in the static context is absent), or if it cannot be used to retrieve the string representation of a resource.
err:FOUT1190, Cannot decode external resource.: Raised by fn:unparsed-text or fn:unparsed-text-lines if the $encoding argument is not a valid encoding name, if the processor does not support the specified encoding, if the string representation of the retrieved resource contains octets that cannot be decoded into Unicode characters using the specified encoding, or if the resulting characters are not permitted characters.
err:FOUT1200, Cannot infer encoding of external resource.: Raised by fn:unparsed-text or fn:unparsed-text-lines if the $encoding argument is absent and the processor cannot infer the encoding using external information and the encoding is not UTF-8.
err:FOXT0001, No suitable XSLT processor available: A dynamic error is raised if no XSLT processor suitable for evaluating a call on fn:transform is available.
err:FOXT0002, Invalid parameters to XSLT transformation: A dynamic error is raised if the parameters supplied to fn:transform are invalid, for example if two mutually exclusive parameters are supplied. If a suitable XSLT error code is available (for example in the case where the requested initial-template does not exist in the stylesheet), that error code should be used in preference.
err:FOXT0003, XSLT transformation failed: A dynamic error is raised if an XSLT transformation invoked using fn:transform fails with a static or dynamic error. The XSLT error code is used if available; this error code provides a fallback when no XSLT error code is returned, for example because the processor is an XSLT 1.0 processor.
err:FOXT0004, XSLT transformation has been disabled: A dynamic error is raised if the fn:transform function is invoked when XSLT transformation (or a specific transformation option) has been disabled for security or other reasons.
err:FOXT0006, XSLT output contains non-accepted characters: A dynamic error is raised if the result of the fn:transform function contains characters available only in XML 1.1 and the calling processor cannot handle such characters.

C Built-in named record types

Changes in 4.0 (next | previous)

Named record types used in the signatures of built-in functions are now available as standard in the static context. [Issue 835 PR 1991 11 May 2025]

This appendix lists the named record types that are used in function signatures in this function library, and that are available in the static context of every application.

These definitions are all in the standard function namespace http://www.w3.org/2005/xpath-functions, which is normally bound to the prefix fn. Because this will not usually be the default namespace for types, the names will usually be written with the prefix fn.

Record dateTime-record
Record dateTime-record
Record load-xquery-module-record
Record parsed-csv-structure-record
Record random-number-generator-record
Record schema-type-record
Record uri-structure-record

G Implementation-defined features (Non-Normative)

It is implementation-defined which version of Unicode is supported, but it is recommended that the most recent version of Unicode be used. (See Conformance.)
It is implementation-defined whether the type system is based on XML Schema 1.0 or XML Schema 1.1. (See Conformance.)
It is implementation-defined whether definitions that rely on XML (for example, the set of valid XML characters) should use the definitions in XML 1.0 or XML 1.1. (See Conformance.)
Implementations may attach an implementation-defined meaning to options in the map that are not described in this specification. These options should use values of type xs:QName as the option names, using an appropriate namespace. (See Options.)
It is implementation-defined which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used. (See Strings, characters, and codepoints.)
[Definition] Some functions (such as fn:in-scope-prefixes, fn:load-xquery-module, and fn:unordered) produce result sequences or result maps in an implementation-defined or implementation-dependent order. In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are said to be nondeterministic with respect to ordering. (See Properties of functions.)
Where the results of a function are described as being (to a greater or lesser extent) implementation-defined or implementation-dependent, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results. (See Properties of functions.)
They may provide an implementation-defined mechanism that allows users to choose between raising an error and returning a result that is modulo the largest representable integer value. See [ISO 10967]. (See Arithmetic operators on numeric values.)
For xs:decimal values, let N be the number of digits of precision supported by the implementation, and let M (M <= N) be the minimum limit on the number of digits required for conformance (18 digits for XSD 1.0, 16 digits for XSD 1.1). Then for addition, subtraction, and multiplication operations, the returned result should be accurate to N digits of precision, and for division and modulus operations, the returned result should be accurate to at least M digits of precision. The actual precision is implementation-defined. If the number of digits in the mathematical result exceeds the number of digits that the implementation retains for that operation, the result is truncated or rounded in an implementation-defined manner. (See Arithmetic operators on numeric values.)
The [IEEE 754-2019] specification also describes handling of two exception conditions called divideByZero and invalidOperation. The IEEE divideByZero exception is raised not only by a direct attempt to divide by zero, but also by operations such as log(0). The IEEE invalidOperation exception is raised by attempts to call a function with an argument that is outside the function’s domain (for example, sqrt(-1) or log(-1)). Although IEEE defines these as exceptions, it also defines “default non-stop exception handling” in which the operation returns a defined result, typically positive or negative infinity, or NaN. With this function library, these IEEE exceptions do not cause a dynamic error at the application level; rather they result in the relevant function or operator returning the defined non-error result. The underlying IEEE exception may be notified to the application or to the user by some implementation-defined warning condition, but the observable effect on an application using the functions and operators defined in this specification is simply to return the defined result (typically -INF, +INF, or NaN) with no error. (See Arithmetic operators on numeric values.)
The [IEEE 754-2019] specification distinguishes two NaN values: a quiet NaN and a signaling NaN. These two values are not distinguishable in the XDM model: the value spaces of xs:float and xs:double each include only a single NaN value. This does not prevent the implementation distinguishing them internally, and triggering different implementation-defined warning conditions, but such distinctions do not affect the observable behavior of an application using the functions and operators defined in this specification. (See Arithmetic operators on numeric values.)
The implementation may adopt a different algorithm provided that it is equivalent to this formulation in all cases where implementation-dependent or implementation-defined behavior does not affect the outcome, for example, the implementation-defined precision of the result of xs:decimal division. (See op:numeric-integer-divide.)
There may be implementation-defined limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation. (See fn:divide-decimals.)
There may be implementation-defined limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation. (See fn:round.)
There may be implementation-defined limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation. (See fn:round-half-to-even.)
XSD 1.1 allows the string +INF as a representation of positive infinity; XSD 1.0 does not. It is implementation-defined whether XSD 1.1 is supported. (See fn:number.)
Any other format token, which indicates a numbering sequence in which that token represents the number 1 (one) (but see the note below). It is implementation-defined which numbering sequences, additional to those listed above, are supported. If an implementation does not support a numbering sequence represented by the given token, it must use a format token of 1. (See fn:format-integer.)
For all format tokens other than a digit-pattern, there may be implementation-defined lower and upper bounds on the range of numbers that can be formatted using this format token; indeed, for some numbering sequences there may be intrinsic limits. For example, the format token U+2460 (CIRCLED DIGIT ONE, ①) has a range imposed by the Unicode character repertoire — zero to 20 in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering sequences described above any upper bound imposed by the implementation must not be less than 1000 (one thousand) and any lower bound must not be greater than 1. Numbers that fall outside this range must be formatted using the format token 1. (See fn:format-integer.)
The set of languages for which numbering is supported is implementation-defined. If the $language argument is absent, or is set to an empty sequence, or is invalid, or is not a language supported by the implementation, then the number is formatted using the default language from the dynamic context. (See fn:format-integer.)
...either a or t, to indicate alphabetic or traditional numbering respectively, the default being implementation-defined. (See fn:format-integer.)
The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences. The interpretation of this string is implementation-defined. No error occurs if the implementation does not define any interpretation for the defined string. (See fn:format-integer.)
It is implementation-defined what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead. (See fn:format-integer.)
The use of the a or t modifier disambiguates between numbering sequences that use letters. In many languages there are two commonly used numbering sequences that use letters. One numbering sequence assigns numeric values to letters in alphabetic sequence, and the other assigns numeric values to each letter in some other manner traditional in that language. In English, these would correspond to the numbering sequences specified by the format tokens a and i. In some languages, the first member of each sequence is the same, and so the format token alone would be ambiguous. In the absence of the a or t modifier, the default is implementation-defined. (See fn:format-integer.)
The static context provides a set of decimal formats. One of the decimal formats is unnamed, the others (if any) are identified by a QName. There is always an unnamed decimal format available, but its contents are implementation-defined. (See Defining a decimal format.)
IEEE states that the preferred quantum is language-defined. In this specification, it is implementation-defined. (See Trigonometric and exponential functions.)
IEEE defines various rounding algorithms for inexact results, and states that the choice of rounding direction, and the mechanisms for influencing this choice, are language-defined. In this specification, the rounding direction and any mechanisms for influencing it are implementation-defined. (See Trigonometric and exponential functions.)
The map returned by the fn:random-number-generator function may contain additional entries beyond those specified here, but it must match the record type defined above. The meaning of any additional entries is implementation-defined. To avoid conflict with any future version of this specification, the keys of any such entries should start with an underscore character. (See fn:random-number-generator.)
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. (See fn:codepoints-to-string.)
If two query parameters use the same keyword then the last one wins. If a query parameter uses a keyword or value which is not defined in this specification then the meaning is implementation-defined. If the implementation recognizes the meaning of the keyword and value then it should interpret it accordingly; if it does not recognize the keyword or value then if the fallback parameter is present with the value no it should reject the collation as unsupported, otherwise it should ignore the unrecognized parameter. (See The Unicode Collation Algorithm.)
The following query parameters are defined. If any parameter is absent, the default is implementation-defined except where otherwise stated. The meaning given for each parameter is non-normative; the normative specification is found in [UTS #35]. (See The Unicode Collation Algorithm.)
Because the set of collations that are supported is implementation-defined, an implementation has the option to support all collation URIs, in which case it will never raise this error. (See Choosing a collation.)
The properties available are as defined for the Unicode Collation Algorithm (see 5.3.4 The Unicode Collation Algorithm). Additional implementation-defined properties may be specified as described in the rules for UCA collation URIs. (See fn:collation.)
It is possible to define collations that do not have the ability to generate collation keys. Supplying such a collation will cause the function to fail. The ability to generate collation keys is an implementation-defined property of the collation. (See fn:collation-key.)
Conforming implementations must support normalization form NFC and may support normalization forms NFD, NFKC, NFKD, and FULLY-NORMALIZED. They may also support other normalization forms with implementation-defined semantics. (See fn:normalize-unicode.)
It is implementation-defined which version of Unicode (and therefore, of the normalization algorithms and their underlying data) is supported by the implementation. See [UAX #15] for details of the stability policy regarding changes to the normalization rules in future versions of Unicode. If the input string contains codepoints that are unassigned in the relevant version of Unicode, or for which no normalization rules are defined, the fn:normalize-unicode function leaves such codepoints unchanged. If the implementation supports the requested normalization form then it must be able to handle every input string without raising an error. (See fn:normalize-unicode.)
It is possible to define collations that do not have the ability to decompose a string into units suitable for substring matching. An argument to a function defined in this section may be a URI that identifies a collation that is able to compare two strings, but that does not have the capability to split the string into collation units. Such a collation may cause the function to fail, or to give unexpected results, or it may be rejected as an unsuitable argument. The ability to decompose strings into collation units is an implementation-defined property of the collation. The fn:collation-available function can be used to ask whether a particular collation has this property. (See Functions based on substring matching.)
The result of the function will always be such that validation against this schema would succeed. However, it is implementation-defined whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema. (See fn:analyze-string.)
Some URI schemes are hierarchical and some are non-hierarchical. Implementations must treat the following schemes as non-hierarchical: jar, mailto, news, tag, tel, and urn. Whether additional schemes are known to be non-hierarchical implementation-defined. If a scheme is not known to be non-hierarchical, it must be treated as hierarchical. (See Parsing and building URIs.)
If the omit-default-ports option is true, the port is discarded and set to the empty sequence if the port number is the same as the default port for the given scheme. Implementations should recognize the default ports for http (80), https (443), ftp (21), and ssh (22). Exactly which ports are recognized is implementation-defined. (See fn:parse-uri.)
If the omit-default-ports option is true then the $port is set to the empty sequence if the port number is the same as the default port for the given scheme. Implementations should recognize the default ports for http (80), https (443), ftp (21), and ssh (22). Exactly which ports are recognized is implementation-defined. (See fn:build-uri.)
Processors may support a greater range and/or precision. The limits are implementation-defined. (See Limits and precision.)
Similarly, a processor may be unable accurately to represent the result of dividing a duration by 2, or multiplying a duration by 0.5. A processor that limits the precision of the seconds component of duration values must deliver a result that is as close as possible to the mathematically precise result, given these limits; if two values are equally close, the one that is chosen is implementation-defined. (See Limits and precision.)
All conforming processors must support year values in the range 1 to 9999, and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, 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 0 and years with negative values. The results of operations on dates that cross the year 0 are implementation-defined. (See Limits and precision.)
Similarly, a processor that limits the precision of the seconds component of date and time or duration values may need to deliver a rounded result for arithmetic operations. Such a processor must deliver a result that is as close as possible to the mathematically precise result, given these limits: if two values are equally close, the one that is chosen is implementation-defined. (See Limits and precision.)
...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. (See The picture string.)
...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. (See The picture string.)
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. (See Formatting Fractional Seconds.)
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.89.9.4.8 The language, calendar, and place arguments. (See Formatting Other Components.)
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. (See The language, calendar, and place arguments.)
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. (See The language, calendar, and place arguments.)
The choice of the names and abbreviations used in any given language for calendar units such as days of the week and months of the year is implementation-defined. (See The language, calendar, and place arguments.)
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. (See The language, calendar, and place arguments.)
At least one of the above calendars must be supported. It is implementation-defined which calendars are supported. (See The language, calendar, and place arguments.)
If the arguments to fn:function-lookup identify a function that is present in the static context of the function call, the function will always return the same function that a static reference to this function would bind to. If there is no such function in the static context, then the results depend on what is present in the dynamic context, which is implementation-defined. (See fn:function-lookup.)
It is to some extent implementation-defined whether two maps or arrays have the same function identity. Processors should ensure as a minimum that when a variable $m is bound to a map or array, calling jtree($m) more than once (with the same variable reference) will deliver the same JNode each time. (See fn:jtree.)
The requirement to deliver a deterministic result has performance implications, and for this reason implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call of the function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:doc.)
Various aspects of this processing are implementation-defined. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:... (See fn:doc.)
It is implementation-defined whether DTD validation and/or schema validation is applied to the source document. (See fn:doc.)
The effect of a fragment identifier in the supplied URI is implementation-defined. One possible interpretation is to treat the fragment identifier as an ID attribute value, and to return a document node having the element with the selected ID value as its only child. (See fn:doc.)
By default, this function is deterministic. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:collection.)
By default, this function is deterministic. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:uri-collection.)
It is no longer automatically an error if the resource (after decoding) contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. (See fn:unparsed-text.)
UTF-8, or a value that results from implementation-defined heuristics. (See fn:unparsed-text.)
The fact that the resolution of URIs is defined by a mapping in the dynamic context means that in effect, various aspects of the behavior of this function are implementation-defined. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:... (See fn:unparsed-text.)
The fact that the resolution of URIs is defined by a mapping in the dynamic context means that in effect, various aspects of the behavior of this function are implementation-defined. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:... (See fn:unparsed-binary.)
The collation used for matching names is implementation-defined, but must be the same as the collation used to ensure that the names of all environment variables are unique. (See fn:environment-variable.)
Except to the extent defined by these options, the precise process used to construct the XDM instance is implementation-defined. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used. (See fn:parse-xml.)
Options set in $options may be supplemented or modified based on configuration options defined externally using implementation-defined mechanisms. (See fn:parse-xml.)
Except as explicitly defined, the precise process used to construct the XDM instance is implementation-defined. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used. (See fn:parse-xml-fragment.)
If the second argument is omitted, or is supplied in the form of an output:serialization-parameters element, then the values of any serialization parameters that are not explicitly specified is implementation-defined, and may depend on the context. (See fn:serialize.)
A list of target namespaces identifying schema components to be used for validation. The way in which the processor locates schema components for the specified target namespaces is implementation-defined. A zero-length string denotes a no-namespace schema.... (See fn:xsd-validator.)
Set to the decimal value 1.0 or 1.1 to indicate which version of XSD is to be used. The default is implementation-defined. A processor may use a later version of XSD than the version requested, but must not use an earlier version.... (See fn:xsd-validator.)
The XSD specification allows a schema to be used for validation even when it contains unresolved references to absent schema components. It is implementation-defined whether this function allows the schema to be incomplete in this way. For example, some processors might allow validation using a schema in which an element declaration contains a reference to a type declaration that is not present in the schema, provided that the element declaration is never needed in the course of a particular validation episode. (See fn:xsd-validator.)
...error-details as map(*)*. This field is present only when (a) the option return-error-details was set to true, and (b) the supplied document was found to be invalid. The value is a sequence of maps, each containing details of one invalidity that was found. The precise details of the invalidities are implementation-defined, but they may include the following fields, if the information is available:... (See fn:xsd-validator.)
Because the [DOM: Living Standard] and [HTML: Living Standard] are not fixed, it is implementation-defined which versions are used. (See XDM Mapping from HTML DOM Nodes.)
If an implementation allows these nodes to be passed in via an API or similar mechanism, their behaviour is implementation-defined. (See XDM Mapping from HTML DOM Nodes.)
If the local name contains a character that is not a valid XML NameStartChar or NameChar, then an implementation-defined replacement string is used. The result must be a valid NCName. (See node-name Accessor.)
If the local name contains a character that is not a valid XML NameStartChar or NameChar, then an implementation-defined replacement string is used. The result must be a valid NCName. (See node-name Accessor.)
The input may contain deviations from the grammar of [RFC 7159], which are handled in an implementation-defined way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised [err:FOJS0001] if the input does not conform to the grammar. (See fn:parse-json.)
The supplied function is called to process the string value of any JSON number in the input. By default, numbers are processed by converting to xs:double using the XPath casting rules. Supplying the value xs:decimal#1 will instead convert to xs:decimal (which potentially retains more precision, but disallows exponential notation), while supplying a function that casts to (xs:decimal | xs:double) will treat the value as xs:decimal if there is no exponent, or as xs:double otherwise. Supplying the value fn:identity#1 causes the value to be retained unchanged as an xs:untypedAtomic. If the liberal option is false (the default), then the supplied number-parser is called if and only if the value conforms to the JSON grammar for numbers (for example, a leading plus sign and redundant leading zeroes are not allowed). If the liberal option is true then it is also called if the value conforms to an implementation-defined extension of this grammar. (See fn:parse-json.)
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. (See fn:json-doc.)
The input may contain deviations from the grammar of [RFC 7159], which are handled in an implementation-defined way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised (see below) if the input does not conform to the grammar. (See fn:json-to-xml.)
Default: Implementation-defined. (See fn:json-to-xml.)
Indicates that the resulting XDM instance must be typed; that is, the element and attribute nodes must carry the type annotations that result from validation against the schema given at D.2 Schema for the result of fn:json-to-xml, or against an implementation-defined schema if the liberal option has the value true. (See fn:json-to-xml.)
The result of the function will always be such that validation against this schema would succeed. However, it is implementation-defined whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema. (See fn:csv-to-xml.)
Additional, implementation-defined options may be available, for example, to control aspects of the XML serialization, to specify the grammar start symbol, or to produce output formats other than XML. (See fn:invisible-xml.)
Default: The version given in the prolog of the library module; or implementation-defined if this is absent. (See fn:load-xquery-module.)
A sequence of URIs (in the form of xs:string values) which may be used or ignored in an implementation-defined way.... (See fn:load-xquery-module.)
Values for vendor-defined configuration options for the XQuery processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XQuery processor. The meaning of the associated value is implementation-defined. Implementations should ignore options whose names are in an unrecognized namespace. The option parameter conventions do not apply to this contained map.... (See fn:load-xquery-module.)
It is implementation-defined whether constructs in the library module are evaluated in the same execution scope as the calling module. (See fn:load-xquery-module.)
The library module that is loaded may import schema declarations using an import schema declaration. It is implementation-defined whether schema components in the in-scope schema definitions of the calling module are automatically added to the in-scope schema definitions of the dynamically loaded module. The in-scope schema definitions of the calling and called modules must be consistent, according to the rules defined in 2.2.5 Consistency Constraints ^XQ31. (See fn:load-xquery-module.)
The serialized result is written to persistent storage. This means that the fn:transform function has side-effects and becomes nondeterministic, so the option should be used with care, and the precise behavior may be implementation-defined. When this option is used, the URIs used for the base-output-uri and the URIs of any secondary result documents must be writable locations. (See fn:transform.)
Indicates whether any xsl:message instructions in the stylesheet are to be evaluated. The destination and formatting of any such messages is implementation-defined. (See fn:transform.)
Default: Implementation-defined. (See fn:transform.)
Default: Implementation-defined. (See fn:transform.)
If the implementation provides a way of writing or invoking functions with side-effects, this post-processing function might be used to save a copy of the result document to persistent storage. For example, if the implementation provides access to the EXPath File library [EXPath], then a serialized document might be written to filestore by calling the file:write function. Similar mechanisms might be used to issue an HTTP POST request that posts the result to an HTTP server, or to send the document to an email recipient. The semantics of calling functions with side-effects are entirely implementation-defined. (See fn:transform.)
Calls to fn:transform can potentially have side-effects even in the absence of the post-processing option, because the XSLT specification allows a stylesheet to invoke extension functions that have side-effects. The semantics in this case are implementation-defined. (See fn:transform.)
A string intended to be used as the static base URI of the principal stylesheet module. This value must be used if no other static base URI is available. If the supplied stylesheet already has a base URI (which will generally be the case if the stylesheet is supplied using stylesheet-node or stylesheet-location) then it is implementation-defined whether this parameter has any effect. If the value is a relative reference, it is resolved against the executable base URI^XP of the fn:transform function call.... (See fn:transform.)
Values for vendor-defined configuration options for the XSLT processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XSLT processor. The meaning of the associated value is implementation-defined. Implementations should ignore options whose names are in an unrecognized namespace. Default is an empty map.... (See fn:transform.)
It is implementation-defined whether the XSLT transformation is executed within the same execution scope as the calling code. (See fn:transform.)
XSLT 1.0 does not define any error codes, so this is the likely outcome with an XSLT 1.0 processor. XSLT 2.0 and 3.0 do define error codes, but some APIs do not expose them. If multiple errors are signaled by the transformation (which is most likely to happen with static errors) then the error code should where possible be that of one of these errors, chosen arbitrarily; the processor may make details of additional errors available to the application in an implementation-defined way. (See fn:transform.)
In addition, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an implementation-defined destination. (See fn:trace.)
Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, $v is an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will return $v. The processor may output "124.84" and "the value of $v is:" to an implementation-defined destination. (See fn:trace.)
Similar to fn:trace, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an implementation-defined destination. (See fn:message.)
If ST is xs:float or xs:double, then TV is the xs:decimal value, within the set of xs:decimal values that the implementation is capable of representing, that is numerically closest to SV. If two values are equally close, then the one that is closest to zero is chosen. If SV is too large to be accommodated as an xs:decimal, (see [XML Schema Part 2: Datatypes Second Edition] for implementation-defined limits on numeric values) a dynamic error is raised [err:FOCA0001]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002]. (See Casting to xs:decimal.)
In casting to xs:decimal or to a type derived from xs:decimal, if the value is not too large or too small but nevertheless cannot be represented accurately with the number of decimal digits available to the implementation, the implementation may round to the nearest representable value or may raise a dynamic error [err:FOCA0006]. The choice of rounding algorithm and the choice between rounding and error behavior is implementation-defined. (See Casting from xs:string and xs:untypedAtomic.)
If ST is xs:decimal, xs:float or xs:double, then TV is SV with the fractional part discarded and the value converted to xs:integer. Thus, casting 3.1456 returns 3 while -17.89 returns -17. Casting 3.124E1 returns 31. If SV is too large to be accommodated as an integer, (see [XML Schema Part 2: Datatypes Second Edition] for implementation-defined limits on numeric values) a dynamic error is raised [err:FOCA0003]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002]. (See Casting to xs:integer.)
The tz timezone database, available at http://www.iana.org/time-zones. It is implementation-defined which version of the database is used. (See IANA Timezone Database.)
Unicode Standard Annex #15: Unicode Normalization Forms. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 16.0.0, dated 2024-08-14. As with [The Unicode Standard], the version to be used is implementation-defined. Available at: http://www.unicode.org/reports/tr15/. (See UAX #15.)
Unicode Standard Annex #29: Unicode Text Segmentation. Ed. Josh Hadley, Unicode Consortium. The current version is 16.0.0, dated 2024-08-28. As with [The Unicode Standard], the version to be used is implementation-defined. Available at: http://www.unicode.org/reports/tr29/. (See UAX #29.)
The Unicode Consortium, Reading, MA, Addison-Wesley, 2016. The Unicode Standard as updated from time to time by the publication of new versions. See http://www.unicode.org/standard/versions/ for the latest version and additional information on versions of the standard and of the Unicode Character Database. The version of Unicode to be used is implementation-defined, but implementations are recommended to use the latest Unicode version; currently, Version 9.0.0. (See The Unicode Standard.)
Unicode Technical Standard #10: Unicode Collation Algorithm. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 16.0.0, dated 2024-08-22. As with [The Unicode Standard], the version to be used is implementation-defined. Available at: http://www.unicode.org/reports/tr10/. (See UTS #10.)
Unicode Technical Standard #35: Unicode Locale Data Markup Language. Ed Mark Davis et al, Unicode Consortium. The current version is 47, dated 2025-03-11. As with [The Unicode Standard], the version to be used is implementation-defined. Available at: http://www.unicode.org/reports/tr35/. (See UTS #35.)

H Changes since 3.1 (Non-Normative)

H.1 Summary of Changes

If a section of this specification has been updated since version 3.1, an overview of the changes is provided, along with links to navigate to the next or previous change.
See 1 Introduction
Sections with significant changes are marked with a ✭ symbol in the table of contents. New functions are indicated by ✚.
See 1 Introduction
PR 1504 2329
New in 4.0
See 2.1.7 fn:insert-separator
New in 4.0
See 2.1.10 fn:replicate
New in 4.0
See 2.1.12 fn:slice
PR 1120 1150
A callback function can be supplied for comparing individual items.
See 2.2.4 fn:deep-equal
Changed in 4.0 to use transitive equality comparisons for numeric values.
See 2.2.5 fn:distinct-values
PR 614 987
New in 4.0
See 2.2.6 fn:duplicate-values
New in 4.0. Originally proposed under the name fn:uniform
See 2.4.2 fn:all-equal
New in 4.0. Originally proposed under the name fn:unique
See 2.4.3 fn:all-different
New in 4.0
See 2.5.3 fn:every
New in 4.0
See 2.5.9 fn:highest
New in 4.0
See 2.5.10 fn:index-where
New in 4.0
See 2.5.11 fn:lowest
New in 4.0
See 2.5.15 fn:scan-right
New in 4.0
See 2.5.16 fn:some
PR 795 2228
New in 4.0
See 2.5.19 fn:sort-with
PR 521 761
New in 4.0
See 2.5.22 fn:transitive-closure
New in 4.0
See 4.4.5 fn:is-NaN
PR 1260 1275
A third argument has been added, providing control over the rounding mode.
See 4.4.6 fn:round
PR 1049 1151
Decimal format parameters can now be supplied directly as a map in the third argument, rather than referencing a format defined in the static context.
See 4.7.2 fn:format-number
PR 1205 1230
New in 4.0
See 4.8.2 math:e
See 4.8.8 math:cosh
See 4.8.15 math:sinh
See 4.8.18 math:tanh
The 3.1 specification suggested that every value in the result range should have the same chance of being chosen. This has been corrected to say that the distribution should be arithmetically uniform (because there are as many xs:double values between 0.01 and 0.1 as there are between 0.1 and 1.0).
See 4.9.2 fn:random-number-generator
PR 261 306 993
New in 4.0
See 5.4.1 fn:char
New in 4.0
See 5.4.2 fn:characters
PR 937 995 1190
New in 4.0
See 5.4.13 fn:hash
PR 215 415
New in 4.0
See 7.6.2 fn:parse-uri
PR 1423 1413
New in 4.0
See 7.6.3 fn:build-uri
New in 4.0
See 9.4.2 fn:build-dateTime
New in 4.0
See 9.4.2 fn:build-dateTime
New in 4.0
See 9.6.16 fn:parts-of-dateTime
New in 4.0
See 9.6.16 fn:parts-of-dateTime
New in 4.0
See 12.2.2 fn:in-scope-namespaces
PR 1620 1886
Options are added to customize the form of the output.
See 12.2.9 fn:path
PR 1547 1551
New in 4.0
See 12.2.11 fn:siblings
PR 969 1134
New in 4.0
See 14.4.6 map:filter
PR 478 515
New in 4.0
See 14.4.12 map:keys-where
PR 1575 1906
A new function fn:element-to-map is provided for converting XDM trees to maps suitable for serialization as JSON. Unlike the fn:xml-to-json function retained from 3.1, this can handle arbitrary XML as input.
See 14.5 Converting elements to maps
New in 4.0
See 15.2.3 array:empty
PR 968 1295
New in 4.0
See 15.2.13 array:index-of
PR 476 1087
New in 4.0
See 15.2.16 array:items
PR 360 476
New in 4.0
See 15.2.18 array:members
See 15.2.19 array:of-members
Supplying an empty sequence as the value of an optional argument is equivalent to omitting the argument.
See 15.2.29 array:subarray
PR 1117 1279
The $options parameter has been added.
See 17.1.6 fn:unparsed-text-lines
PR 259 956
A new function is available for processing input data in HTML format.
See 17.3 Functions on HTML Data
New in 4.0
See 17.3.2 fn:parse-html
PR 975 1058 1246
An option is provided to control how JSON numbers should be formatted.
See 17.4.4 fn:parse-json
Additional options are available, as defined by fn:parse-json.
See 17.4.5 fn:json-doc
PR 533 719 834 1066
New in 4.0
See 17.5.4 fn:csv-to-arrays
See 17.5.7 fn:parse-csv
PR 533 719 834 1066 1605
New in 4.0
See 17.5.10 fn:csv-to-xml
PR 791 1256 1282 1405
New in 4.0
See 17.6.1 fn:invisible-xml
PR 629 803
New in 4.0
See 21.2.2 fn:message
PR 533 719 834
New functions are available for processing input data in CSV (comma separated values) format.
See 17.5 Functions on CSV Data
Comparison of mixed numeric types (for example xs:double and xs:decimal) now generally converts both values to xs:decimal.
See 4.3 Comparing numeric values
PR 289 1901
A third argument is added, allowing user control of how absent keys should be handled.
See 14.4.9 map:get
A third argument is added, allowing user control of how index-out-of-bounds conditions should be handled.
See 15.2.11 array:get
A new collation URI is defined for Unicode case-insensitive comparison and ordering.
See 5.3.5 The Unicode case-insensitive collation
PR 1727 1740
It is no longer guaranteed that the new key replaces the existing key.
See 14.4.14 map:put
The group may remove this function, it is considered at risk.
See 15.2.18 array:members
See 15.2.19 array:of-members
PR 173
New in 4.0
See 18.4 fn:op
PR 203
New in 4.0
See 14.4.1 map:build
PR 207
New in 4.0
See 10.1.2 fn:parse-QName
See 10.2.5 fn:expanded-QName
PR 222
New in 4.0
See 2.2.3 fn:contains-subsequence
See 2.2.7 fn:ends-with-subsequence
See 2.2.9 fn:starts-with-subsequence
PR 250
New in 4.0
See 2.1.3 fn:foot
See 2.1.15 fn:trunk
See 15.2.2 array:build
See 15.2.8 array:foot
See 15.2.31 array:trunk
PR 258
New in 4.0
See 15.2.14 array:index-where
PR 313
The second argument can now be a sequence of integers.
See 2.1.9 fn:remove
PR 319
New in 4.0. The function replaces the internal op:same-key function in 3.1
See 2.2.1 fn:atomic-equal
PR 326
Higher-order functions are no longer an optional feature.
See 1.2 Conformance
PR 360
New in 4.0
See 14.4.4 map:entries
PR 419
New in 4.0
See 2.1.8 fn:items-at
PR 434
New in 4.0
See 4.5.2 fn:parse-integer
The function has been extended to allow output in a radix other than 10, for example in hexadecimal.
See 4.6.1 fn:format-integer
PR 477
New in 4.0
See 15.2.24 array:slice
PR 482
Deleted an inaccurate statement concerning the behavior of NaN.
See 4.3 Comparing numeric values
PR 507
New in 4.0
See 2.5.13 fn:partition
PR 546
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted.
See 5.2.1 fn:codepoints-to-string
It is no longer automatically an error if the resource (after decoding) contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted.
See 17.1.5 fn:unparsed-text
The rules regarding use of non-XML characters in JSON texts have been relaxed.
See 17.4.3 JSON character repertoire
See 17.4.4 fn:parse-json
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted.
See 17.4.5 fn:json-doc
PR 609
New in 4.0
See 15.2.28 array:split
PR 631
New in 4.0
See 7.1 fn:decode-from-uri
PR 662
Constructor functions now have a zero-arity form; the first argument defaults to the context item.
See 22 Constructor functions
PR 680
The case-insensitive collation is now defined normatively within this specification, rather than by reference to the HTML "living specification", which is subject to change. The collation can now be used for ordering comparisons as well as equality comparisons.
See 5.3.6 The HTML ASCII Case-Insensitive Collation
PR 702
The function can now take any number of arguments (previously it had to be two or more), and the arguments can be sequences of strings rather than single strings.
See 5.4.4 fn:concat
PR 710
Changes the function to return a sequence of key-value pairs rather than a map.
See 13.5 fn:function-annotations
PR 727
It has been clarified that loading a module has no effect on the static or dynamic context of the caller.
See 18.2 fn:load-xquery-module
PR 828
The $predicate callback function accepts an optional position argument.
See 2.5.4 fn:filter
The $action callback function accepts an optional position argument.
See 2.5.7 fn:for-each
See 2.5.8 fn:for-each-pair
The $predicate callback function now accepts an optional position argument.
See 15.2.4 array:filter
The $action callback function now accepts an optional position argument.
See 15.2.9 array:for-each
See 15.2.10 array:for-each-pair
PR 881
The way that fn:min and fn:max compare numeric values of different types has changed. The most noticeable effect is that when these functions are applied to a sequence of xs:integer or xs:decimal values, the result is an xs:integer or xs:decimal, rather than the result of converting this to an xs:float or xs:double.
See 2.4.5 fn:max
See 2.4.6 fn:min
PR 901
The optional third argument can now be supplied as an empty sequence.
See 2.1.13 fn:subsequence
The third argument can now be supplied as an empty sequence.
See 5.4.6 fn:substring
The second argument can now be an empty sequence.
See 6.3.3 fn:tokenize
The optional second argument can now be supplied as an empty sequence.
See 7.5 fn:resolve-uri
The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.
See 9.8.1 fn:format-dateTime9.9.1 fn:format-dateTime9.8.19.9.1 fn:format-dateTime
See 9.8.2 fn:format-date9.9.2 fn:format-date9.8.29.9.2 fn:format-date
See 9.8.3 fn:format-time9.9.3 fn:format-time9.8.39.9.3 fn:format-time
All three arguments are now optional, and each argument can be set to an empty sequence. Previously if $description was supplied, it could not be empty.
See 21.1.1 fn:error
The $label argument can now be set to an empty sequence. Previously if $label was supplied, it could not be empty.
See 21.2.1 fn:trace
PR 905
The rule that multiple calls on fn:doc supplying the same absolute URI must return the same document node has been clarified; in particular the rule does not apply if the dynamic context for the two calls requires different processing of the documents (such as schema validation or whitespace stripping).
See 17.1.1 fn:doc
PR 909
The function has been expanded in scope to handle comparison of values other than strings.
See 2.2.2 fn:compare
PR 924
Rules have been added clarifying that users should not be allowed to change the schema for the fn namespace.
See D Schemas
PR 925
The decimal format name can now be supplied as a value of type xs:QName, as an alternative to supplying a lexical QName as an instance of xs:string.
See 4.7.2 fn:format-number
PR 932
The specification now prescribes a minimum precision and range for durations.
See 8.1.2 Limits and precision
PR 933
When comments and processing instructions are ignored, any text nodes either side of the comment or processing instruction are now merged prior to comparison.
See 2.2.4 fn:deep-equal
PR 940
New in 4.0
See 2.5.20 fn:subsequence-where
PR 953
Constructor functions for named record types have been introduced.
See 22.6 Constructor functions for named record types
PR 962
New in 4.0
See 2.5.2 fn:do-until
See 2.5.23 fn:while-do
PR 969
New in 4.0
See 14.4.3 map:empty
PR 984
New in 4.0
See 8.4.1 fn:seconds
PR 987
The order of results is now prescribed; it was previously implementation-dependent.
See 2.2.5 fn:distinct-values
PR 1022
Regular expressions can include comments (starting and ending with #) if the c flag is set.
See 6.1 Regular expression syntax
See 6.2 Flags
PR 1028
An option is provided to control how the JSON null value should be handled.
See 17.4.4 fn:parse-json
PR 1032
New in 4.0
See 2.1.17 fn:void
PR 1046
New in 4.0
See 2.5.21 fn:take-while
PR 1059
Use of an option keyword that is not defined in the specification and is not known to the implementation now results in a dynamic error; previously it was ignored.
See 1.7 Options
PR 1068
New in 4.0
See 5.4.3 fn:graphemes
PR 1072
The return type is now specified more precisely.
See 18.2 fn:load-xquery-module
PR 1090
When casting from a string to a duration or time or dateTime, it is now specified that when there are more digits in the fractional seconds than the implementation is able to retain, excess digits are truncated. Rounding upwards (which could affect the number of minutes or hours in the value) is not permitted.
See 23.2 Casting from xs:string and xs:untypedAtomic
PR 1093
New in 4.0
See 5.3.9 fn:collation
PR 1117
The $options parameter has been added.
See 17.1.5 fn:unparsed-text
See 17.1.7 fn:unparsed-text-available
PR 1182
The $predicate callback function may return an empty sequence (meaning false).
See 2.5.2 fn:do-until
See 2.5.3 fn:every
See 2.5.4 fn:filter
See 2.5.10 fn:index-where
See 2.5.16 fn:some
See 2.5.21 fn:take-while
See 2.5.23 fn:while-do
See 14.4.6 map:filter
See 14.4.12 map:keys-where
See 15.2.4 array:filter
See 15.2.14 array:index-where
PR 1191
The $options parameter has been added, absorbing the $collation parameter.
See 2.2.4 fn:deep-equal
New in 4.0
See 12.3.1 fn:distinct-ordered-nodes
PR 1250
For selected properties including percent and exponent-separator, it is now possible to specify a single-character marker to be used in the picture string, together with a multi-character rendition to be used in the formatted output.
See 4.7.2 fn:format-number
PR 1257
The $options parameter has been added.
See 17.2.1 fn:parse-xml
See 17.2.2 fn:parse-xml-fragment
PR 1262
New in 4.0
See 5.3.10 fn:collation-available
PR 1265
The constraints on the result of the function have been relaxed.
See 12.1.2 fn:document-uri
PR 1280
As a result of changes to the coercion rules, the number of supplied arguments can be greater than the number required: extra arguments are ignored.
See 2.5.1 fn:apply
PR 1288
Additional error conditions have been defined.
See 17.2.1 fn:parse-xml
PR 1296
New in 4.0
See 2.5.14 fn:scan-left
PR 1333
A new option is provided to allow the content of the loaded module to be supplied as a string.
See 18.2 fn:load-xquery-module
PR 1353
An option has been added to suppress the escaping of the solidus (forwards slash) character.
See 17.4.7 fn:xml-to-json
PR 1358
New in 4.0
See 9.3.2 fn:unix-dateTime9.4.3 fn:unix-dateTime9.3.29.4.3 fn:unix-dateTime
PR 1361
The term atomic value has been replaced by atomic item.
See 1.9 Terminology
PR 1393
Changes the function to return a sequence of key-value pairs rather than a map.
See 13.5 fn:function-annotations
PR 1409
This section now uses the term primitive type strictly to refer to the 20 atomic types that are not derived by restriction from another atomic type: that is, the 19 primitive atomic types defined in XSD, plus xs:untypedAtomic. The three types xs:integer, xs:dayTimeDuration, and xs:yearMonthDuration, which have custom casting rules but are not strictly-speaking primitive, are now handled in other subsections.
See 23.1 Casting from primitive types to primitive types
The rules for conversion of dates and times to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since these deliver exactly the same result as the XPath 3.1 rules.
See 23.1.2.2 Casting date/time values to xs:string
The rules for conversion of durations to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since the XSD 1.1 rules deliver exactly the same result as the XPath 3.1 rules.
See 23.1.2.3 Casting xs:duration values to xs:string
PR 1455
Numbers now retain their original lexical form, except for any changes needed to satisfy JSON syntax rules (for example, stripping leading zero digits).
See 17.4.7 fn:xml-to-json
PR 1473
New in 4.0
See 2.1.5 fn:identity
PR 1481
The function has been extended to handle other Gregorian types such as xs:gYearMonth.
See 9.5.1 fn:year-from-dateTime9.6.1 fn:year-from-dateTime9.5.19.6.1 fn:year-from-dateTime
See 9.5.2 fn:month-from-dateTime9.6.2 fn:month-from-dateTime9.5.29.6.2 fn:month-from-dateTime
The function has been extended to handle other Gregorian types such as xs:gMonthDay.
See 9.5.3 fn:day-from-dateTime9.6.3 fn:day-from-dateTime9.5.39.6.3 fn:day-from-dateTime
The function has been extended to handle other types including xs:time.
See 9.5.4 fn:hours-from-dateTime9.6.4 fn:hours-from-dateTime9.5.49.6.4 fn:hours-from-dateTime
See 9.5.5 fn:minutes-from-dateTime9.6.5 fn:minutes-from-dateTime9.5.59.6.5 fn:minutes-from-dateTime
The function has been extended to handle other types such as xs:gYearMonth.
See 9.5.7 fn:timezone-from-dateTime9.6.7 fn:timezone-from-dateTime9.5.79.6.7 fn:timezone-from-dateTime
PR 1523
New functions are provided to obtain information about built-in types and types defined in an imported schema.
See 19 Processing types
New in 4.0
See 19.1.2 fn:schema-type
See 19.1.4 fn:atomic-type-annotation
See 19.1.5 fn:node-type-annotation
PR 1545
New in 4.0
See 9.6.4 fn:civil-timezone9.7.4 fn:civil-timezone9.6.49.7.4 fn:civil-timezone
PR 1565
The default for the escape option has been changed to false. The 3.1 specification gave the default value as true, but this appears to have been an error, since it was inconsistent with examples given in the specification and with tests in the test suite.
See 17.4.4 fn:parse-json
PR 1570
New in 4.0
See 19.1.3 fn:type-of
PR 1587
New in 4.0
See 17.1.8 fn:unparsed-binary
PR 1611
The spec has been corrected to note that the function depends on the implicit timezone.
See 2.2.2 fn:compare
PR 1671
New in 4.0.
See 4.4.3 fn:divide-decimals
PR 1687
New in 4.0
See 14.4.10 map:items
PR 1703
Ordered maps are introduced.
See 14.1 Ordering of Maps
Enhanced to allow for ordered maps.
See 14.4.6 map:filter
See 14.4.7 map:find
See 14.4.8 map:for-each
See 14.4.14 map:put
See 14.4.15 map:remove
The order of entries in maps is retained.
See 17.4.4 fn:parse-json
PR 1711
It is explicitly stated that the limits for $precision are implementation-defined.
See 4.4.6 fn:round
See 4.4.7 fn:round-half-to-even
PR 1727
For consistency with the new function map:build, the handling of duplicates may now be controlled by supplying a user-defined callback function as an alternative to the fixed values for the earlier duplicates option.
See 14.4.13 map:merge
PR 1734
In 3.1, given a mixed input sequence such as (1, 3, 4.2e0), the specification was unclear whether it was permitted to add the first two integer items using integer arithmetic, rather than converting all items to doubles before performing any arithmetic. The 4.0 specification is clear that this is permitted; but since the items can be reordered before being added, this is not required.
See 2.4.4 fn:avg
See 2.4.7 fn:sum
PR 1825
New in 4.0
See 2.5.12 fn:partial-apply
PR 1856
Word boundaries can be matched. Lookahead and lookbehind assertions are supported. Assertions (including ^ and $) can no longer be followed by a quantifier.
See 6.1 Regular expression syntax
The output of the function is extended to allow the represention of captured groups found within lookahead assertions.
See 6.3.4 fn:analyze-string
PR 1879
Additional options to control DTD and XInclude processing have been added.
See 17.2.1 fn:parse-xml
PR 1897
The $replacement argument can now be a function that computes the replacement strings.
See 6.3.2 fn:replace
PR 1906
New in 4.0
See 14.5.10 fn:element-to-map-plan
New in 4.0.
See 14.5.11 fn:element-to-map
PR 1910
An $options parameter is added. Note that the rules for the $options parameter control aspects of processing that were implementation-defined in earlier versions of this specification. An implementation may provide configuration options designed to retain backwards-compatible behavior when no explicit options are supplied.
See 17.1.1 fn:doc
See 17.1.2 fn:doc-available
PR 1913
It is now permitted for the regular expression to match a zero-length string.
See 6.3.2 fn:replace
See 6.3.3 fn:tokenize
See 6.3.4 fn:analyze-string
PR 1933
New in 4.0
See 17.2.5 fn:xsd-validator
PR 1991
Named record types used in the signatures of built-in functions are now available as standard in the static context.
See C Built-in named record types
PR 2001
New in 4.0.
See 2.5.18 fn:sort-by
See 15.2.26 array:sort-by
PR 2013
Support for binary input has been added.
See 17.2.1 fn:parse-xml
See 17.2.2 fn:parse-xml-fragment
New in 4.0
See 17.3.3 fn:html-doc
See 17.5.8 fn:csv-doc
PR 2030
This description of the XSD validation process was previously found (with some duplication) in the XQuery and XSLT specifications; those specifications now reference this description. As a side-effects, the descriptions of the process in XQuery and XSLT are better aligned.
See 17.2.4 XSD validation
PR 2031
Introduced the concept of JNodes.
See 16 Processing JNodes
New in 4.0
See 16.1.1 fn:jtree
See 16.1.3 fn:jnode-selector
See 16.1.4 fn:jnode-position
PR 2149
Generalized to work with JNodes as well as XNodes.
See 12.2.1 fn:has-children
The function is extended to handle JNodes.
See 12.2.9 fn:path
Generalized to work with JNodes as well as XNodes.
See 12.3.2 fn:innermost
See 12.3.3 fn:outermost
PR 2168
Atomic items of types xs:hexBinary and xs:base64Binary are now mutually comparable. In rare cases, where an application uses both types and assumes they are distinct, this can represent a backwards incompatibility.
See 2.2.1 fn:atomic-equal
See 2.2.4 fn:deep-equal
See 2.2.5 fn:distinct-values
PR 2223
An error may now be raised if the base URI is not a valid LEIRI reference.
See 12.1.1 fn:base-uri
PR 2224
The $action callback function now accepts an optional position argument.
See 14.4.6 map:filter
See 14.4.8 map:for-each
PR 2228
New in 4.0
See 15.2.27 array:sort-with
PR 2249
The specification now describes in more detail how to determine the effective encoding value.
See 17.1.5 fn:unparsed-text
PR 2256
In the interests of consistency, the index-of function now defines equality to mean contextually equal. This has the implication that NaN is now considered equal to NaN.
See 2.2.8 fn:index-of
PR 2259
A new parameter canonical is available to give control over serialization of XML, XHTML, and JSON.
See 17.2.3 fn:serialize
PR 2286
The type of $value has been generalized to xs:anyAtomicType?.
See 5.4.7 fn:string-length
See 5.4.8 fn:normalize-space
PR 2387
It is now recommended that out-of-range xs:double values should translate to positive or negative infinity.
See 17.4.4 fn:parse-json

XPath and XQuery Functions and Operators 4.0

W3C Editor's Draft 2 February12 March 2026

Abstract

Status of this Document

Dedication

8 Processing durations

8.4 Constructing durations

8.4.1 fn:seconds

8.5 Arithmetic operators on durations

8.5.3 op:multiply-yearMonthDuration

8.5.4 op:divide-yearMonthDuration

9 Processing dates and times

9.1 Date and time types

9.1.1 Limits and precision

9.3 Record fn:dateTime-record

9.39.4 Constructing a dateTime

9.3.19.4.1 fn:dateTime

9.4.2 fn:build-dateTime

9.3.29.4.3 fn:unix-dateTime

9.49.5 Comparing date and time values

9.59.6 Extracting components of dates and times

9.5.19.6.1 fn:year-from-dateTime

9.5.29.6.2 fn:month-from-dateTime

9.5.39.6.3 fn:day-from-dateTime

9.5.49.6.4 fn:hours-from-dateTime

9.5.59.6.5 fn:minutes-from-dateTime

9.5.69.6.6 fn:seconds-from-dateTime

9.5.79.6.7 fn:timezone-from-dateTime

9.5.89.6.8 fn:year-from-date

9.5.99.6.9 fn:month-from-date

9.5.109.6.10 fn:day-from-date

9.5.119.6.11 fn:timezone-from-date

9.5.129.6.12 fn:hours-from-time

9.5.139.6.13 fn:minutes-from-time

9.5.149.6.14 fn:seconds-from-time

9.5.159.6.15 fn:timezone-from-time

9.6.16 fn:parts-of-dateTime

9.69.7 Adjusting timezones on dates and times

9.6.19.7.1 fn:adjust-dateTime-to-timezone

9.6.29.7.2 fn:adjust-date-to-timezone

9.6.39.7.3 fn:adjust-time-to-timezone

9.6.49.7.4 fn:civil-timezone

9.79.8 Arithmetic operators on durations, dates and times

9.7.19.8.1 Limits and precision

9.7.29.8.2 op:subtract-dateTimes

9.7.39.8.3 op:subtract-dates

9.7.49.8.4 op:subtract-times

9.7.59.8.5 op:add-yearMonthDuration-to-dateTime

9.7.69.8.6 op:add-dayTimeDuration-to-dateTime

9.7.79.8.7 op:subtract-yearMonthDuration-from-dateTime

9.7.89.8.8 op:subtract-dayTimeDuration-from-dateTime

9.7.99.8.9 op:add-yearMonthDuration-to-date

9.7.109.8.10 op:add-dayTimeDuration-to-date

9.7.119.8.11 op:subtract-yearMonthDuration-from-date

9.7.129.8.12 op:subtract-dayTimeDuration-from-date

9.7.139.8.13 op:add-dayTimeDuration-to-time

9.7.149.8.14 op:subtract-dayTimeDuration-from-time

9.89.9 Formatting dates and times

9.8.19.9.1 fn:format-dateTime

9.8.29.9.2 fn:format-date

9.8.39.9.3 fn:format-time

9.8.49.9.4 The date/time formatting functions

9.8.4.19.9.4.1 The picture string

9.8.4.29.9.4.2 The Width Modifier

9.8.4.39.9.4.3 Formatting Integer-Valued Date/Time Components

9.8.4.49.9.4.4 Formatting the Year Component

9.8.4.59.9.4.5 Formatting Fractional Seconds

9.8.4.69.9.4.6 Formatting timezones

9.8.4.79.9.4.7 Formatting Other Components

9.8.4.89.9.4.8 The language, calendar, and place arguments

9.8.59.9.5 Examples of date and time formatting

9.99.10 Parsing dates and times

9.9.19.10.1 fn:parse-ietf-date

18 Dynamic evaluation

18.1 Record fn:load-xquery-module-record

B Error codes

C Built-in named record types

G Implementation-defined features (Non-Normative)

H Changes since 3.1 (Non-Normative)

H.1 Summary of Changes