Although the formatting rules are expressed in terms of the rules
for format tokens in fn:format-integer
, the formats actually used may be specialized
to the numbering of date components where appropriate. For example, in Italian, it
is conventional to
use an ordinal number (primo
) for the first day of the month, and cardinal numbers
(due, tre, quattro ...
) for the remaining days. A processor may therefore use
this convention to number days of the month, ignoring the presence or absence of the
ordinal
presentation modifier.
Whether or not a presentation modifier is included, a width modifier may be supplied. This indicates the number of characters to be included in the representation of the value.
The width modifier, if present, is introduced by a comma. It takes the form:
"," min-width ("-" max-width)?
where min-width
is either an unsigned integer indicating the minimum number of characters to
be output, or *
indicating that there is no explicit minimum, and
max-width
is either an unsigned integer indicating the maximum number of characters to
be output, or *
indicating that there is no explicit maximum; if max-width
is omitted then *
is assumed.
A dynamic error ([err:FOFD1340]) is raised if
min-width
is present and less than one, or if
max-width
is present and less than one or less than min-width
.
A format token containing more than one digit, such as 001
or 9999
, sets the
minimum and maximum width to the number of digits appearing in the format token; if
a width
modifier is also present, then the width modifier takes precedence.
The rules in this section apply to the majority of integer-valued components: specifically
M D d F W w H h m s
.
In the rules below, the term decimal digit pattern has the meaning given in 4.6.1 fn:format-integer.
If the first presentation modifier takes the form of a decimal digit pattern:
If there is no width modifier, then the value is formatted according to
the rules of the format-integer
function.
If there is a width modifier, then the first presentation modifier is adjusted as follows:
If the decimal digit pattern includes a grouping separator, the output is implementation-defined (but this is not an error).
Note:
Use of a width modifier together with grouping separators is inadvisable for this reason. It is never necessary to use a width modifier with a decimal digit pattern, since the same effect can be achieved by use of optional digit signs.
Otherwise, the number of mandatory-digit-sign characters in the presentation modifier is increased if necessary. This is done first by replacing optional-digit-signs with mandatory-digit-signs, starting from the right, and then prepending mandatory-digit-signs to the presentation modifier, until the number of mandatory-digit-signs is equal to the minimum width. Any mandatory-digit-signs that are added by this process must use the same decimal digit family as existing mandatory-digit-signs in the presentation modifier if there are any, or ASCII digits otherwise.
The maximum width, if specified, is ignored.
The output is then as defined using the format-integer
function with this adjusted decimal digit pattern.
If the first presentation modifiers is one of N
, n
, or Nn
:
Let FN be the full name of the component, that is, the form of the name that would be used in the absence of any width modifier.
If FN is shorter than the minimum width, then it is padded by appending spaces to the end of the name.
If FN is longer than the maximum width, then it is abbreviated, either by choosing a conventional abbreviation that fits within the maximum width (for example, "Wednesday" might be abbreviated to "Weds"), or by removing characters from the end of FN until it fits within the maximum width.
For other presentation modifiers:
Any adjustment of the value to fit within the requested width range is implementation-defined.
The value should not be truncated if this results in output that will not be meaningful to users (for example, there is no sensible way to truncate Roman numerals).
If shorter than the minimum width, the value should be padded to the minimum width, either by appending spaces, or in some other way appropriate to the numbering scheme.
The rules for the year component (Y) are the same as those in <IP_ADDRESS> Formatting Integer-Valued Date/Time Components, except that the value of the year as output is the value of the year component of the supplied value modulo ten to the power N where N is determined as follows:
If the width modifier is present and defines a finite maximum width, then that maximum width.
Otherwise, if the first presentation modifier takes the form of a decimal-digit-pattern, then:
Let W be the number of optional-digit-signs and mandatory-digit-signs in that decimal-digit-pattern.
If W is 2 or more, then W.
Otherwise, N is infinity (that is, the year is output in full).
The output for the fractional seconds component (f
) is equivalent to the result of the following algorithm:
If the first presentation modifier contains no Unicode digit, then the output is implementation-defined.
Otherwise, the value of the fractional seconds is output as follows:
If there is no width modifier and the first presentation modifier comprises in its
entirety a single mandatory-digit-sign (for example the default
1
), then
the presentation modifier is extended on the right with as many
optional-digit-signs as
are needed to accommodate the actual fractional seconds precision
encountered in the
value to be formatted.
If there is a width modifier, then the first presentation modifier is adjusted as follows:
If a minimum width is specified, and if this exceeds the number of mandatory-digit-sign characters in the first presentation modifier, then the first presentation modifier is adjusted. This is done first by replacing optional-digit-signs with mandatory-digit-signs, starting from the left, and then appending mandatory-digit-signs to the presentation modifier, until the number of mandatory-digit-signs is equal to the minimum width. Any mandatory-digit-signs that are added by this process must use the same decimal digit family as existing mandatory-digit-signs in the presentation modifier.
If a maximum width is specified, the first presentation modifier is extended on the right with as many optional-digit-signs as are needed to ensure that the number of mandatory-digit-signs and optional-digit-signs is at least equal to the maximum width.
The sequence of characters in the (adjusted) first presentation modifier is reversed
(for example,
999'###
becomes ###'999
).
If the result is not a valid decimal digit pattern, then the output is
·implementation-defined·.
The sequence of digits in the conventional decimal representation of the fractional
seconds component
is reversed, with insignificant zeroes removed, and the result
is treated as an integer. For example, if the
seconds value is 25.8235
, the reversed fractional seconds value is 5328
.
The reversed fractional seconds value is formatted using the reversed decimal digit
pattern according to the
rules of the fn:format-integer
function. Given the examples above, the result is 5'328
The resulting string is reversed. In our example, the result is 823'5
.
If the result contains more digits than the number of mandatory-digit-signs and optional-digit-signs in the decimal digit pattern, then excess digits are removed from the right hand end (that is, the value is truncated towards zero rather than being rounded). Any grouping separator that immediately precedes a removed digit is also removed.
Note:
The reason for presenting the algorithm in this way is that it enables maximum re-use
of the rules defined for
fn:format-integer
. Since the fractional seconds value is not properly an integer, the rules do not
work if used directly: for example, the positions of grouping separators
need to be counted from the left rather
than from the right. Implementations, as always, are free to use a different
algorithm that yields the same result.
Note:
A format token consisting of a single digit,
such as 1
, does not constrain the number of digits in the output.
In the case of fractional seconds in particular, [f001]
requests three decimal digits,
[f01]
requests two digits, but [f1]
will retain all digits in the
supplied date/time value (the maximum number of digits is implementation-defined).
If exactly one digit is required, this can be achieved using the component
specifier
[f1,1-1]
.
Special rules apply to the formatting of timezones. When the component specifiers
Z
or z
are used, the rules in this section override any rules given elsewhere in the case
of
discrepancies.
If the date/time value to be formatted does not include a timezone offset, then the timezone component specifier is generally ignored (results in no output). The exception is where military timezones are used (format ZZ) in which case the string "J" is output, indicating local time.
When the component specifier is z
, the output is the same as for component specifier
Z
, except that it is prefixed by the characters GMT
or some localized
equivalent. The prefix is omitted, however, in cases where the timezone is
identified by name rather than by
a numeric offset from UTC.
If the first presentation modifier is numeric and comprises one or two digits
with no grouping-separator (for example 1
or 01
), then the timezone is formatted as a displacement from UTC in hours, preceded by
a plus or minus
sign: for example -5
or +03
. If the actual timezone offset is not an integral number of hours,
then the minutes part of the offset is appended, separated by a colon: for
example +10:30
or
-1:15
.
If the first presentation modifier is numeric with a grouping-separator (for example 1:01
or 01.01
), then the timezone offset is output in hours and minutes, separated by the grouping
separator,
even if the number of minutes is zero: for example +5:00
or +10.30
.
If the first presentation modifier is numeric and comprises three or four digits with no
grouping-separator, for example 001
or 0001
, then the timezone offset
is shown in hours and minutes with no separator, for example -0500
or +1030
.
If the first presentation modifier is numeric, in any of the above formats, and the second
presentation modifier is t
, then a zero timezone offset (that is, UTC) is output as Z
instead
of a signed numeric value. In this presentation modifier is absent or if the
timezone offset is non-zero,
then the displayed timezone offset is preceded by a "-" sign for negative
offsets
or a "+" sign for non-negative offsets.
If the first presentation modifier is Z
, then the timezone is formatted
as a military timezone letter, using the convention Z = +00:00, A = +01:00,
B = +02:00, ..., M = +12:00,
N = -01:00, O = -02:00, ... Y = -12:00. The letter J (meaning local time)
is used in the case of a
value that does not specify a timezone offset. Timezone offsets that have
no representation in this system
(for example Indian Standard Time, +05:30) are output as if the format
01:01
had been requested.
If the first presentation modifier is N
, then the timezone is output
(where possible) as a timezone name, for example EST
or CET
. The same timezone
offset has different names in different places; it is therefore recommended that this option
should be used only if a country code (see [ISO 3166-1]) or IANA timezone name (see [IANA Timezone Database]) is supplied in the $place
argument.
In the absence of this information, the implementation may apply a default,
for example by using the timezone
names that are conventional in North America. If no timezone name can be identified,
the timezone offset is
output using the fallback format +01:01
.
The following examples illustrate options for timezone formatting.
| Variable marker | $place |
Timezone offsets (with time = 12:00:00) | ||||
|---|---|---|---|---|---|---|
| -10:00 | -05:00 | +00:00 | +05:30 | +13:00 | ||
| [Z] | () | -10:00 | -05:00 | +00:00 | +05:30 | +13:00 |
| [Z0] | () | -10 | -5 | +0 | +5:30 | +13 |
| [Z0:00] | () | -10:00 | -5:00 | +0:00 | +5:30 | +13:00 |
| [Z00:00] | () | -10:00 | -05:00 | +00:00 | +05:30 | +13:00 |
| [Z0000] | () | -1000 | -0500 | +0000 | +0530 | +1300 |
| [Z00:00t] | () | -10:00 | -05:00 | Z | +05:30 | +13:00 |
| [z] | () | GMT‑10:00 | GMT‑05:00 | GMT+00:00 | GMT+05:30 | GMT+13:00 |
| [ZZ] | () | W | R | Z | +05:30 | +13:00 |
| [ZN] | "us" | HST | EST | GMT | IST | +13:00 |
| [H00]:[M00] [ZN] | "America/New_York" | 06:00 EST | 12:00 EST | 07:00 EST | 01:30 EST | 18:00 EST |
If a width specifier is present when formatting a timezone, then the representation as defined in this section is padded to the minimum width as described in <IP_ADDRESS> The Width Modifier, but it is never shortened.
This section applies to the remaining components: P
(am/pm marker), C
(calendar),
and E
(era).
The output for these components is entirely ·implementation-defined·.
The default presentation modifier for these components is n
, indicating that they are output as names (or
conventional abbreviations), and the chosen names will in many cases depend
on the chosen language: see <IP_ADDRESS> The language, calendar, and place arguments.
The set of languages, calendars, and places that are supported in the ·date formatting functions· is ·implementation-defined·. When any of these arguments is omitted or is an empty sequence, an ·implementation-defined· default value is used.
If the fallback representation uses a different calendar from that requested,
the output string must identify the calendar actually used, for example by
prefixing the string with [Calendar: X]
(where X is the calendar actually used),
localized as appropriate to the
requested language. If the fallback representation uses a different language
from that requested, the output string must identify the language actually
used, for example by prefixing the string with [Language: Y]
(where Y is the language
actually used) localized in an
implementation-dependent way. If a particular component of the value cannot be output
in
the requested format, it should be output in the default format for
that component.
The $language
argument specifies the language to be used for the result string
of the function. The value of the argument should be either the empty sequence
or a value that would be valid for the xml:lang
attribute (see [XML]).
Note that this permits the identification of sublanguages
based on country codes (from [ISO 3166-1]) as well as identification of dialects
and of regions within a country.
If the $language
argument is omitted or is set to an empty sequence, or if it is set to an invalid
value or a
value that the implementation does not recognize,
then the processor uses the default language defined in the dynamic context.
The language is used to select the appropriate language-dependent forms of:
names (for example, of months)
numbers expressed as words or as ordinals (twenty, 20th, twentieth
)
hour convention (0-23 vs 1-24, 0-11 vs 1-12)
first day of week, first week of year
Where appropriate this choice may also take into account the value of the
$place
argument, though this should not be used to override the
language or any sublanguage that is specified as part of the language
argument.
The choice of the names and abbreviations used in any given language is
·implementation-defined·. For example,
one implementation might abbreviate July as Jul
while another uses Jly
. In German,
one implementation might represent Saturday as Samstag
while another
uses Sonnabend
. Implementations may provide mechanisms allowing users to
control such choices.
Where ordinal numbers are used, the selection of the correct representation of the ordinal (for example, the linguistic gender) may depend on the component being formatted and on its textual context in the picture string.
The calendar
attribute specifies that the dateTime
, date
,
or time
supplied in the $value
argument must be
converted to a value in the specified calendar and then converted to a string using
the
conventions of that calendar.
The calendar value if present must be a valid EQName
(dynamic error: [err:FOFD1340]).
If it is a lexical QName
then it is expanded into an expanded QName
using the statically known namespaces; if it has no prefix then it represents an expanded-QName
in no namespace.
If the expanded QName is in no namespace,
then it must identify a calendar with a designator specified below
(dynamic error: [err:FOFD1340]).
If the expanded QName is in a namespace then it identifies the calendar in an ·implementation-defined· way.
If the $calendar
argument is omitted or is set to an empty sequence
then the default calendar defined in the dynamic context is used.
Note:
The calendars listed below were known to be in use during the last hundred years. Many other calendars have been used in the past.
This specification does not define any of these calendars, nor the way that they
map to the value space of the xs:date
datatype in [XML Schema Part 2: Datatypes Second Edition].
There may be ambiguities when dates are recorded using different calendars.
For example, the start of a new day is not simultaneous in different calendars,
and may also vary geographically (for example, based on the time of sunrise or sunset).
Translation of dates is therefore more reliable when the time of day is also known,
and
when the geographic location is known.
When translating dates between
one calendar and another, the processor may take account of the values
of the $place
and/or $language
arguments, with the
$place
argument taking precedence.
Information about some of these calendars, and algorithms for converting between them, may be found in [Calendrical Calculations].
| Designator | Calendar |
|---|---|
| AD | Anno Domini (Christian Era) |
| AH | Anno Hegirae (Muhammedan Era) |
| AME | Mauludi Era (solar years since Mohammed's birth) |
| AM | Anno Mundi (Jewish Calendar) |
| AP | Anno Persici |
| AS | Aji Saka Era (Java) |
| BE | Buddhist Era |
| CB | Cooch Behar Era |
| CE | Common Era |
| CL | Chinese Lunar Era |
| CS | Chula Sakarat Era |
| EE | Ethiopian Era |
| FE | Fasli Era |
| ISO | ISO 8601 calendar |
| JE | Japanese Calendar |
| KE | Khalsa Era (Sikh calendar) |
| KY | Kali Yuga |
| ME | Malabar Era |
| MS | Monarchic Solar Era |
| NS | Nepal Samwat Era |
| OS | Old Style (Julian Calendar) |
| RS | Rattanakosin (Bangkok) Era |
| SE | Saka Era |
| SH | Mohammedan Solar Era (Iran) |
| SS | Saka Samvat |
| TE | Tripurabda Era |
| VE | Vikrama Era |
| VS | Vikrama Samvat Era |
At least one of the above calendars must be supported. It is ·implementation-defined· which calendars are supported.
The ISO 8601 calendar ([ISO 8601]),
which is included in the above list and designated ISO
,
is very similar to the Gregorian calendar designated AD
, but it
differs in several ways. The ISO calendar
is intended to ensure that date and time formats can be read
easily by other software, as well as being legible for human
users. The ISO calendar
prescribes the use of particular numbering conventions as defined in
ISO 8601, rather than allowing these to be localized on a per-language basis.
In particular it
provides a numeric 'week date' format which identifies dates by
year, week of the year, and day in the week;
in the ISO calendar the days of the week are numbered from 1 (Monday) to 7 (Sunday),
and
week 1 in any calendar year is the week (from Monday to Sunday) that includes the
first Thursday
of that year. The numeric values of the components year, month, day, hour, minute,
and second
are the same in the ISO calendar as the values used in the lexical representation
of the date and
time as defined in [XML Schema Part 2: Datatypes Second Edition]. The era ("E" component)
with this calendar is either a minus sign (for negative years) or a zero-length string
(for positive years).
For dates before 1 January, AD 1, year numbers in
the ISO and AD calendars are off by one from each other: ISO year
0000 is 1 BC, -0001 is 2 BC, etc.
ISO 8601 does not define a numbering for weeks within a month. When the w
component is used, the convention to be adopted is that each Monday-to-Sunday week
is considered to
fall within a particular month if its Thursday occurs in that month; the weeks that
fall in a particular
month under this definition are numbered starting from 1. Thus, for example,
29 January 2013 falls in week 5 because the Thursday of the week (31 January 2013)
is the fifth Thursday
in January, and 1 February 2013 is also in week 5 for the same reason.
Note:
The value space of the date and time datatypes, as defined in XML Schema, is based
on
absolute points in time. The lexical space of these datatypes defines a
representation of these absolute points in time using the proleptic Gregorian calendar,
that is, the modern Western calendar extrapolated into the past and the future; but
the value space
is calendar-neutral. The
·date formatting functions· produce a representation
of this absolute point in time, but denoted in a possibly different calendar. So,
for example, the date whose lexical representation in XML Schema is 1502-01-11
(the day on which Pope Gregory XIII was born) might be
formatted using the Old Style (Julian) calendar as 1 January 1502
. This reflects the fact
that there was at that time a ten-day difference between the two calendars. It would
be
incorrect, and would produce incorrect results, to represent this date in an element
or attribute
of type xs:date
as 1502-01-01
, even though this might reflect the way
the date was recorded in contemporary documents.
When referring to years occurring in antiquity, modern historians generally
use a numbering system in which there is no year zero (the year before 1 CE
is thus 1 BCE). This is the convention that should be used when the
requested calendar is OS (Julian) or AD (Gregorian). When the requested
calendar is ISO, however, the conventions of ISO 8601 should be followed:
here the year before +0001 is numbered zero. In [XML Schema Part 2: Datatypes Second Edition] (version 1.0),
the value space for xs:date
and xs:dateTime
does not include a year zero: however, XSD 1.1 endorses the ISO 8601 convention. This
means that the date on
which Julius Caesar was assassinated has the ISO 8601 lexical representation
-0043-03-13, but will be formatted as 15 March 44 BCE in the Julian calendar
or 13 March 44 BCE in the Gregorian calendar (dependant on the chosen
localization of the names of months and eras).
The intended use of the $place
argument is to identify
the place where an event
represented by the dateTime
, date
,
or time
supplied in the $value
argument took place or will take place.
If the $place
argument is omitted or is set
to an empty sequence, then the default place defined in the dynamic context is used.
If the value is supplied, and is not the empty sequence, then it should
either be a country code or an IANA timezone name.
If the value does not take this form, or if its value is not recognized
by the implementation, then the default place defined in the dynamic context is used.
Country codes are defined in [ISO 3166-1]. Examples are "de" for Germany and "jp" for Japan. Implementations may also allow the use of codes representing subdivisions of a country from ISO 3166-2, or codes representing formerly used names of countries from ISO 3166-3
IANA timezone names are defined in the IANA timezone database [IANA Timezone Database]. Examples are "America/New_York" and "Europe/Rome".
This argument is not intended to identify the location of the user
for whom the date or time is being formatted;
that should be done by means of the $language
attribute.
This information
may be used to provide additional information when converting dates between
calendars or when deciding how individual components of the date and time are to be
formatted.
For example, different countries using the Old Style (Julian) calendar started the
new year on different
days, and some countries used variants of the calendar that were out of synchronization
as a result of
differences in calculating leap years.
The geographical area identified by a country code is defined by the boundaries as they existed at the time of the date to be formatted, or the present-day boundaries for dates in the future.
If the $place
argument is supplied in the form
of an IANA timezone name that is recognized by the implementation, then the date or
time being formatted is adjusted to the timezone offset applicable in that timezone.
For example, if the xs:dateTime
value 2010-02-15T12:00:00Z
is formatted with the $place
argument set to
America/New_York
, then the output will be as if the value
2010-02-15T07:00:00-05:00
had been supplied. This adjustment takes daylight
savings time into account where possible; if the date in question falls during
daylight savings time in New York, then it is adjusted to timezone offset -PT4H
rather than -PT5H
. Adjustment using daylight savings time is only possible
where the value includes a date, and where the date is within the range covered
by the timezone database.
The following examples show a selection of dates and times and the way they might be formatted. These examples assume the use of the Gregorian calendar as the default calendar.
| Required Output | Expression |
|---|---|
2002-12-31
|
format-date($d, "[Y0001]-[M01]-[D01]")
|
12-31-2002
|
format-date($d, "[M]-[D]-[Y]")
|
31-12-2002
|
format-date($d, "[D]-[M]-[Y]")
|
31 XII 2002
|
format-date($d, "[D1] [MI] [Y]")
|
31st December, 2002
|
format-date($d, "[D1o] [MNn], [Y]", "en", (), ())
|
31 DEC 2002
|
format-date($d, "[D01] [MN,*-3] [Y0001]", "en", (), ())
|
December 31, 2002
|
format-date($d, "[MNn] [D], [Y]", "en", (), ())
|
31 Dezember, 2002
|
format-date($d, "[D] [MNn], [Y]", "de", (), ())
|
Tisdag 31 December 2002
|
format-date($d, "[FNn] [D] [MNn] [Y]", "sv", (), ())
|
[2002-12-31]
|
format-date($d, "[[[Y0001]-[M01]-[D01]]]")
|
Two Thousand and Three
|
format-date($d, "[YWw]", "en", (), ())
|
einunddreißigste Dezember
|
format-date($d, "[Dwo] [MNn]", "de", (), ())
|
3:58 PM
|
format-time($t, "[h]:[m01] [PN]", "en", (), ())
|
3:58:45 pm
|
format-time($t, "[h]:[m01]:[s01] [Pn]", "en", (), ())
|
3:58:45 PM PDT
|
format-time($t, "[h]:[m01]:[s01] [PN] [ZN,*-3]", "en", (), ())
|
3:58:45 o'clock PM PDT
|
format-time($t, "[h]:[m01]:[s01] o'clock [PN] [ZN,*-3]", "en", (), ())
|
15:58
|
format-time($t,"[H01]:[m01]")
|
15:58:45.762
|
format-time($t,"[H01]:[m01]:[s01].[f001]")
|
15:58:45 GMT+02:00
|
format-time($t,"[H01]:[m01]:[s01] [z,6-6]", "en", (), ())
|
15.58 Uhr GMT+2
|
format-time($t,"[H01]:[m01] Uhr [z]", "de", (), ())
|
3.58pm on Tuesday, 31st December
|
format-dateTime($dt, "[h].[m01][Pn] on [FNn], [D1o] [MNn]")
|
12/31/2002 at 15:58:45
|
format-dateTime($dt, "[M01]/[D01]/[Y0001] at [H01]:[m01]:[s01]")
|
The following examples use calendars other than the Gregorian calendar.
| Description | Request | Result |
|---|---|---|
| Islamic |
format-date($d, "[D١] [Mn] [Y١]", "ar", "AH", ())
|
٢٦ ﺸﻭّﺍﻝ ١٤٢٣ |
| Jewish (with Western numbering) |
format-date($d, "[D] [Mn] [Y]", "he", "AM", ())
|
26 טבת 5763 |
| Jewish (with traditional numbering) |
format-date($d, "[Dאt] [Mn] [Yאt]", "he", "AM", ())
|
כ״ו טבת תשס״ג |
| Julian (Old Style) |
format-date($d, "[D] [MNn] [Y]", "en", "OS", ())
|
18 December 2002 |
| Thai |
format-date($d, "[D๑] [Mn] [Y๑]", "th", "BE", ())
|
๓๑ ธันวาคม ๒๕๔๕ |
| Function | Meaning |
|---|---|
fn:parse-ietf-date |
Parses a string containing the date and time in IETF format, returning the corresponding
xs:dateTime value.
|
A function is provided to parse dates and times expressed using syntax that is commonly encountered in internet protocols.
Parses a string containing the date and time in IETF format, returning the corresponding
xs:dateTime
value.
fn:parse-ietf-date
($value
as
xs:string?
) as
xs:dateTime?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function accepts a string matching the production input
in the
following grammar:
input
|
::= |
S? (dayname ","? S)? ((datespec S time) | asctime) S?
|
dayname
|
::= |
"Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun" | "Monday | "Tuesday"
| "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"
|
datespec
|
::= |
daynum dsep monthname dsep year
|
asctime
|
::= |
monthname dsep daynum S time S year
|
dsep
|
::= |
S | (S? "-" S?)
|
daynum
|
::= |
digit digit?
|
year
|
::= |
digit digit (digit digit)?
|
digit
|
::= |
[0-9]
|
monthname
|
::= |
"Jan" | "Feb" | "Mar" | "Apr" | "May" | "Jun" | "Jul" | "Aug" | "Sep" |
"Oct" | "Nov" | "Dec"
|
time
|
::= |
hours ":" minutes (":" seconds)? (S? timezone)?
|
hours
|
::= |
digit digit?
|
minutes
|
::= |
digit digit
|
seconds
|
::= |
digit digit ("." digit+)?
|
timezone
|
::= |
tzname | tzoffset (S? "(" S? tzname S? ")")?
|
tzname
|
::= |
"UT" | "UTC" | "GMT" | "EST" | "EDT" | "CST" | "CDT" | "MST" | "MDT" | "PST"
| "PDT"
|
tzoffset
|
::= |
("+"|"-") hours ":"? minutes?
|
S
|
::= |
( x09 | x0A | x0D | x20 )+
|
The input is case-insensitive: upper-case and lower-case distinctions in the above grammar show the conventional usage, but otherwise have no significance.
If the input is an empty sequence, the result is an empty sequence.
The dayname
, if present, is ignored.
The daynum
, monthname
, and year
supply the day,
month, and year of the resulting xs:dateTime
value. A two-digit year
must have 1900 added to it. A year such as 0070 is to be treated
as given; negative years are not permitted.
The hours
, minutes
, and seconds
(including
fractional seconds) values supply the corresponding components of the resulting
xs:dateTime
value; if the seconds
value
or the fractional seconds value is absent then zero
is assumed.
If both a tzoffset
and a tzname
are supplied then the
tzname
is ignored.
If a tzoffset
is supplied then this defines the hours and minutes parts of the timezone offset:
If it contains a colon, this separates the hours part from the minutes part.
Otherwise, the grammar allows a sequence of from one to four digits. These are interpreted
as H
, HH
, HMM
, or HHMM
respectively, where H
or HH
is the hours part, and MM
(if present) is the minutes part.
00
.
If a tzname
is supplied with no tzoffset
then it is translated
to a timezone offset as follows:
| tzname | Offset |
|---|---|
| UT, UTC, GMT | 00:00 |
| EST | -05:00 |
| EDT | -04:00 |
| CST | -06:00 |
| CDT | -05:00 |
| MST | -07:00 |
| MDT | -06:00 |
| PST | -08:00 |
| PDT | -07:00 |
If neither a tzoffset
nor tzname
is supplied, a timezone
offset of 00:00
is assumed.
A dynamic error is raised [err:FORG0010] if the input does not match the grammar, or if the resulting date/time value is invalid (for example, 31 February).
The parse-ietf-date
function attempts to interpret its input as a date
in any of the three formats specified by HTTP [RFC 2616].
These formats are used widely on the Internet to represent timestamps, and were specified in:
asctime()
format
[RFC 2616] (HTTP) officially uses a subset of those three formats restricted to GMT.
The grammar for this function is slightly more liberal than the RFCs (reflecting the internet tradition of being liberal in what is accepted). For example the function:
Accepts a single-digit value where appropriate in place of a two-digit value with a leading zero (so "Wed 1 Jun" is acceptable in place of "Wed 01 Jun", and the timezone offset "-5:00" is equivalent to "-05:00")
Accepts one or more whitespace characters (x20, x09, x0A, x0D) wherever a single space is required, and allows whitespace to be omitted where it is not required for parsing
Accepts and ignores whitespace characters (x20, x09, x0A, x0D) at the start or end of the string.
In new protocols IETF recommends the format of [RFC 3339] which is based on a profile of ISO 8601 similar to that already used in XPath and XSD, but the "approximate" [RFC 822] format described here is very widely used.
An [RFC 1123] date can be generated approximately using fn:format-dateTime
with a picture
string of "[FNn3], [D01] [MNn3] [Y04] [H01]:[m01]:[s01] [Z0000]"
.
The expression fn:parse-ietf-date("Wed, 06 Jun 1994 07:29:35 GMT")
returns xs:dateTime("1994-06-06T07:29:35Z")
.
The expression fn:parse-ietf-date("Wed, 6 Jun 94 07:29:35 GMT")
returns xs:dateTime("1994-06-06T07:29:35Z")
.
The expression fn:parse-ietf-date("Wed Jun 06 11:54:45 EST 2013")
returns xs:dateTime("2013-06-06T11:54:45-05:00")
.
The expression fn:parse-ietf-date("Sunday, 06-Nov-94 08:49:37 GMT")
returns xs:dateTime("1994-11-06T08:49:37Z")
.
The expression fn:parse-ietf-date("Wed, 6 Jun 94 07:29:35 +0500")
returns xs:dateTime("1994-06-06T07:29:35+05:00")
.
In addition to the xs:QName
constructor function, QName values can
be constructed by combining a namespace URI, prefix, and local name, or by resolving
a lexical QName against the in-scope namespaces of an element node. This section
defines these functions.
Leading and trailing whitespace, if present, is stripped from
string arguments before the result is constructed.
| Function | Meaning |
|---|---|
fn:resolve-QName |
Returns an xs:QName value (that is, an expanded-QName) by taking an
xs:string that has the lexical form of an xs:QName (a
string in the form "prefix:local-name" or "local-name") and resolving it using the
in-scope namespaces for a given element.
|
fn:QName |
Returns an xs:QName value formed using a supplied namespace URI and lexical QName.
|
Returns an xs:QName
value (that is, an expanded-QName) by taking an
xs:string
that has the lexical form of an xs:QName
(a
string in the form "prefix:local-name" or "local-name") and resolving it using the
in-scope namespaces for a given element.
fn:resolve-QName
($qname
as
xs:string?
, $element
as
element()
) as
xs:QName?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $qname
is the empty sequence, returns the empty sequence.
More specifically, the function searches the namespace bindings of $element
for a binding whose name matches the prefix of $qname
, or the zero-length
string if it has no prefix, and returns an expanded-QName whose local name is taken
from the supplied $qname
, and whose namespace URI is taken from the string
value of the namespace binding.
If the $qname
has no prefix, and there is no namespace binding for
$element
corresponding to the default (unnamed) namespace, then the
resulting expanded-QName has no namespace part.
The prefix (or absence of a prefix) in the supplied $qname
argument is
retained in the returned expanded-QName, as described in Section
2.1 Terminology
DM31.
A dynamic error is raised [err:FOCA0002] if $qname
does
not have the correct lexical form for an instance of xs:QName
.
A dynamic error is raised [err:FONS0004] if $qname
has
a prefix and there is no namespace binding for $element
that matches this
prefix.
Sometimes the requirement is to construct an xs:QName
without using the
default namespace. This can be achieved by writing:
if (contains($qname, ":")) then fn:resolve-QName($qname, $element) else fn:QName("", $qname)
If the requirement is to construct an xs:QName
using the namespaces in the
static context, then the xs:QName
constructor should be used.
Assume that the element bound to $element
has a single namespace binding
bound to the prefix eg
.
fn:resolve-QName("hello", $element)
returns a QName with local name
"hello" that is in no namespace.
fn:resolve-QName("eg:myFunc", $element)
returns an xs:QName
whose namespace URI is specified by the namespace binding corresponding to the prefix
"eg" and whose local name is "myFunc".
Returns an xs:QName
value formed using a supplied namespace URI and lexical QName.
fn:QName
($paramURI
as
xs:string?
, $paramQName
as
xs:string
) as
xs:QName
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The namespace URI in the returned QName is taken from $paramURI
. If
$paramURI
is the zero-length string or the empty sequence, it represents
"no namespace".
The prefix (or absence of a prefix) in $paramQName
is retained in the
returned xs:QName
value.
The local name in the result is taken from the local part of
$paramQName
.
A dynamic error is raised [err:FOCA0002] if $paramQName
does not have the correct lexical form for an instance of xs:QName
.
A dynamic error is raised [err:FOCA0002] if $paramURI
is the zero-length string or the empty sequence, and the value of
$paramQName
contains a colon (:
).
A dynamic error may be raised [err:FOCA0002] if
$paramURI
is not a valid URI (XML Namespaces 1.0) or IRI (XML Namespaces
1.1).
fn:QName("http://www.example.com/example", "person")
returns an
xs:QName
with namespace URI = "http://www.example.com/example", local
name = "person" and prefix = "".
fn:QName("http://www.example.com/example", "ht:person")
returns an
xs:QName
with namespace URI = "http://www.example.com/example", local
name = "person" and prefix = "ht".
This section specifies functions on QNames as defined in [XML Schema Part 2: Datatypes Second Edition].
| Function | Meaning |
|---|---|
op:QName-equal |
Returns true if two supplied QNames have the same namespace URI and the
same local part.
|
fn:prefix-from-QName |
Returns the prefix component of the supplied QName. |
fn:local-name-from-QName |
Returns the local part of the supplied QName. |
fn:namespace-uri-from-QName |
Returns the namespace URI part of the supplied QName. |
fn:namespace-uri-for-prefix |
Returns the namespace URI of one of the in-scope namespaces for $element ,
identified by its namespace prefix.
|
fn:in-scope-prefixes |
Returns the prefixes of the in-scope namespaces for an element node. |
Returns true
if two supplied QNames have the same namespace URI and the
same local part.
Defines the semantics
of the "eq" and "ne" operators when applied to two values of type xs:QName
.
op:QName-equal
($arg1
as
xs:QName
, $arg2
as
xs:QName
) as
xs:boolean
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns true
if the namespace URIs of $arg1
and
$arg2
are equal and the local names of $arg1
and
$arg2
are equal.
Otherwise, the function returns false
.
The namespace URI parts are considered equal if they are both absentDM31, or if they are both present and equal under the rules
of the fn:codepoint-equal
function.
The local parts are also compared under the rules of the fn:codepoint-equal
function.
The prefix parts of $arg1
and $arg2
, if any, are ignored.
Returns the prefix component of the supplied QName.
fn:prefix-from-QName
($arg
as
xs:QName?
) as
xs:NCName?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $arg
is the empty sequence the function returns the empty sequence.
If $arg
has no prefix component the function returns the empty
sequence.
Otherwise, the function returns an xs:NCName
representing the prefix
component of $arg
.
Returns the local part of the supplied QName.
fn:local-name-from-QName
($arg
as
xs:QName?
) as
xs:NCName?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $arg
is the empty sequence the function returns the empty sequence.
Otherwise, the function returns an xs:NCName
representing the local part of
$arg
.
The expression fn:local-name-from-QName(fn:QName("http://www.example.com/example",
"person"))
returns "person"
.
Returns the namespace URI part of the supplied QName.
fn:namespace-uri-from-QName
($arg
as
xs:QName?
) as
xs:anyURI?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $arg
is the empty sequence the function returns the empty sequence.
Otherwise, the function returns an xs:anyURI
representing the namespace URI
part of $arg
.
If $arg
is in no namespace, the function returns the zero-length
xs:anyURI
.
The expression fn:namespace-uri-from-QName(fn:QName("http://www.example.com/example",
"person"))
returns xs:anyURI("http://www.example.com/example")
.
Returns the namespace URI of one of the in-scope namespaces for $element
,
identified by its namespace prefix.
fn:namespace-uri-for-prefix (
|
$prefix |
as xs:string? ,
|
$element |
as element() ) as xs:anyURI? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $element
has an in-scope namespace whose namespace prefix is equal to
$prefix
, the function returns the namespace URI of that namespace.
If $element
has no in-scope namespace whose namespace prefix is equal to
$prefix
, the function returns the empty sequence.
If $prefix
is the zero-length string or the empty sequence, then if
$element
has a default namespace (that is, a namespace node with no
name), the function returns the namespace URI of the default namespace. If
$element
has no default namespace, the function returns the empty
sequence.
Prefixes are equal only if their Unicode codepoints match exactly.
let $e := <z:a xmlns="http://example.org/one" xmlns:z="http://example.org/two"> <b xmlns=""/> </z:a>
The expression fn:namespace-uri-for-prefix("z", $e)
returns "http://example.org/two"
.
The expression fn:namespace-uri-for-prefix("", $e)
returns "http://example.org/one"
.
The expression fn:namespace-uri-for-prefix((), $e)
returns "http://example.org/one"
.
The expression fn:namespace-uri-for-prefix("xml", $e)
returns "http://www.w3.org/XML/1998/namespace"
.
The expression fn:namespace-uri-for-prefix("xml", $e)
returns "http://www.w3.org/XML/1998/namespace"
.
Returns the prefixes of the in-scope namespaces for an element node.
fn:in-scope-prefixes
($element
as
element()
) as
xs:string*
This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.
The function returns a sequence of strings representing the prefixes of the in-scope
namespaces for $element
.
For namespace bindings that have a prefix, the function returns the prefix as an
xs:NCName
. For the default namespace, which has no prefix, it returns
the zero-length string.
The result sequence contains no duplicates.
The ordering of the result sequence is ·implementation-dependent·.
The XML namespace is in scope for every element, so the result will always include the string "xml".
The following comparison operators on xs:base64Binary
and
xs:hexBinary
values are defined. Comparisons take two operands of
the same type; that is, both operands must be xs:base64Binary
or
both operands may be xs:hexBinary
. Each returns a boolean value.
A value of type xs:hexBinary
can be compared with a value of type
xs:base64Binary
by casting one value to the other type. See
19.1.6 Casting to xs:base64Binary and xs:hexBinary.
| Function | Meaning |
|---|---|
op:hexBinary-equal |
Returns true if two xs:hexBinary values contain the same octet
sequence.
|
op:hexBinary-less-than |
Returns true if the first argument is less than the second. |
op:hexBinary-greater-than |
Returns true if the first argument is greater than the second. |
op:base64Binary-equal |
Returns true if two xs:base64Binary values contain the same octet
sequence.
|
op:base64Binary-less-than |
Returns true if the first argument is less than the second. |
op:base64Binary-greater-than |
Returns true if the first argument is greater than the second. |
Returns true if two xs:hexBinary
values contain the same octet
sequence.
Defines the semantics of
the "eq" and "ne" operators when applied to two xs:hexBinary
values.
op:hexBinary-equal (
|
$value1 |
as xs:hexBinary ,
|
$value2 |
as xs:hexBinary ) as xs:boolean |
The function returns true
if $value1
and $value2
are of the same length, measured in binary octets, and contain the same octets in
the
same order. Otherwise, it returns false
.
Returns true if the first argument is less than the second.
Defines the semantics of
the "lt" operator when applied to two xs:hexBinary
values. Also used in the
definition of the "ge" operator.
op:hexBinary-less-than (
|
$arg1 |
as xs:hexBinary ,
|
$arg2 |
as xs:hexBinary ) as xs:boolean |
The function returns true
if any of the following conditions is true:
$arg1
is zero-length (contains no octets) and $arg2
is
not zero-length.
Neither argument is zero-length, and the first octet of $arg1
is less
than the first octet of $arg2
, treating the value of the octet as an
unsigned integer in the range 0 to 255.
Neither argument is zero-length, the first octet of $arg1
is equal to
the first octet of $arg2
, and the xs:hexBinary
value
formed by taking all octets of arg1
after the first is less than the
xs:hexBinary
value formed by taking all octets of
arg2
after the first.
Otherwise, the function returns false
.
Returns true if the first argument is greater than the second.
Defines the semantics of
the "gt" operator when applied to two xs:hexBinary
values. Also used in the
definition of the "le" operator.
op:hexBinary-greater-than (
|
$arg1 |
as xs:hexBinary ,
|
$arg2 |
as xs:hexBinary ) as xs:boolean |
The function call op:hexBinary-greater-than($A, $B)
is defined to return
the same result as op:hexBinary-less-than($B, $A)
Returns true if two xs:base64Binary
values contain the same octet
sequence.
Defines the semantics
of the "eq" and "ne" operators when applied to two xs:base64Binary
values.
op:base64Binary-equal (
|
$value1 |
as xs:base64Binary ,
|
$value2 |
as xs:base64Binary ) as xs:boolean |
The function returns true
if $value1
and $value2
are of the same length, measured in binary octets, and contain the same octets in
the
same order. Otherwise, it returns false
.
Returns true if the first argument is less than the second.
Defines the semantics
of the "lt" operator when applied to two xs:base64Binary
values. Also used in
the definition of the "ge" operator.
op:base64Binary-less-than (
|
$arg1 |
as xs:base64Binary ,
|
$arg2 |
as xs:base64Binary ) as xs:boolean |
The function returns true
if any of the following conditions is true:
$arg1
is zero-length (contains no octets) and $arg2
is
not zero-length.
Neither argument is zero-length, and the first octet of $arg1
is less
than the first octet of $arg2
, treating the value of the octet as an
unsigned integer in the range 0 to 255.
Neither argument is zero-length, the first octet of $arg1
is equal to
the first octet of $arg2
, and the xs:base64Binary
value
formed by taking all octets of arg1
after the first is less than the
xs:base64Binary
value formed by taking all octets of
arg2
after the first.
Otherwise, the function returns false
.
Returns true if the first argument is greater than the second.
Defines the semantics
of the "gt" operator when applied to two xs:base64Binary
values. Also used in
the definition of the "le" operator.
op:base64Binary-greater-than (
|
$arg1 |
as xs:base64Binary ,
|
$arg2 |
as xs:base64Binary ) as xs:boolean |
The function call op:base64Binary-greater-than($A, $B)
is defined to return
the same result as op:base64Binary-less-than($B, $A)
This section specifies operators that take xs:NOTATION
values as arguments.
| Function | Meaning |
|---|---|
op:NOTATION-equal |
Returns true if the two xs:NOTATION values have the same
namespace URI and the same local part.
|
Returns true
if the two xs:NOTATION
values have the same
namespace URI and the same local part.
Defines the
semantics of the "eq" and "ne" operators when applied to two values of type
xs:NOTATION
.
op:NOTATION-equal
($arg1
as
xs:NOTATION
, $arg2
as
xs:NOTATION
) as
xs:boolean
The function returns true
if the namespace URIs of $arg1
and
$arg2
are equal and the local names of $arg1
and
$arg2
are equal.
Otherwise, the function returns false
.
The namespace URI parts are considered equal if they are both absentDM31, or if they are both present and equal under the rules
of the fn:codepoint-equal
function.
The local parts are also compared under the rules of the fn:codepoint-equal
function.
The prefix parts of $arg1
and $arg2
, if any, are ignored.
This section specifies functions and operators on nodes. Nodes are formally defined in Section 6 Nodes DM31.
| Function | Meaning |
|---|---|
fn:name |
Returns the name of a node, as an xs:string that is either the zero-length
string, or has the lexical form of an xs:QName .
|
fn:local-name |
Returns the local part of the name of $arg as an xs:string
that is either the zero-length string, or has the lexical form of an
xs:NCName .
|
fn:namespace-uri |
Returns the namespace URI part of the name of $arg , as an
xs:anyURI value.
|
fn:lang |
This function tests whether the language of $node , or the context item if
the second argument is omitted, as specified by xml:lang attributes is the
same as, or is a sublanguage of, the language specified by $testlang .
|
fn:root |
Returns the root of the tree to which $arg belongs. This will usually, but
not necessarily, be a document node.
|
fn:path |
Returns a path expression that can be used to select the supplied node relative to the root of its containing document. |
fn:has-children |
Returns true if the supplied node has one or more child nodes (of any kind). |
fn:innermost |
Returns every node within the input sequence that is not an ancestor of another member of the input sequence; the nodes are returned in document order with duplicates eliminated. |
fn:outermost |
Returns every node within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated. |
For the illustrative examples below assume an XQuery or transformation operating on
a
PurchaseOrder
document containing a number of line-item
elements. Each line-item has
child elements called description
, price
, quantity
, etc. whose content is different
for each line-item
. Quantity has simple content of type xs:decimal
.
Further assume that variables $item1
, $item2
, etc. are
each bound to single line-item element nodes in the document in sequence and that
the value of the quantity child of the first line-item is 5.0
.
let $po := <PurchaseOrder> <line-item> <description>Large widget</description> <price>8.95</price> <quantity>5.0</quantity> </line-item> <line-item> <description>Small widget</description> <price>3.99</price> <quantity>2.0</quantity> </line-item> <line-item> <description>Tiny widget</description> <price>1.49</price> <quantity>805</quantity> </line-item> </PurchaseOrder>
let $item1 := $po/line-item[1]
let $item2 := $po/line-item[2]
let $item3 := $po/line-item[3]
Returns the name of a node, as an xs:string
that is either the zero-length
string, or has the lexical form of an xs:QName
.
fn:name
() as
xs:string
fn:name
($arg
as
node()?
) as
xs:string
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
). The
behavior of the function if the argument is omitted is exactly the same as if the
context item had been passed as the argument.
If the argument is supplied and is the empty sequence, the function returns the zero-length string.
If the node identified by $arg
has no name (that is, if it is a document
node, a comment, a text node, or a namespace node having no name), the function returns
the zero-length string.
Otherwise, the function returns the value of the expression
fn:string(fn:node-name($arg))
.
The following errors may be raised when $arg
is omitted:
If the context item is absentDM31, dynamic error [err:XPDY0002]XP31
If the context item is not a node, type error [err:XPTY0004]XP31.
Because the result depends on the choice of namespace prefixes in the source document,
it is not good practice to use the result of this function for anything other than
display
purposes. For example, the test name(.) = 'my:profile'
will fail if the source
document uses an unexpected namespace prefix. Such a test (assuming it relates to
an element node)
is better written as boolean(self::my:profile)
.
Returns the local part of the name of $arg
as an xs:string
that is either the zero-length string, or has the lexical form of an
xs:NCName
.
fn:local-name
() as
xs:string
fn:local-name
($arg
as
node()?
) as
xs:string
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
). The
behavior of the function if the argument is omitted is exactly the same as if the
context item had been passed as the argument.
If the argument is supplied and is the empty sequence, the function returns the zero-length string.
If the node identified by $arg
has no name (that is, if it is a document
node, a comment, a text node, or a namespace node having no name), the function returns
the zero-length string.
Otherwise, the function returns the local part of the expanded-QName of the node
identified by $arg
, as determined by the dm:node-name
accessor
defined in Section
5.10 node-name Accessor
DM31). This will be an
xs:string
whose lexical form is an xs:NCName
.
The following errors may be raised when $arg
is omitted:
If the context item is absentDM31, dynamic error [err:XPDY0002]XP31
If the context item is not a node, type error [err:XPTY0004]XP31.
Returns the namespace URI part of the name of $arg
, as an
xs:anyURI
value.
fn:namespace-uri
() as
xs:anyURI
fn:namespace-uri
($arg
as
node()?
) as
xs:anyURI
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context node (.
). The
behavior of the function if the argument is omitted is exactly the same as if the
context item had been passed as the argument.
If the node identified by $arg
is neither an element nor an attribute node,
or if it is an element or attribute node whose expanded-QName (as determined by the
dm:node-name
accessor in the Section
5.10 node-name Accessor
DM31)
is in no namespace, then the function returns the zero-length xs:anyURI
value.
Otherwise, the result will be the namespace URI part of the expanded-QName of the
node
identified by $arg
, as determined by the dm:node-name
accessor
defined in Section
5.10 node-name Accessor
DM31), returned as an
xs:anyURI
value.
The following errors may be raised when $arg
is omitted:
If the context item is absentDM31, dynamic error [err:XPDY0002]XP31
If the context item is not a node, type error [err:XPTY0004]XP31.
This function tests whether the language of $node
, or the context item if
the second argument is omitted, as specified by xml:lang
attributes is the
same as, or is a sublanguage of, the language specified by $testlang
.
fn:lang
($testlang
as
xs:string?
) as
xs:boolean
fn:lang
($testlang
as
xs:string?
, $node
as
node()
) as
xs:boolean
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The behavior of the function if the second argument is omitted is exactly the same
as if
the context item (.
) had been passed as the second argument.
The language of the argument $node
, or the context item if the second
argument is omitted, is determined by the value of the xml:lang
attribute
on the node, or, if the node has no such attribute, by the value of the
xml:lang
attribute on the nearest ancestor of the node that has an
xml:lang
attribute. If there is no such ancestor, then the function
returns false
.
If $testlang
is the empty sequence it is interpreted as the zero-length
string.
The relevant xml:lang
attribute is determined by the value of the XPath
expression:
(ancestor-or-self::*/@xml:lang)[last()]
If this expression returns an empty sequence, the function returns false
.
Otherwise, the function returns true
if and only if, based on a caseless
default match as specified in section 3.13 of [The Unicode Standard], either:
$testlang
is equal to the string-value of the relevant
xml:lang
attribute, or
$testlang
is equal to some substring of the string-value of the
relevant xml:lang
attribute that starts at the start of the
string-value and ends immediately before a hyphen, "-" (the character "-" is
HYPHEN-MINUS, #x002D).
The following errors may be raised when $arg
is omitted:
If the context item is absentDM31, dynamic error [err:XPDY0002]XP31
If the context item is not a node, type error [err:XPTY0004]XP31.
The expression fn:lang("en")
would return true
if the
context node were any of the following four elements:
<para xml:lang="en"/>
<div xml:lang="en"><para>And now, and
forever!</para></div>
<para xml:lang="EN"/>
<para xml:lang="en-us"/>
The expression fn:lang("fr")
would return false
if the
context node were <para xml:lang="EN"/>
Returns the root of the tree to which $arg
belongs. This will usually, but
not necessarily, be a document node.
fn:root
() as
node()
fn:root
($arg
as
node()?
) as
node()?
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the function is called without an argument, the context item (.
) is used
as the default argument. The behavior of the function if the argument is omitted is
exactly the same as if the context item had been passed as the argument.
The function returns the value of the expression
($arg/ancestor-or-self::node())[1]
.
The following errors may be raised when $arg
is omitted:
If the context item is absentDM31, dynamic error [err:XPDY0002]XP31
If the context item is not a node, type error [err:XPTY0004]XP31.
These examples use some variables which could be defined in [XQuery 3.1: An XML Query Language] as:
let $i := <tool>wrench</tool> let $o := <order> {$i} <quantity>5</quantity> </order> let $odoc := document {$o} let $newi := $o/tool
Or they could be defined in [XSL Transformations (XSLT) Version 3.0] as:
<xsl:variable name="i" as="element()"> <tool>wrench</tool> </xsl:variable> <xsl:variable name="o" as="element()"> <order> <xsl:copy-of select="$i"/> <quantity>5</quantity> </order> </xsl:variable> <xsl:variable name="odoc"> <xsl:copy-of select="$o"/> </xsl:variable> <xsl:variable name="newi" select="$o/tool"/>
fn:root($i)
returns the element node $i
fn:root($o/quantity)
returns the element node $o
fn:root($odoc//quantity)
returns the document node $odoc
fn:root($newi)
returns the element node $o
The final three examples could be made type-safe by wrapping their operands with
fn:exactly-one()
.
Returns a path expression that can be used to select the supplied node relative to the root of its containing document.
fn:path
() as
xs:string?
fn:path
($arg
as
node()?
) as
xs:string?
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The behavior of the function if the argument is omitted is exactly the same as if
the
context item (.
) had been passed as the argument.
If $arg
is the empty sequence, the function returns the empty sequence.
If $arg
is a document node, the function returns the string
"/"
.
Otherwise, the function returns a string that consists of a sequence of steps, one
for each ancestor-or-self of $arg
other than the root node. This string is
prefixed by "Q{http://www.w3.org/2005/xpath-functions}root()"
if the root
node is not a document node. Each step consists of the character "/"
followed by a string whose form depends on the kind of node selected by that step,
as
follows:
For an element node,
Q{uri}local[position]
,
where uri
is the namespace URI of the node name or the
empty string if the node is in no namespace, local
is
the local part of the node name, and position
is an
integer representing the position of the selected node among its like-named
siblings.
For an attribute node:
if the node is in no namespace, @local
, where
local
is the local part of the node name
otherwise, @Q{uri}local
, where
uri
is the namespace URI of the node name,
and local
is the local part of the node name
For a text node: text()[position]
where
position
is an integer representing the position
of the selected node among its text node siblings
For a comment node: comment()[position]
where
position
is an integer representing the position
of the selected node among its comment node siblings
For a processing-instruction node:
processing-instruction(local)[position]
where local
is the name of the processing instruction
node and position
is an integer representing the
position of the selected node among its like-named processing-instruction node
siblings
For a namespace node:
If the namespace node has a name:
namespace::prefix
, where
prefix
is the local part of the name of the
namespace node (which represents the namespace prefix).
If the namespace node has no name (that is, it represents the default
namespace):
namespace::*[Q{http://www.w3.org/2005/xpath-functions}local-name()=""]
The following errors may be raised when $arg
is omitted:
If the context item is absentDM31, dynamic error [err:XPDY0002]XP31
If the context item is not a node, type error [err:XPTY0004]XP31.
let $e := document { <p xmlns="http://example.com/one" xml:lang="de" author="Friedrich von Schiller"> Freude, schöner Götterfunken,<br/> Tochter aus Elysium,<br/> Wir betreten feuertrunken,<br/> Himmlische, dein Heiligtum.</p>}
The expression fn:path($e)
returns '/'
.
The expression fn:path($e/*:p)
returns '/Q{http://example.com/one}p[1]'
.
The expression fn:path($e/*:p/@xml:lang)
returns '/Q{http://example.com/one}p[1]/@Q{http://www.w3.org/XML/1998/namespace}lang'
.
The expression fn:path($e/*:p/@author)
returns '/Q{http://example.com/one}p[1]/@author'
.
The expression fn:path($e/*:p/*:br[2])
returns '/Q{http://example.com/one}p[1]/Q{http://example.com/one}br[2]'
.
The expression fn:path($e//text()[starts-with(normalize-space(),
'Tochter')])
returns '/Q{http://example.com/one}p[1]/text()[2]'
.
let $emp := <employee xml:id="ID21256"> <empnr>E21256</empnr> <first>John</first> <last>Brown</last> </employee>
The expression fn:path($emp)
returns 'Q{http://www.w3.org/2005/xpath-functions}root()'
.
The expression fn:path($emp/@xml:id)
returns 'Q{http://www.w3.org/2005/xpath-functions}root()/@Q{http://www.w3.org/XML/1998/namespace}id'
.
The expression fn:path($emp/empnr)
returns 'Q{http://www.w3.org/2005/xpath-functions}root()/Q{}empnr[1]'
.
Returns true if the supplied node has one or more child nodes (of any kind).
fn:has-children
() as
xs:boolean
fn:has-children
($node
as
node()?
) as
xs:boolean
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
). The
behavior of the function if the argument is omitted is exactly the same as if the
context item had been passed as the argument.
Provided that the supplied argument $node
matches the expected type
node()?
, the result of the function call
fn:has-children($node)
is defined to be the same as the result of the
expression fn:exists($node/child::node())
.
The following errors may be raised when $node
is omitted:
If the context item is absentDM31, dynamic error [err:XPDY0002]XP31
If the context item is not a node, type error [err:XPTY0004]XP31.
If $node
is an empty sequence the result is false.
The motivation for this function is to support streamed evaluation. According to the streaming rules in [XSL Transformations (XSLT) Version 3.0], the following construct is not streamable:
<xsl:if test="exists(row)"> <ul> <xsl:for-each select="row"> <li><xsl:value-of select="."/></li> </xsl:for-each> </ul> </xsl:if>
This is because it makes two downward selections to read the child row
elements. The use of fn:has-children
in the xsl:if
conditional
is intended to circumvent this restriction.
Although the function was introduced to support streaming use cases, it has general utility as a convenience function.
Returns every node within the input sequence that is not an ancestor of another member of the input sequence; the nodes are returned in document order with duplicates eliminated.
fn:innermost
($nodes
as
node()*
) as
node()*
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function call fn:innermost($nodes)
is defined to be
equivalent to the result of the expression:
$nodes except $nodes/ancestor::node()
That is, the function takes as input a sequence of nodes, and returns every node within the sequence that is not an ancestor of another node within the sequence; the nodes are returned in document order with duplicates eliminated.
If the source document contains nested sections represented by div
elements, the expression innermost(//div)
returns those div
elements that do not contain further div
elements.
Returns every node within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated.
fn:outermost
($nodes
as
node()*
) as
node()*
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function call fn:outermost($nodes)
is defined to be
equivalent to the result of the expression:
$nodes[not(ancestor::node() intersect $nodes)]/.
That is, the function takes as input a sequence of nodes, and returns every node within the sequence that does not have another node within the sequence as an ancestor; the nodes are returned in document order with duplicates eliminated.
The formulation $nodes except $nodes/descendant::node()
might appear to be
simpler, but does not correctly account for attribute nodes, as these are not
descendants of their parent element.
The motivation for the function was based on XSLT streaming use cases. There are cases
where the [XSL Transformations (XSLT) Version 3.0] streaming rules allow the construct
outermost(//section)
but do not allow //section
; the
function can therefore be useful in cases where it is known that sections will not
be
nested, as well as cases where the application actually wishes to process all sections
except those that are nested within another.
If the source document contains nested sections represented by div
elements, the expression outermost(//div)
returns those div
elements that are not contained within further div
elements.
A sequence
is an ordered collection of zero or more items
.
An item
is either a node or an atomic value. The terms
sequence
and item
are defined formally in [XQuery 3.1: An XML Query Language] and [XML Path Language (XPath) 3.1].
The following functions are defined on sequences. These functions work on any sequence, without performing any operations that are sensitive to the individual items in the sequence.
| Function | Meaning |
|---|---|
fn:empty |
Returns true if the argument is the empty sequence. |
fn:exists |
Returns true if the argument is a non-empty sequence. |
fn:head |
Returns the first item in a sequence. |
fn:tail |
Returns all but the first item in a sequence. |
fn:insert-before |
Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence. |
fn:remove |
Returns a new sequence containing all the items of $target except the item
at position $position .
|
fn:reverse |
Reverses the order of items in a sequence. |
fn:subsequence |
Returns the contiguous sequence of items in the value of $sourceSeq
beginning at the position indicated by the value of $startingLoc and
continuing for the number of items indicated by the value of $length .
|
fn:unordered |
Returns the items of $sourceSeq in an ·implementation-dependent· order.
|
As in the previous section, for the illustrative examples below, assume an XQuery
or transformation operating on a non-empty Purchase Order document containing a
number of line-item elements. The variable $seq
is bound to the
sequence of line-item nodes in document order. The variables
$item1
, $item2
, etc. are bound to separate, individual
line-item nodes in the sequence.
Returns true if the argument is the empty sequence.
fn:empty
($arg
as
item()*
) as
xs:boolean
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the value of $arg
is the empty sequence, the function returns
true
; otherwise, the function returns false
.
The expression fn:empty((1,2,3)[10])
returns true()
.
The expression fn:empty(fn:remove(("hello", "world"), 1))
returns false()
.
The expression fn:empty([])
returns false()
.
The expression fn:empty(map{})
returns false()
.
The expression fn:empty("")
returns false()
.
Assuming $in
is an element with no children:
let $break := <br/> return fn:empty($break)
The result is false()
.
Returns true if the argument is a non-empty sequence.
fn:exists
($arg
as
item()*
) as
xs:boolean
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the value of $arg
is a non-empty sequence, the function returns
true
; otherwise, the function returns false
.
The expression fn:exists(fn:remove(("hello"), 1))
returns false()
.
The expression fn:exists(fn:remove(("hello", "world"), 1))
returns true()
.
The expression fn:exists([])
returns true()
.
The expression fn:exists(map{})
returns true()
.
The expression fn:exists("")
returns true()
.
Assuming $in
is an element with no children:
let $break :=
return fn:exists($break)
The result is true()
.
Returns the first item in a sequence.
fn:head
($arg
as
item()*
) as
item()?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the value of the expression $arg[1]
If $arg
is the empty sequence, the empty sequence is returned. Otherwise
the first item in the sequence is returned.
The expression fn:head(1 to 5)
returns 1
.
The expression fn:head(("a", "b", "c"))
returns "a"
.
The expression fn:head(())
returns ()
.
The expression fn:head([1,2,3])
returns [1,2,3]
.
Returns all but the first item in a sequence.
fn:tail
($arg
as
item()*
) as
item()*
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the value of the expression subsequence($arg, 2)
If $arg
is the empty sequence, or a sequence containing a single item, then
the empty sequence is returned.
The expression fn:tail(1 to 5)
returns (2, 3, 4, 5)
.
The expression fn:tail(("a", "b", "c"))
returns ("b", "c")
.
The expression fn:tail("a")
returns ()
.
The expression fn:tail(())
returns ()
.
The expression fn:tail([1,2,3])
returns ()
.
Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence.
fn:insert-before (
|
$target |
as item()* ,
|
$position |
as xs:integer ,
|
|
$inserts |
as item()* ) as item()* |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The value returned by the function consists of all items of $target
whose
index is less than $position
, followed by all items of
$inserts
, followed by the remaining elements of $target
, in
that order.
If $target
is the empty sequence, $inserts
is returned. If
$inserts
is the empty sequence, $target
is returned.
If $position
is less than one (1), the first position, the effective value
of $position
is one (1). If $position
is greater than the
number of items in $target
, then the effective value of
$position
is equal to the number of items in $target
plus
1.
The value of $target
is not affected by the sequence construction.
let $abc := ("a", "b", "c")
The expression fn:insert-before($abc, 0, "z")
returns ("z", "a", "b", "c")
.
The expression fn:insert-before($abc, 1, "z")
returns ("z", "a", "b", "c")
.
The expression fn:insert-before($abc, 2, "z")
returns ("a", "z", "b", "c")
.
The expression fn:insert-before($abc, 3, "z")
returns ("a", "b", "z", "c")
.
The expression fn:insert-before($abc, 4, "z")
returns ("a", "b", "c", "z")
.
Returns a new sequence containing all the items of $target
except the item
at position $position
.
fn:remove
($target
as
item()*
, $position
as
xs:integer
) as
item()*
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a sequence consisting of all items of $target
whose
index is less than $position
, followed by all items of $target
whose index is greater than $position
.
If $position
is less than 1 or greater than the number of items in
$target
, $target
is returned.
If $target
is the empty sequence, the empty sequence is returned.
let $abc := ("a", "b", "c")
The expression fn:remove($abc, 0)
returns ("a", "b", "c")
.
The expression fn:remove($abc, 1)
returns ("b", "c")
.
The expression fn:remove($abc, 6)
returns ("a", "b", "c")
.
The expression fn:remove((), 3)
returns ()
.
Reverses the order of items in a sequence.
fn:reverse
($arg
as
item()*
) as
item()*
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a sequence containing the items in $arg
in reverse
order.
If $arg
is the empty sequence, the empty sequence is returned.
let $abc := ("a", "b", "c")
The expression fn:reverse($abc)
returns ("c", "b", "a")
.
The expression fn:reverse(("hello"))
returns ("hello")
.
The expression fn:reverse(())
returns ()
.
The expression fn:reverse([1,2,3])
returns [1,2,3]
. (The input is a sequence containing a single item (the array)).
The expression fn:reverse(([1,2,3],[4,5,6]))
returns ([4,5,6],[1,2,3])
.
Returns the contiguous sequence of items in the value of $sourceSeq
beginning at the position indicated by the value of $startingLoc
and
continuing for the number of items indicated by the value of $length
.
fn:subsequence
($sourceSeq
as
item()*
, $startingLoc
as
xs:double
) as
item()*
fn:subsequence (
|
$sourceSeq |
as item()* ,
|
$startingLoc |
as xs:double ,
|
|
$length |
as xs:double ) as item()* |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
In the two-argument case, returns:
$sourceSeq[fn:round($startingLoc) le position()]
In the three-argument case, returns:
$sourceSeq[fn:round($startingLoc) le position() and position() lt fn:round($startingLoc) + fn:round($length)]
The first item of a sequence is located at position 1, not position 0.
If $sourceSeq
is the empty sequence, the empty sequence is returned.
In the two-argument case, the function returns a sequence comprising those items of
$sourceSeq
whose index position (counting from one)
is greater than or equal to the value of $startingLoc
(rounded to an integer). No error occurs if $startingLoc
is
zero or negative.
In the three-argument case, The function returns a sequence comprising those items
of $sourceSeq
whose index position (counting from one)
is greater than or equal to the value of $startingLoc
(rounded to an integer), and
less than the sum of $startingLoc
and $length
(both rounded to integers). No error occurs if $startingLoc
is
zero or negative, or if $startingLoc
plus $length
exceeds the number of items in the sequence, or if
$length
is negative.
As a consequence of the general rules, if $startingLoc
is
-INF
and $length
is +INF
, then
fn:round($startingLoc) + fn:round($length)
is NaN
; since
position() lt NaN
is always false, the result is an empty sequence.
The reason the function accepts arguments of type xs:double
is that many
computations on untyped data return an xs:double
result; and the reason for
the rounding rules is to compensate for any imprecision in these floating-point
computations.
let $seq := ("item1", "item2", "item3", "item4", "item5")
The expression fn:subsequence($seq, 4)
returns ("item4", "item5")
.
The expression fn:subsequence($seq, 3, 2)
returns ("item3", "item4")
.
Returns the items of $sourceSeq
in an ·implementation-dependent· order.
fn:unordered
($sourceSeq
as
item()*
) as
item()*
This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.
The function returns the items of $sourceSeq
in an ·implementation-dependent· order.
Query optimizers may be able to do a better job if the order of the output sequence is not specified. For example, when retrieving prices from a purchase order, if an index exists on prices, it may be more efficient to return the prices in index order rather than in document order.
The expression fn:unordered((1, 2, 3, 4, 5))
returns some permutation of (1, 2, 3, 4, 5)
.
The functions in this section rely on comparisons between the items in one or more sequences.
| Function | Meaning |
|---|---|
fn:distinct-values |
Returns the values that appear in a sequence, with duplicates eliminated. |
fn:index-of |
Returns a sequence of positive integers giving the positions within the sequence
$seq of items that are equal to $search .
|
fn:deep-equal |
This function assesses whether two sequences are deep-equal to each other. To be deep-equal, they must contain items that are pairwise deep-equal; and for two items to be deep-equal, they must either be atomic values that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal, or maps with matching entries, or arrays with matching members. |
Returns the values that appear in a sequence, with duplicates eliminated.
fn:distinct-values
($arg
as
xs:anyAtomicType*
) as
xs:anyAtomicType*
fn:distinct-values (
|
$arg |
as xs:anyAtomicType* ,
|
$collation |
as xs:string ) as xs:anyAtomicType* |
The one-argument form of this function is ·nondeterministic-wrt-ordering·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The function returns the sequence that results from removing from $arg
all
but one of a set of values that are considered equal to one another.
Two items $J and $K in the input sequence
(after atomization, as required by the function signature)
are considered equal if fn:deep-equal($J, $K, $coll)
is true,
where $coll
is the collation selected according to the rules in 5.3.5 Choosing a collation. This collation is used when string comparison is
required.
The order in which the sequence of values is returned is ·implementation-dependent·.
Which value of a set of values that compare equal is returned is ·implementation-dependent·.
If the input sequence contains values of different numeric types that differ from
each
other by small amounts, then the eq operator is not transitive, because of rounding
effects occurring during type promotion. In the situation where the input contains
three
values A
, B
, and C
such that A eq B
,
B eq C
, but A ne C
, then the number of items in the result
of the function (as well as the choice of which items are returned) is ·implementation-dependent·, subject only to the constraints that (a) no two
items in the result sequence compare equal to each other, and (b) every input item
that
does not appear in the result sequence compares equal to some item that does appear
in
the result sequence.
For example, this arises when computing:
distinct-values( (xs:float('1.0'), xs:decimal('1.0000000000100000000001', xs:double( '1.00000000001'))
because the values of type xs:float
and xs:double
both compare
equal to the value of type xs:decimal
but not equal to each other.
If $arg
is the empty sequence, the function returns the empty sequence.
Values of type xs:untypedAtomic
are compared as if they were of type
xs:string
.
Values that cannot be compared, because the eq
operator is not defined for
their types, are considered to be distinct.
For xs:float
and xs:double
values, positive zero is equal to
negative zero and, although NaN
does not equal itself, if $arg
contains multiple NaN
values a single NaN
is returned.
If xs:dateTime
, xs:date
or xs:time
values do not
have a timezone, they are considered to have the implicit timezone provided by the
dynamic context for the purpose of comparison. Note that xs:dateTime
,
xs:date
or xs:time
values can compare equal even if their
timezones are different.
The expression fn:distinct-values((1, 2.0, 3, 2))
returns some permutation of (1, 3, 2.0)
. (The result may include either the xs:integer
2 or the xs:decimal
2.0).
The expression fn:distinct-values((xs:untypedAtomic("cherry"),
xs:untypedAtomic("plum"), xs:untypedAtomic("plum")))
returns some permutation of (xs:untypedAtomic("cherry"),
xs:untypedAtomic("plum"))
.
Returns a sequence of positive integers giving the positions within the sequence
$seq
of items that are equal to $search
.
fn:index-of (
|
$seq |
as xs:anyAtomicType* ,
|
$search |
as xs:anyAtomicType ) as xs:integer* |
fn:index-of (
|
$seq |
as xs:anyAtomicType* ,
|
$search |
as xs:anyAtomicType ,
|
|
$collation |
as xs:string ) as xs:integer* |
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The function returns a sequence of positive integers giving the positions within the
sequence $seq
of items that are equal to $search
.
The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation. This collation is used when string comparison is required.
The items in the sequence $seq
are compared with $search
under
the rules for the eq
operator. Values of type xs:untypedAtomic
are compared as if they were of type xs:string
. Values that cannot be
compared, because the eq
operator is not defined for their types, are
considered to be distinct. If an item compares equal, then the position of that item
in
the sequence $seq
is included in the result.
The first item in a sequence is at position 1, not position 0.
The result sequence is in ascending numeric order.
If the value of $seq
is the empty sequence, or if no item in
$seq
matches $search
, then the function returns the empty
sequence.
No error occurs if non-comparable values are encountered. So when comparing two atomic
values, the effective boolean value of fn:index-of($a, $b)
is true if
$a
and $b
are equal, false if they are not equal or not
comparable.
The expression fn:index-of((10, 20, 30, 40), 35)
returns ()
.
The expression fn:index-of((10, 20, 30, 30, 20, 10), 20)
returns (2, 5)
.
The expression fn:index-of(("a", "sport", "and", "a", "pastime"),
"a")
returns (1, 4)
.
The expression fn:index-of(current-date(), 23)
returns ()
.
The expression fn:index-of([1, [5, 6], [6, 7]], 6)
returns (3, 4)
. (The array is atomized to a sequence of five integers).
If @a
is an attribute of type xs:NMTOKENS
whose string
value is "red green blue"
, and whose typed value is therefore
("red", "green", "blue")
, then fn:index-of(@a, "blue")
returns 3
. This is because the function calling mechanism atomizes the
attribute node to produce a sequence of three xs:NMTOKEN
values.
This function assesses whether two sequences are deep-equal to each other. To be deep-equal, they must contain items that are pairwise deep-equal; and for two items to be deep-equal, they must either be atomic values that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal, or maps with matching entries, or arrays with matching members.
fn:deep-equal
($parameter1
as
item()*
, $parameter2
as
item()*
) as
xs:boolean
fn:deep-equal (
|
$parameter1 |
as item()* ,
|
$parameter2 |
as item()* ,
|
|
$collation |
as xs:string ) as xs:boolean |
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The $collation
argument identifies a collation which is used at all levels
of recursion when strings are compared (but not when names are compared), according
to
the rules in 5.3.5 Choosing a collation.
If the two sequences are both empty, the function returns true
.
If the two sequences are of different lengths, the function returns
false
.
If the two sequences are of the same length, the function returns true
if
and only if every item in the sequence $parameter1
is deep-equal to the
item at the same position in the sequence $parameter2
. The rules for
deciding whether two items are deep-equal follow.
Call the two items $i1
and $i2
respectively.
If $i1
and $i2
are both atomic values, they are deep-equal if
and only if ($i1 eq $i2)
is true
, or if both values are
NaN
. If the eq
operator is not defined for $i1
and $i2
, the function returns false
.
If $i1
and $i2
are both ·maps·, the result is true
if and only if all the
following conditions apply:
Both maps have the same number of entries.
For every entry in the first map, there is an entry in the second map that:
has the ·same key· (note that the collation is not used when comparing keys), and
has the same associated value (compared using the fn:deep-equal
function, under the collation supplied in the original call to
fn:deep-equal
).
If $i1
and $i2
are both ·arrays·, the result is true
if and only if all
the following conditions apply:
Both arrays have the same number of members (array:size($i1) eq
array:size($i2)
).
Members in the same position of both arrays are deep-equal to each other, under
the collation supplied in the original call to fn:deep-equal
: that is,
every $p in 1 to array:size($i1) satisfies deep-equal($i1($p), $i2($p),
$collation)
If $i1
and $i2
are both nodes, they are compared as described
below:
If the two nodes are of different kinds, the result is false
.
If the two nodes are both document nodes then they are deep-equal if and only if
the sequence $i1/(*|text())
is deep-equal to the sequence
$i2/(*|text())
.
If the two nodes are both element nodes then they are deep-equal if and only if all of the following conditions are satisfied:
The two nodes have the same name, that is (node-name($i1) eq
node-name($i2))
.
Either both nodes are annotated as having simple content or both nodes are annotated as having complex content. For this purpose "simple content" means either a simple type or a complex type with simple content; "complex content" means a complex type whose variety is mixed, element-only, or empty.
Note:
It is a consequence of this rule that validating a document D against a schema will usually (but not necessarily) result in a document that is not deep-equal to D. The exception is when the schema allows all elements to have mixed content.
The two nodes have the same number of attributes, and for every attribute
$a1
in $i1/@*
there exists an attribute
$a2
in $i2/@*
such that $a1
and
$a2
are deep-equal.
One of the following conditions holds:
Both element nodes are annotated as having simple content (as defined
in 3(b) above), and the typed value of $i1
is deep-equal
to the typed value of $i2
.
Both element nodes have a type annotation that is a complex type with
variety element-only, and the sequence $i1/*
is
deep-equal to the sequence $i2/*
.
Both element nodes have a type annotation that is a complex type with
variety mixed, and the sequence $i1/(*|text())
is
deep-equal to the sequence $i2/(*|text())
.
Both element nodes have a type annotation that is a complex type with variety empty.
If the two nodes are both attribute nodes then they are deep-equal if and only if both the following conditions are satisfied:
The two nodes have the same name, that is (node-name($i1) eq
node-name($i2))
.
The typed value of $i1
is deep-equal to the typed value of
$i2
.
If the two nodes are both processing instruction nodes, then they are deep-equal if and only if both the following conditions are satisfied:
The two nodes have the same name, that is (node-name($i1) eq
node-name($i2))
.
The string value of $i1
is equal to the string value of
$i2
.
If the two nodes are both namespace nodes, then they are deep-equal if and only if both the following conditions are satisfied:
The two nodes either have the same name or are both nameless, that is
fn:deep-equal(node-name($i1), node-name($i2))
.
The string value of $i1
is equal to the string value of
$i2
when compared using the Unicode codepoint collation.
If the two nodes are both text nodes or comment nodes, then they are deep-equal if and only if their string-values are equal.
In all other cases the result is false.
A type error is raised [err:FOTY0015] if either input sequence contains a function item that is not a map or array.
The two nodes are not required to have the same type annotation, and they are not
required to have the same in-scope namespaces. They may also differ in their parent,
their base URI, and the values returned by the is-id
and
is-idrefs
accessors (see Section
5.5 is-id Accessor
DM31 and
Section
5.6 is-idrefs Accessor
DM31). The order of children is significant,
but the order of attributes is insignificant.
The contents of comments and processing instructions are significant only if these nodes appear directly as items in the two sequences being compared. The content of a comment or processing instruction that appears as a descendant of an item in one of the sequences being compared does not affect the result. However, the presence of a comment or processing instruction, if it causes a text node to be split into two text nodes, may affect the result.
Comparing items of different kind (for example, comparing an atomic
value to a node, or a map to an array, or an integer to an xs:date
) returns false, it does not return an error. So
the result of fn:deep-equal(1, current-dateTime())
is false
.
Comparing a function (other than a map or array) to any other value raises a type error.
let $at := <attendees> <name last='Parker' first='Peter'/> <name last='Barker' first='Bob'/> <name last='Parker' first='Peter'/> </attendees>
The expression fn:deep-equal($at, $at/*)
returns false()
.
The expression fn:deep-equal($at/name[1], $at/name[2])
returns false()
.
The expression fn:deep-equal($at/name[1], $at/name[3])
returns true()
.
The expression fn:deep-equal($at/name[1], 'Peter Parker')
returns false()
.
The expression fn:deep-equal(map{1:'a', 2:'b'}, map{2:'b', 1:'a'})
returns true()
.
The expression fn:deep-equal([1, 2, 3], [1, 2, 3])
returns true()
.
The expression fn:deep-equal((1, 2, 3), [1, 2, 3])
returns false()
.
The following functions test the cardinality of their sequence arguments.
| Function | Meaning |
|---|---|
fn:zero-or-one |
Returns $arg if it contains zero or one items. Otherwise, raises an
error.
|
fn:one-or-more |
Returns $arg if it contains one or more items. Otherwise, raises an error.
|
fn:exactly-one |
Returns $arg if it contains exactly one item. Otherwise, raises an error.
|
The functions fn:zero-or-one
, fn:one-or-more
, and
fn:exactly-one
defined in this section, check that the cardinality
of a sequence is in the expected range. They are particularly useful with regard
to static typing. For example, the function call fn:remove($seq, fn:index-of($seq2, 'abc'))
requires the result of the call on fn:index-of
to be a singleton integer,
but the static type system cannot infer this; writing the expression as
fn:remove($seq, fn:exactly-one(fn:index-of($seq2, 'abc')))
will provide a suitable static type at query analysis time, and ensures that the length
of the sequence is
correct with a dynamic check at query execution time.
The type signatures for these functions deliberately declare the argument type as
item()*
, permitting a sequence of any length. A more restrictive
signature would defeat the purpose of the function, which is to defer
cardinality checking until query execution time.
Returns $arg
if it contains zero or one items. Otherwise, raises an
error.
fn:zero-or-one
($arg
as
item()*
) as
item()?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Except in error cases, the function returns $arg
unchanged.
A dynamic error is raised [err:FORG0003] if $arg
contains more than one item.
Returns $arg
if it contains one or more items. Otherwise, raises an error.
fn:one-or-more
($arg
as
item()*
) as
item()+
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Except in error cases, the function returns $arg
unchanged.
A dynamic error is raised [err:FORG0004] if $arg
is an
empty sequence.
Returns $arg
if it contains exactly one item. Otherwise, raises an error.
fn:exactly-one
($arg
as
item()*
) as
item()
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Except in error cases, the function returns $arg
unchanged.
A dynamic error is raised [err:FORG0005] if $arg
is an
empty sequence or a sequence containing more than one item.
Aggregate functions take a sequence as argument and return a single value
computed from values in the sequence. Except for fn:count
, the
sequence must consist of values of a single type or one if its subtypes, or they
must be numeric. xs:untypedAtomic
values are permitted in the
input sequence and handled by special conversion rules. The type of the items in
the sequence must also support certain operations.
| Function | Meaning |
|---|---|
fn:count |
Returns the number of items in a sequence. |
fn:avg |
Returns the average of the values in the input sequence $arg , that is, the
sum of the values divided by the number of values.
|
fn:max |
Returns a value that is equal to the highest value appearing in the input sequence. |
fn:min |
Returns a value that is equal to the lowest value appearing in the input sequence. |
fn:sum |
Returns a value obtained by adding together the values in $arg .
|
Returns the number of items in a sequence.
fn:count
($arg
as
item()*
) as
xs:integer
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the number of items in the value of $arg
.
Returns 0 if $arg
is the empty sequence.
let $seq1 := ($item1, $item2)
let $seq2 := (98.5, 98.3, 98.9)
let $seq3 := ()
The expression fn:count($seq1)
returns 2
.
The expression fn:count($seq3)
returns 0
.
The expression fn:count($seq2)
returns 3
.
The expression fn:count($seq2[. > 100])
returns 0
.
The expression fn:count([])
returns 1
.
The expression fn:count([1,2,3])
returns 1
.
Returns the average of the values in the input sequence $arg
, that is, the
sum of the values divided by the number of values.
fn:avg
($arg
as
xs:anyAtomicType*
) as
xs:anyAtomicType?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $arg
is the empty sequence, the empty sequence is returned.
If $arg
contains values of type xs:untypedAtomic
they are cast
to xs:double
.
Duration values must either all be xs:yearMonthDuration
values or must all
be xs:dayTimeDuration
values. For numeric values, the numeric promotion
rules defined in 4.2 Arithmetic operators on numeric values are used to promote all values to a single
common type. After these operations, $arg
must satisfy the following condition:
There must be a type T such that:
$arg
is an instance of T.
xs:double
, xs:float
,xs:decimal
, xs:yearMonthDuration
, orxs:dayTimeDuration
.
The function returns the average of the values as sum($arg) div
count($arg)
; but the implementation may use an otherwise equivalent algorithm
that avoids arithmetic overflow.
A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.
let $d1 := xs:yearMonthDuration("P20Y")
let $d2 := xs:yearMonthDuration("P10M")
let $seq3 := (3, 4, 5)
The expression fn:avg($seq3)
returns 4.0
. (The result is of type xs:decimal
.)
The expression fn:avg(($d1, $d2))
returns xs:yearMonthDuration("P10Y5M")
.
fn:avg(($d1, $seq3))
raises a type error [err:FORG0006].
The expression fn:avg(())
returns ()
.
The expression fn:avg((xs:float('INF'), xs:float('-INF')))
returns xs:float('NaN')
.
The expression fn:avg(($seq3, xs:float('NaN')))
returns xs:float('NaN')
.
Returns a value that is equal to the highest value appearing in the input sequence.
fn:max
($arg
as
xs:anyAtomicType*
) as
xs:anyAtomicType?
fn:max
($arg
as
xs:anyAtomicType*
, $collation
as
xs:string
) as
xs:anyAtomicType?
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The following conversions are applied to the input sequence $arg
, in order:
Values of type xs:untypedAtomic
in $arg
are cast to
xs:double
.
If the resulting sequence contains values that are instances of more than one primitive type (meaning the 19 primitive types defined in [Schema 1.1 Part 2]), then:
If each value is an instance of one of the types xs:string
or xs:anyURI
,
then all the values are cast to type xs:string
.
If each value is an instance of one of the types xs:decimal
or xs:float
,
then all the values are cast to type xs:float
.
If each value is an instance of one of the types xs:decimal
, xs:float
,
or xs:double
, then all the values are cast to type xs:double
.
Otherwise, a type error is raised [err:FORG0006].
Note:
The primitive type of an xs:integer
value for this purpose is xs:decimal
.
The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence. The function returns an item from the converted sequence rather than the input sequence.
If the converted sequence is empty, the function returns the empty sequence.
All items in the converted sequence must be derived from a single base type for which
the le
operator is defined. In addition, the values in the sequence must
have a total order. If date/time values do not have a timezone, they are considered
to
have the implicit timezone provided by the dynamic context for the purpose of
comparison. Duration values must either all be xs:yearMonthDuration
values
or must all be xs:dayTimeDuration
values.
If the converted sequence contains the value NaN
, the value
NaN
is returned
(as an xs:float
or xs:double
as appropriate).
If the items in the converted sequence are of type xs:string
or types
derived by restriction from xs:string
, then the determination of the item
with the smallest value is made according to the collation that is used. If the type
of
the items in the converted sequence is not xs:string
and
$collation
is specified, the collation is ignored.
The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation.
The function returns the result of the expression:
if (every $v in $c satisfies $c[1] ge $v) then $c[1] else fn:max(fn:tail($c))
evaluated with $collation
as the default collation if specified, and with
$c
as the converted sequence.
A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.
Because the rules allow the sequence to be reordered, if there are two or more items
that are
"equal highest", the specific item whose value is returned is ·implementation-dependent·. This can arise for example if two different strings
compare equal under the selected collation, or if two different xs:dateTime
values compare equal despite being in different timezones.
If the converted sequence contains exactly one value then that value is returned.
The default type when the fn:max
function is applied to
xs:untypedAtomic
values is xs:double
. This differs from the
default type for operators such as gt
, and for sorting in XQuery and XSLT,
which is xs:string
.
The rules for the dynamic type of the result are stricter in version 3.1 of the specification
than
in earlier versions. For example, if all the values in the input sequence belong to
types derived from
xs:integer
, version 3.0 required only that the result be an instance
of the least common supertype of the types present in the input sequence; Version
3.1
requires that the returned value retains its original type. This does not apply, however,
where type promotion
is needed to convert all the values to a common primitive type.
The expression fn:max((3,4,5))
returns 5
.
The expression fn:max([3,4,5])
returns 5
. (Arrays are atomized).
The expression fn:max((xs:integer(5), xs:float(5.0), xs:double(0)))
returns xs:double(5.0e0)
.
fn:max((3,4,"Zero"))
raises a type error [err:FORG0006].
The expression fn:max((fn:current-date(), xs:date("2100-01-01")))
returns xs:date("2100-01-01")
. (Assuming that the current date is during the 21st
century.)
The expression fn:max(("a", "b", "c"))
returns "c"
. (Assuming a typical default collation.)
Returns a value that is equal to the lowest value appearing in the input sequence.
fn:min
($arg
as
xs:anyAtomicType*
) as
xs:anyAtomicType?
fn:min
($arg
as
xs:anyAtomicType*
, $collation
as
xs:string
) as
xs:anyAtomicType?
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and implicit timezone.
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI, and implicit timezone.
The following rules are applied to the input sequence:
Values of type xs:untypedAtomic
in $arg
are cast to
xs:double
.
If the resulting sequence contains values that are instances of more than one primitive type (meaning the 19 primitive types defined in [Schema 1.1 Part 2]), then:
If each value is an instance of one of the types xs:string
or xs:anyURI
,
then all the values are cast to type xs:string
.
If each value is an instance of one of the types xs:decimal
or xs:float
,
then all the values are cast to type xs:float
.
If each value is an instance of one of the types xs:decimal
, xs:float
,
or xs:double
, then all the values are cast to type xs:double
.
Otherwise, a type error is raised [err:FORG0006].
Note:
The primitive type of an xs:integer
value for this purpose is xs:decimal
.
The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence. The function returns an item from the converted sequence rather than the input sequence.
If the converted sequence is empty, the empty sequence is returned.
All items in the converted sequence must be derived from a single base type for which
the le
operator is defined. In addition, the values in the sequence must
have a total order. If date/time values do not have a timezone, they are considered
to
have the implicit timezone provided by the dynamic context for the purpose of
comparison. Duration values must either all be xs:yearMonthDuration
values
or must all be xs:dayTimeDuration
values.
If the converted sequence contains the value NaN
, the value
NaN
is returned
(as an xs:float
or xs:double
as appropriate).
If the items in the converted sequence are of type xs:string
or types
derived by restriction from xs:string
, then the determination of the item
with the smallest value is made according to the collation that is used. If the type
of
the items in the converted sequence is not xs:string
and
$collation
is specified, the collation is ignored.
The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation.
The function returns the result of the expression:
if (every $v in $c satisfies $c[1] le $v) then $c[1] else fn:min(fn:tail($c))
evaluated with $collation
as the default collation if specified, and with
$c
as the converted sequence.
A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.
Because the rules allow the sequence to be reordered, if there are two or items that
are
"equal lowest", the specific item whose value is returned is ·implementation-dependent·. This can arise for example if two different strings
compare equal under the selected collation, or if two different xs:dateTime
values compare equal despite being in different timezones.
If the converted sequence contains exactly one value then that value is returned.
The default type when the fn:min
function is applied to
xs:untypedAtomic
values is xs:double
. This differs from the
default type for operators such as lt
, and for sorting in XQuery and XSLT,
which is xs:string
.
The rules for the dynamic type of the result are stricter in version 3.1 of the specification
than
in earlier versions. For example, if all the values in the input sequence belong to
types derived from
xs:integer
, version 3.0 required only that the result be an instance
of the least common supertype of the types present in the input sequence; Version
3.1
requires that the returned value retains its original type. This does not apply, however,
where type promotion
is needed to convert all the values to a common primitive type.
The expression fn:min((3,4,5))
returns 3
.
The expression fn:min([3,4,5])
returns 3
. (Arrays are atomized).
The expression fn:min((xs:integer(5), xs:float(5), xs:double(10)))
returns xs:double(5.0e0)
.
fn:min((3,4,"Zero"))
raises a type error [err:FORG0006].
fn:min((xs:float(0.0E0), xs:float(-0.0E0)))
can return either positive
or negative zero. The two items are equal, so it is ·implementation-dependent· which is returned.
The expression fn:min((fn:current-date(), xs:date("1900-01-01")))
returns xs:date("1900-01-01")
. (Assuming that the current date is set to a reasonable
value.)
The expression fn:min(("a", "b", "c"))
returns "a"
. (Assuming a typical default collation.)
Returns a value obtained by adding together the values in $arg
.
fn:sum
($arg
as
xs:anyAtomicType*
) as
xs:anyAtomicType
fn:sum (
|
$arg |
as xs:anyAtomicType* ,
|
$zero |
as xs:anyAtomicType? ) as xs:anyAtomicType? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Any values of type xs:untypedAtomic
in $arg
are cast to
xs:double
. The items in the resulting sequence may be reordered in an
arbitrary order. The resulting sequence is referred to below as the converted
sequence.
If the converted sequence is empty, then the single-argument form of the function
returns the xs:integer
value 0
; the two-argument form returns
the value of the argument $zero
.
If the converted sequence contains the value NaN
, NaN
is
returned.
All items in $arg
must be numeric or derived from a single base type. In
addition, the type must support addition. Duration values must either all be
xs:yearMonthDuration
values or must all be
xs:dayTimeDuration
values. For numeric values, the numeric promotion
rules defined in 4.2 Arithmetic operators on numeric values are used to promote all values to a single
common type. The sum of a sequence of integers will therefore be an integer, while
the
sum of a numeric sequence that includes at least one xs:double
will be an
xs:double
.
The result of the function, using the second signature, is the result of the expression:
if (fn:count($c) eq 0) then $zero else if (fn:count($c) eq 1) then $c[1] else $c[1] + fn:sum(subsequence($c, 2))
where $c
is the converted sequence.
The result of the function, using the first signature, is the result of the expression:
fn:sum($arg, 0)
.
A type error is raised [err:FORG0006] if the input sequence contains items of incompatible types, as described above.
The second argument allows an appropriate value to be defined to represent the sum of an empty sequence. For example, when summing a sequence of durations it would be appropriate to return a zero-length duration of the appropriate type. This argument is necessary because a system that does dynamic typing cannot distinguish "an empty sequence of integers", for example, from "an empty sequence of durations".
If the converted sequence contains exactly one value then that value is returned.
let $d1 := xs:yearMonthDuration("P20Y")
let $d2 := xs:yearMonthDuration("P10M")
let $seq1 := ($d1, $d2)
let $seq3 := (3, 4, 5)
The expression fn:sum(($d1, $d2))
returns xs:yearMonthDuration("P20Y10M")
.
The expression fn:sum($seq1[. lt xs:yearMonthDuration('P3M')],
xs:yearMonthDuration('P0M'))
returns xs:yearMonthDuration("P0M")
.
The expression fn:sum($seq3)
returns 12
.
The expression fn:sum(())
returns 0
.
The expression fn:sum((),())
returns ()
.
The expression fn:sum((1 to 100)[. lt 0], 0)
returns 0
.
fn:sum(($d1, 9E1))
raises a type error [err:FORG0006].
The expression fn:sum(($d1, $d2), "ein Augenblick")
returns xs:yearMonthDuration("P20Y10M")
. (There is no requirement that the $zero
value should be
the same type as the items in $arg
, or even that it should belong to
a type that supports addition.)
The expression fn:sum([1, 2, 3])
returns 6
. (Atomizing an array returns the sequence obtained by atomizing its members.)
The expression fn:sum([[1, 2], [3, 4]])
returns 10
. (Atomizing an array returns the sequence obtained by atomizing its members.)
This section defines a number of functions used to find elements by ID
or IDREF
value,
or to generate IDs.
| Function | Meaning |
|---|---|
fn:id |
Returns the sequence of element nodes that have an ID value matching the
value of one or more of the IDREF values supplied in $arg .
|
fn:element-with-id |
Returns the sequence of element nodes that have an ID value matching the
value of one or more of the IDREF values supplied in $arg .
|
fn:idref |
Returns the sequence of element or attribute nodes with an IDREF value
matching the value of one or more of the ID values supplied in
$arg .
|
fn:generate-id |
This function returns a string that uniquely identifies a given node. |
Returns the sequence of element nodes that have an ID
value matching the
value of one or more of the IDREF
values supplied in $arg
.
fn:id
($arg
as
xs:string*
) as
element()*
fn:id
($arg
as
xs:string*
, $node
as
node()
) as
element()*
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a sequence, in document order with duplicates eliminated,
containing every element node E
that satisfies all the following
conditions:
E
is in the target document. The target document is the document
containing $node
, or the document containing the context item
(.
) if the second argument is omitted. The behavior of the
function if $node
is omitted is exactly the same as if the context
item had been passed as $node
.
E
has an ID
value equal to one of the candidate
IDREF
values, where:
An element has an ID
value equal to V
if either
or both of the following conditions are true:
The is-id
property (See Section
5.5 is-id Accessor
DM31.) of the element node is true, and the typed value
of the element node is equal to V
under the rules of the
eq
operator using the Unicode codepoint collation
(http://www.w3.org/2005/xpath-functions/collation/codepoint
).
The element has an attribute node whose is-id
property
(See Section
5.5 is-id Accessor
DM31.) is true and whose typed
value is equal to V
under the rules of the
eq
operator using the Unicode code point collation
(http://www.w3.org/2005/xpath-functions/collation/codepoint
).
Each xs:string
in $arg
is parsed as if it were of
type IDREFS
, that is, each xs:string
in
$arg
is treated as a whitespace-separated sequence of
tokens, each acting as an IDREF
. These tokens are then included
in the list of candidate IDREF
s. If any of the tokens is not a
lexically valid IDREF
(that is, if it is not lexically an
xs:NCName
), it is ignored. Formally, the candidate
IDREF
values are the strings in the sequence given by the
expression:
for $s in $arg return fn:tokenize(fn:normalize-space($s), ' ')[. castable as xs:IDREF]
If several elements have the same ID
value, then E
is
the one that is first in document order.
A dynamic error is raised [err:FODC0001] if
$node
, or the context item if the second argument is absent, is a node
in a tree whose root is not a document node.
The following errors may be raised when $node
is omitted:
If the context item is absentDM31, dynamic error [err:XPDY0002]XP31
If the context item is not a node, type error [err:XPTY0004]XP31.
The effect of this function is anomalous in respect of element nodes with the
is-id
property. For legacy reasons, this function returns the element
that has the is-id
property, whereas it would be more appropriate to return
its parent, that being the element that is uniquely identified by the ID. A new function
fn:element-with-id
has been introduced with the desired
behavior.
If the data model is constructed from an Infoset, an attribute will have the
is-id
property if the corresponding attribute in the Infoset had an
attribute type of ID
: typically this means the attribute was declared as an
ID
in a DTD.
If the data model is constructed from a PSVI, an element or attribute will have the
is-id
property if its typed value is a single atomic value of type
xs:ID
or a type derived by restriction from xs:ID
.
No error is raised in respect of a candidate IDREF
value that does not
match the ID
of any element in the document. If no candidate
IDREF
value matches the ID
value of any element, the
function returns the empty sequence.
It is not necessary that the supplied argument should have type xs:IDREF
or xs:IDREFS
, or that it should be derived from a node with the
is-idrefs
property.
An element may have more than one ID
value. This can occur with synthetic
data models or with data models constructed from a PSVI where the element and one
of its
attributes are both typed as xs:ID
.
If the source document is well-formed but not valid, it is possible for two or more
elements to have the same ID
value. In this situation, the function will
select the first such element.
It is also possible in a well-formed but invalid document to have an element or
attribute that has the is-id
property but whose value does not conform to
the lexical rules for the xs:ID
type. Such a node will never be selected by
this function.
let $emp := validate lax{ document{ <employee xml:id="ID21256" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <empnr xsi:type="xs:ID">E21256</empnr> <first>John</first> <last>Brown</last> </employee> } }
The expression $emp/id('ID21256')/name()
returns "employee"
. (The xml:id
attribute has the is-id
property,
so the employee element is selected.)
The expression $emp/id('E21256')/name()
returns "empnr"
. (Assuming the empnr
element is given the type
xs:ID
as a result of schema validation, the element will have the
is-id
property and is therefore selected. Note the difference from
the behavior of fn:element-with-id
.)
Returns the sequence of element nodes that have an ID
value matching the
value of one or more of the IDREF
values supplied in $arg
.
fn:element-with-id
($arg
as
xs:string*
) as
element()*
fn:element-with-id
($arg
as
xs:string*
, $node
as
node()
) as
element()*
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Note:
The effect of this function is identical to fn:id
in respect of
elements that have an attribute with the is-id
property. However, it
behaves differently in respect of element nodes with the is-id
property.
Whereas the fn:id
function, for legacy reasons, returns the element that has the
is-id
property, this function returns the element identified by the ID,
which is the parent of the element having the is-id
property.
The function returns a sequence, in document order with duplicates eliminated,
containing every element node E
that satisfies all the following
conditions:
E
is in the target document. The target document is the document
containing $node
, or the document containing the context item
(.
) if the second argument is omitted. The behavior of the
function if $node
is omitted is exactly the same as if the context
item had been passed as $node
.
E
has an ID
value equal to one of the candidate
IDREF
values, where:
An element has an ID
value equal to V
if either
or both of the following conditions are true:
The element has an child element node whose is-id
property (See Section
5.5 is-id Accessor
DM31.) is true and
whose typed value is equal to V
under the rules of the
eq
operator using the Unicode code point collation
(http://www.w3.org/2005/xpath-functions/collation/codepoint
).
The element has an attribute node whose is-id
property
(See Section
5.5 is-id Accessor
DM31.) is true and whose typed
value is equal to V
under the rules of the
eq
operator using the Unicode code point collation
(http://www.w3.org/2005/xpath-functions/collation/codepoint
).
Each xs:string
in $arg
is parsed as if it were of
type IDREFS
, that is, each xs:string
in
$arg
is treated as a whitespace-separated sequence of
tokens, each acting as an IDREF
. These tokens are then included
in the list of candidate IDREF
s. If any of the tokens is not a
lexically valid IDREF
(that is, if it is not lexically an
xs:NCName
), it is ignored. Formally, the candidate
IDREF
values are the strings in the sequence given by the
expression:
for $s in $arg return fn:tokenize(fn:normalize-space($s), ' ')[. castable as xs:IDREF]
If several elements have the same ID
value, then E
is
the one that is first in document order.
A dynamic error is raised [err:FODC0001] if
$node
, or the context item if the second argument is omitted, is a node
in a tree whose root is not a document node.
The following errors may be raised when $node
is omitted:
If the context item is absentDM31, dynamic error [err:XPDY0002]XP31
If the context item is not a node, type error [err:XPTY0004]XP31.
This function is equivalent to the fn:id
function except when dealing with
ID-valued element nodes. Whereas the fn:id
function selects the element
containing the identifier, this function selects its parent.
If the data model is constructed from an Infoset, an attribute will have the
is-id
property if the corresponding attribute in the Infoset had an
attribute type of ID
: typically this means the attribute was declared as an
ID
in a DTD.
If the data model is constructed from a PSVI, an element or attribute will have the
is-id
property if its typed value is a single atomic value of type
xs:ID
or a type derived by restriction from xs:ID
.
No error is raised in respect of a candidate IDREF
value that does not
match the ID
of any element in the document. If no candidate
IDREF
value matches the ID
value of any element, the
function returns the empty sequence.
It is not necessary that the supplied argument should have type xs:IDREF
or xs:IDREFS
, or that it should be derived from a node with the
is-idrefs
property.
An element may have more than one ID
value. This can occur with synthetic
data models or with data models constructed from a PSVI where the element and one
of its
attributes are both typed as xs:ID
.
If the source document is well-formed but not valid, it is possible for two or more
elements to have the same ID
value. In this situation, the function will
select the first such element.
It is also possible in a well-formed but invalid document to have an element or
attribute that has the is-id
property but whose value does not conform to
the lexical rules for the xs:ID
type. Such a node will never be selected by
this function.
let $emp := validate lax{ document{ <employee xml:id="ID21256" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <empnr xsi:type="xs:ID">E21256</empnr> <first>John</first> <last>Brown</last> </employee> } }
The expression $emp/fn:element-with-id('ID21256')/name()
returns "employee"
. (The xml:id
attribute has the is-id
property,
so the employee element is selected.)
The expression $emp/fn:element-with-id('E21256')/name()
returns "employee"
. (Assuming the empnr
element is given the type
xs:ID
as a result of schema validation, the element will have the
is-id
property and is therefore its parent is selected. Note the
difference from the behavior of fn:id
.)
Returns the sequence of element or attribute nodes with an IDREF
value
matching the value of one or more of the ID
values supplied in
$arg
.
fn:idref
($arg
as
xs:string*
) as
node()*
fn:idref
($arg
as
xs:string*
, $node
as
node()
) as
node()*
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns a sequence, in document order with duplicates eliminated,
containing every element or attribute node $N
that satisfies all the
following conditions:
$N
is in the target document. The target document is the document
containing $node
or the document containing the context item
(.
) if the second argument is omitted. The behavior of the
function if $node
is omitted is exactly the same as if the context
item had been passed as $node
.
$N
has an IDREF
value equal to one of the candidate
ID
values, where:
A node $N
has an IDREF
value equal to
V
if both of the following conditions are true:
The is-idrefs
property (see Section
5.6 is-idrefs Accessor
DM31) of $N
is true
.
The sequence
fn:tokenize(fn:normalize-space(fn:string($N)), ' ')
contains a string that is
equal to V
under the rules of the eq
operator using the Unicode code point collation
(http://www.w3.org/2005/xpath-functions/collation/codepoint
).
Each xs:string
in $arg
is parsed as if it were of
lexically of type xs:ID
. These xs:string
s are then
included in the list of candidate xs:ID
s. If any of the strings
in $arg
is not a lexically valid xs:ID
(that is,
if it is not lexically an xs:NCName
), it is ignored. More
formally, the candidate ID
values are the strings in the
sequence:
$arg[. castable as xs:NCName]
A dynamic error is raised [err:FODC0001] if
$node
, or the context item if the second argument is omitted, is a node
in a tree whose root is not a document node.
The following errors may be raised when $node
is omitted:
If the context item is absentDM31, dynamic error [err:XPDY0002]XP31
If the context item is not a node, type error [err:XPTY0004]XP31.
An element or attribute typically acquires the is-idrefs
property by being
validated against the schema type xs:IDREF
or xs:IDREFS
, or
(for attributes only) by being described as of type IDREF
or
IDREFS
in a DTD.
Because the function is sensitive to the way in which the data model is constructed, calls on this function are not always interoperable.
No error is raised in respect of a candidate ID
value that does not match
the IDREF
value of any element or attribute in the document. If no
candidate ID
value matches the IDREF
value of any element or
attribute, the function returns the empty sequence.
It is possible for two or more nodes to have an IDREF
value that matches a
given candidate ID
value. In this situation, the function will return all
such nodes. However, each matching node will be returned at most once, regardless
how
many candidate ID
values it matches.
It is possible in a well-formed but invalid document to have a node whose
is-idrefs
property is true but that does not conform to the lexical
rules for the xs:IDREF
type. The effect of the above rules is that
ill-formed candidate ID
values and ill-formed IDREF
values are
ignored.
If the data model is constructed from a PSVI, the typed value of a node that has the
is-idrefs
property will contain at least one atomic value of type
xs:IDREF
(or a type derived by restriction from xs:IDREF
).
It may also contain atomic values of other types. These atomic values are treated
as
candidate ID
values if two conditions are met: their lexical form must be valid as an
xs:NCName
, and there must be at least one instance of xs:IDREF
in the typed value of the node. If these conditions are not satisfied, such values
are ignored.
let $emp := validate lax { document { <employees xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <employee xml:id="ID21256"> <empnr xsi:type="xs:ID">E21256</empnr> <first>Anil</first> <last>Singh</last> <deputy xsi:type="xs:IDREF">E30561</deputy> </employee> <employee xml:id="ID30561"> <empnr xsi:type="xs:ID">E30561</empnr> <first>John</first> <last>Brown</last> <manager xsi:type="xs:IDREF">ID21256</manager> </employee> </employees> } }
The expression $emp/(element-with-id('ID21256')/@xml:id => fn:idref())/ancestor::employee/last =>
string()
returns "Brown"
. (Assuming that manager
has the is-idref property, the call on fn:idref
selects
the manager
element. If, instead, the manager
had a ref
attribute with the is-idref property, the call on fn:idref
would select the attribute node.)
The expression $emp/(element-with-id('E30561')/empnr => fn:idref())/ancestor::employee/last => string()
returns "Singh"
. (Assuming that employee/deputy
has the is-idref property, the call on fn:idref
selects
the deputy
element.)
This function returns a string that uniquely identifies a given node.
fn:generate-id
() as
xs:string
fn:generate-id
($arg
as
node()?
) as
xs:string
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context item (.
). The
behavior of the function if the argument is omitted is exactly the same as if the
context item had been passed as the argument.
If the argument is the empty sequence, the result is the zero-length string.
In other cases, the function returns a string that uniquely identifies a given node.
More formally, it is guaranteed that within a single
·execution scope·,
fn:codepoint-equal(fn:generate-id($N), fn:generate-id($M))
returns true
if and only if ($M is $N)
returns true.
The returned identifier must consist of ASCII alphanumeric characters and must start with an alphabetic character. Thus, the string is syntactically an XML name.
The following errors may be raised when $arg
is omitted:
If the context item is absentDM31, dynamic error [err:XPDY0002]XP31
If the context item is not a node, type error [err:XPTY0004]XP31.
An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same node and that different identifiers are always generated from different nodes. An implementation is under no obligation to generate the same identifiers each time a document is transformed or queried.
There is no guarantee that a generated unique identifier will be distinct from any unique IDs specified in the source document.
There is no inverse to this function; it is not directly possible to find the node
with
a given generated ID. Of course, it is possible to search a given sequence of nodes
using an expression such as $nodes[generate-id()=$id]
.
It is advisable, but not required, for implementations to generate IDs that are distinct even when compared using a case-blind collation.
The primary use case for this function is to generate hyperlinks. For example, when
generating HTML, an anchor for a given section $sect
can be generated by
writing (in either XSLT or XQuery):
<a name="{fn:generate-id($sect)}"/>
and a link to that section can then be produced with code such as:
see <a href="#{fn:generate-id($sect)}">here</a>
Note that anchors generated in this way will not necessarily be the same each time a document is republished.
Since the keys in a map must be atomic values, it is possible to use generated IDs
as surrogates for nodes when constructing a map. For example, in some implementations,
testing whether a node $N
is a member of a large node-set $S