See also translations.
This document is also available in these non-normative formats: Specification in XML format using HTML5 vocabulary, XML function catalog, and HTML with change markings relative to version 3.0.
Copyright © 2017 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This document defines constructor functions, operators, and functions on the datatypes defined in [XML Schema Part 2: Datatypes Second Edition] and the datatypes defined in [XQuery and XPath Data Model (XDM) 3.1]. It also defines functions and operators on nodes and node sequences as defined in the [XQuery and XPath Data Model (XDM) 3.1]. These functions and operators are defined for use in [XML Path Language (XPath) 3.1] and [XQuery 3.1: An XML Query Language] and [XSL Transformations (XSLT) Version 3.0] and other related XML standards. The signatures and summaries of functions defined in this document are available at: http://www.w3.org/2005/xpath-functions/.
At the time of writing, XSLT 3.0 requires support for XPath 3.0, and therefore version 3.0 of this function library; but it makes support for XPath 3.1 optional. It also replicates some of the functions defined herein, notably those concerned with processing of maps, so that these functions are available in XSLT 3.0 whether or not the processor supports XPath 3.1.
This is the fourth version of the specification of this function library. The first version was included as an intrinsic part of the [XML Path Language (XPath) Version 1.0] specification published on 16 November 1999. The second version was published under the title XQuery 1.0 and XPath 2.0 Functions and Operators on 23 January 2007, subsequently revised in a second edition published on 14 December 2010. The third version, published on 8 April 2014, was the first to carry its own version number, 3.0. This version 3.1 is a revision of 3.0 that adds additional functions and operators, notably to work with the new datatypes of maps and arrays.
A summary of changes since version 3.0 is provided at F Changes since version 3.0.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document is governed by the 1 September 2015 W3C Process Document.
This is a Proposed Recommendation as described in the Process Document. This document will remain a Proposed Recommendation until 28 February 2017. Advisory Committee Representatives should consult their WBS questionnaires.
This document was published by the W3C XML Query Working Group and the W3C XSLT Working Group, each of which is part of the XML Activity.
The Working Groups expect to advance this specification to Recommendation Status.
This Proposed Recommendation specifies XSLT and XQuery Functions and Operators (F&O) version 3.1, a fully compatible extension of F&O version 3.0. This publication differs from its version 3.0 primarily by the addition of maps and arrays. There are numerous smaller differences as well, all documented in the change log.
This specification is designed to be referenced normatively from other specifications defining a host language for it; it is not intended to be implemented outside a host language. The implementability of this specification has been tested in the context of its normative inclusion in host languages defined by the XQuery 3.1 and XSLT 3.0 (expected in 2017) specifications; see the XQuery 3.1 implementation report (and, in the future, the WGs expect that there will also be an XSLT 3.0 implementation report) for details.
This document incorporates changes made against the Candidate Recommendation of 13 December 2016. Changes to this document since the Candidate Recommendation are detailed in F.4 Changes since the Candidate Recommendation of 13 December 2016.
Please report errors in this document using W3C's public Bugzilla system (instructions can be found at https://www.w3.org/XML/2005/04/qt-bugzilla). If access to that system is not feasible, you may send your comments to the W3C XSLT/XPath/XQuery public comments mailing list<EMAIL_ADDRESS>It will be very helpful if you include the string “[FO31]” in the subject line of your report, whether made in Bugzilla or in email. Please use multiple Bugzilla entries (or, if necessary, multiple email messages) if you have more than one comment to make. Archives of the comments and responses are available at https://lists.w3.org/Archives/Public/public-qt-comments/.
Publication as a Proposed Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by groups operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (W3C XML Query Working Group) and a public list of any patent disclosures (W3C XSLT Working Group) made in connection with the deliverables of each group; these pages also include instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
The purpose of this document is to catalog the functions and operators required for XPath 3.1, XQuery 3.1, and XSLT 3.0 (at the time of writing, XSLT 3.0 requires support for version 3.0 of this specification, and makes support for version 3.1 optional). The exact syntax used to call these functions and operators is specified in [XML Path Language (XPath) 3.1], [XQuery 3.1: An XML Query Language] and [XSL Transformations (XSLT) Version 3.0].
This document defines three classes of functions:
General purpose functions, available for direct use in user-written queries, stylesheets, and XPath expressions, whose arguments and results are values defined by the [XQuery and XPath Data Model (XDM) 3.1].
Constructor functions, used for creating instances of a datatype from values of (in general) a different datatype. These functions are also available for general use; they are named after the datatype that they return, and they always take a single argument.
Functions that specify the semantics of operators defined in [XML Path Language (XPath) 3.1] and [XQuery 3.1: An XML Query Language]. These exist for specification purposes only, and are not intended for direct calling from user-written code.
[XML Schema Part 2: Datatypes Second Edition] defines a number of primitive and derived datatypes, collectively known as built-in datatypes. This document defines functions and operations on these datatypes as well as the other types (for example, nodes and sequences of nodes) defined in Section 2.7 Schema Information DM31 of the [XQuery and XPath Data Model (XDM) 3.1]. These functions and operations are available for use in [XML Path Language (XPath) 3.1], [XQuery 3.1: An XML Query Language] and any other host language that chooses to reference them. In particular, they may be referenced in future versions of XSLT and related XML standards.
[Schema 1.1 Part 2] adds to the datatypes defined
in [XML Schema Part 2: Datatypes Second Edition]. It introduces a new derived type xs:dateTimeStamp
, and it
incorporates as built-in types the two types xs:yearMonthDuration
and xs:dayTimeDuration
which were previously XDM additions to the type system. In addition, XSD 1.1 clarifies
and updates many
aspects of the definitions of the existing datatypes: for example, it extends the
value space of
xs:double
to allow both positive and negative zero, and extends the lexical space to allow
+INF
;
it modifies the value space of xs:Name
to permit additional Unicode characters; it allows year zero and disallows leap seconds
in xs:dateTime
values; and it allows any character string to appear as the value of an xs:anyURI
item.
Implementations of this specification may support either XSD 1.0 or XSD 1.1 or both.
References to specific sections of some of the above documents are indicated by cross-document links in this document. Each such link consists of a pointer to a specific section followed a superscript specifying the linked document. The superscripts have the following meanings: 'XQ' [XQuery 3.1: An XML Query Language], 'XT' [XSL Transformations (XSLT) Version 3.0], 'XP' [XML Path Language (XPath) 3.1], and 'DM' [XQuery and XPath Data Model (XDM) 3.1].
This recommendation contains a set of function specifications. It defines conformance at the level of individual functions. An implementation of a function conforms to a function specification in this recommendation if all the following conditions are satisfied:
For all combinations of valid inputs to the function (both explicit arguments and implicit context dependencies), the result of the function meets the mandatory requirements of this specification.
For all invalid inputs to the function, the implementation signals (in some way appropriate to the calling environment) that a dynamic error has occurred.
For a sequence of calls within the same ·execution scope·, the requirements of this recommendation regarding the ·determinism· of results are satisfied (see 1.7.4 Properties of functions).
Other recommendations ("host languages") that reference this document may dictate:
Subsets or supersets of this set of functions to be available in particular environments;
Mechanisms for invoking functions, supplying arguments, initializing the static and dynamic context, receiving results, and handling errors;
A concrete realization of concepts such as ·execution scope·;
Which versions of other specifications referenced herein (for example, XML, XSD, or Unicode) are to be used.
Any behavior that is discretionary (implementation-defined or implementation-dependent) in this specification may be constrained by a host language.
Note:
Adding such constraints in a host language, however, is discouraged because it makes it difficult to re-use implementations of the function library across host languages.
This specification allows flexibility in the choice of versions of specifications on which it depends:
It is ·implementation-defined· which version of Unicode is supported, but it is recommended that the most recent version of Unicode be used.
It is ·implementation-defined· whether the type system is based on XML Schema 1.0 or XML Schema 1.1.
It is ·implementation-defined· whether definitions that rely on XML (for example, the set of valid XML characters) should use the definitions in XML 1.0 or XML 1.1.
Note:
The XML Schema 1.1 recommendation
introduces one new concrete datatype: xs:dateTimeStamp
; it also incorporates
the types xs:dayTimeDuration
, xs:yearMonthDuration
,
and xs:anyAtomicType
which were previously defined in earlier versions of [XQuery and XPath Data Model (XDM) 3.1].
Furthermore, XSD 1.1
includes the option of supporting revised definitions of types such as xs:NCName
based on the rules in XML 1.1 rather than 1.0.
In this document, text labeled as an example or as a Note is provided for explanatory purposes and is not normative.
The functions and operators defined in this document are contained in one of
several namespaces (see [Namespaces in XML]) and referenced using an
xs:QName
.
This document uses conventional prefixes to refer to these namespaces. User-written
applications can choose a different prefix to refer to the namespace, so long as it
is
bound to the correct URI. The host language may also define a default namespace for
function calls, in which case function names in that namespace need not be prefixed
at all. In many cases the default namespace will be
http://www.w3.org/2005/xpath-functions
, allowing a call on the fn:name
function (for example) to be written as name()
rather than fn:name()
;
in this document, however, all example function calls are explicitly prefixed.
The URIs of the namespaces and the conventional prefixes associated with them are:
http://www.w3.org/2001/XMLSchema
for constructors —
associated with xs
.
The section 18 Constructor functions defines
constructor functions for the built-in datatypes defined
in [XML Schema Part 2: Datatypes Second Edition] and in Section
2.7 Schema Information
DM31
of [XQuery and XPath Data Model (XDM) 3.1]. These datatypes and the corresponding constructor functions
are in the XML Schema namespace, http://www.w3.org/2001/XMLSchema
,
and are named in this document using the xs
prefix.
http://www.w3.org/2005/xpath-functions
for functions — associated with fn
.
The namespace
prefix used in this document for most functions that are available to users is
fn
.
http://www.w3.org/2005/xpath-functions/math
for functions — associated with math
.
This namespace is used for some mathematical functions. The namespace
prefix used in this document for these functions is math
.
These functions are available to users in exactly the same way as those in the
fn
namespace.
http://www.w3.org/2005/xpath-functions/map
for functions — associated with map
.
This namespace is used for some functions that manipulate maps (see
17.1 Functions that Operate on Maps). The namespace
prefix used in this document for these functions is map
.
These functions are available to users in exactly the same way as those in the
fn
namespace.
http://www.w3.org/2005/xpath-functions/array
for functions — associated with array
.
This namespace is used for some functions that manipulate maps (see
17.3 Functions that Operate on Arrays). The namespace
prefix used in this document for these functions is array
.
These functions are available to users in exactly the same way as those in the
fn
namespace.
http://www.w3.org/2005/xqt-errors
— associated with
err
.
There are no functions in this namespace; it is used for error codes.
This document uses the prefix err
to represent the namespace URI
http://www.w3.org/2005/xqt-errors
, which is the namespace for all XPath
and XQuery error codes and messages. This namespace prefix is not predeclared and
its use in this document is not normative.
http://www.w3.org/2010/xslt-xquery-serialization
— associated with
output
.
There are no functions in this namespace: it is used for serialization parameters, as described in [XSLT and XQuery Serialization 3.1]
Functions defined with the op
prefix are described here to
underpin the definitions of the operators in [XML Path Language (XPath) 3.1], [XQuery 3.1: An XML Query Language]
and [XSL Transformations (XSLT) Version 3.0]. These functions are not available
directly to users, and there is no requirement that implementations should
actually provide these functions. For this reason, no namespace is associated
with the op
prefix. For example, multiplication is generally
associated with the *
operator, but it is described as a function
in this document:
op:numeric-multiply
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs:numeric
Note:
The above namespace URIs are not expected to change from one version of this document to another. The contents of these namespaces may be extended to allow additional functions (and errors, and serialization parameters) to be defined.
A function is uniquely defined by its name and arity (number of arguments); it is
therefore
not possible to have two different functions that have the same name and arity, but
different
types in their signature. That is, function overloading in this sense of the term
is not permitted.
Consequently, functions such as fn:string
which accept arguments of many different
types have a signature that defines a very general argument type, in this case item()?
which accepts any single item; supplying an inappropriate item (such as a function
item) causes
a dynamic error.
Some functions on numeric types include the type xs:numeric
in their signature
as an argument or result type. In this version of the specification, xs:numeric
has been redefined as a built-in union type representing the union of
xs:decimal
, xs:float
, xs:double
(and thus automatically
accepting types derived from these, including xs:integer
).
Operators such as "+" may be overloaded: they map to different underlying functions depending on the dynamic types of the supplied operands.
It is possible for two functions to have the same name provided they have different arity (number of arguments). For the functions defined in this specification, where two functions have the same name and different arity, they also have closely related behavior, so they are defined in the same section of this document.
Each function (or group of functions having the same name) is defined in this specification using a standard proforma.
The function name is a QName
as defined in [XML Schema Part 2: Datatypes Second Edition]
and must adhere to its syntactic conventions. Following the precedent set by [XML Path Language (XPath) Version 1.0],
function names are generally composed of English words separated by hyphens ("-").
Abbreviations are
used only where there is a strong precedent in other programming languages (as with
math:sin
and
math:cos
for sine and cosine). If a
function name contains a [XML Schema Part 2: Datatypes Second Edition] datatype name, it may have
intercapitalized spelling and is used in the function name as such. An example is
fn:timezone-from-dateTime
.
The first section in the proforma is a short summary of what the function does. This is intended to be informative rather than normative.
Each function is then defined by specifying its signature, which defines the types of the parameters and of the result value.
Each function's signature is presented in a form like this:
fn:function-name
($parameter-name
as
parameter-type
, ...) as
return-type
In this notation, function-name, in bold-face, is the name of the
function whose signature is being specified. If the function takes no
parameters, then the name is followed by an empty parameter list:
"()
"; otherwise, the name is followed by a parenthesized list of
parameter declarations, in which each declaration specifies the static type of the
parameter, in italics, and a descriptive, but non-normative, name. If there are
two or more parameter declarations, they are separated by a comma. The
return-type
, also in italics, specifies the static type of the value returned by the
function. The dynamic type of the value returned by the function is the same as its
static
type or derived from the static type. All parameter types and return types are
specified using the SequenceType notation defined in Section
2.5.4 SequenceType Syntax
XP31.
One function, fn:concat
, has a variable number of arguments (two or more).
More strictly, there is an infinite set of functions having the name fn:concat
, with arity
ranging from 2 to infinity. For this special case, a single function signature is
given, with an ellipsis
indicating an indefinite number of arguments.
The next section in the proforma defines the semantics of the function as a set of rules. The order in which the rules appear is significant; they are to be applied in the order in which they are written. Error conditions, however, are generally listed in a separate section that follows the main rules, and take precedence over non-error rules except where otherwise stated. The principles outlined in Section 2.3.4 Errors and Optimization XP31 apply by default: to paraphrase, if the result of the function can be determined without evaluating all its arguments, then it is not necessary to evaluate the remaining arguments merely in order to determine whether any error conditions apply.
Where the proforma includes sections headed Notes or Examples, these are non-normative.
Rules for passing parameters to operators are described in the relevant sections
of [XQuery 3.1: An XML Query Language] and [XML Path Language (XPath) 3.1]. For example, the rules for
passing parameters to arithmetic operators are described in Section
3.5 Arithmetic Expressions
XP31. Specifically, rules for parameters of
type xs:untypedAtomic
and the empty sequence are specified in this section.
As is customary, the parameter type name indicates that the function or operator
accepts arguments of that type, or types derived from it, in that position. This
is called subtype substitution (See Section
2.5.5 SequenceType Matching
XP31). In addition, numeric type instances and
instances of type xs:anyURI
can be promoted to produce an argument
of the required type. (See Section
B.1 Type Promotion
XP31).
Subtype Substitution: A derived type may substitute for
its base type. In particular, xs:integer
may be used
where xs:decimal
is expected.
Numeric Type Promotion: xs:decimal
may be
promoted to xs:float
or xs:double
.
Promotion to xs:double
should be done directly, not via
xs:float
, to avoid loss of precision.
anyURI Type Promotion: A value of
type xs:anyURI
can be promoted to the
type xs:string
.
Some functions accept a single value or the empty sequence as an argument and
some may return a single value or the empty sequence. This is indicated in the
function signature by following the parameter or return type name with a
question mark: "?
", indicating that either a single value or the
empty sequence must appear. See below.
fn:function-name
($parameter-name
as
parameter-type?
) as
return-type?
Note that this function signature is different from a signature in which the
parameter is omitted. See, for example, the two signatures
for fn:string
. In the first signature, the parameter is omitted
and the argument defaults to the context item, referred to as .
.
In the second signature, the argument must be present but may be the empty
sequence, written as ()
.
Some functions accept a sequence of zero or more values as an argument. This is
indicated by following the name of the type of the items in the sequence with
*
. The sequence may contain zero or more items of the named type.
For example, the function below accepts a sequence of xs:double
and
returns a xs:double
or the empty sequence.
fn:median
($arg
as
xs:double*
) as
xs:double?
As a matter of convention, a number of functions defined in this document take a parameter whose value is a map, defining options controlling the detail of how the function is evaluated. Maps are a new datatype introduced in XPath 3.1.
For example, the function fn:xml-to-json
has an options parameter
allowing specification of whether the output is to be indented. A call might be written:
fn:xml-to-json($input, map{'indent':true()})
[Definition] Functions that take an options parameter adopt common conventions on how the options are used. These are referred to as the option parameter conventions. These rules apply only to functions that explicitly refer to them.
Where a function adopts the ·option parameter conventions·, the following rules apply:
The value of the relevant argument must be a map. The entries in the map are
referred to as options: the key of the entry is called the option name, and the
associated value is the option value. Option names defined in this specification
are always strings (single xs:string
values). Option values may
be of any type.
The type of the options parameter in the function signature is always
given as map(*)
.
Although option names are described above as strings, the actual key may be
any value that compares equal to the required string (using the eq
operator
with Unicode codepoint collation; or equivalently, the op:same-key
relation).
For example, instances of xs:untypedAtomic
or xs:anyURI
are equally acceptable.
Note:
This means that the implementation of the function can check for the
presence and value of particular options using the functions map:contains
and/or map:get
.
It is not an error if the options map contains options with names other than those
described in this specification. Implementations may attach an
·implementation-defined· meaning to such entries,
and may define errors that arise if such entries are present with invalid values.
Implementations must ignore such entries unless they have a specific
·implementation-defined· meaning.
Implementations that define additional options in this way should
use values of type xs:QName
as the option names, using an appropriate namespace.
All entries in the options map are optional, and supplying an empty map has the same effect as omitting the relevant argument in the function call, assuming this is permitted.
For each named option, the function specification defines a required type for the option value. The value that is actually supplied in the map is converted to this required type using the function conversion rulesXP31. A type error [err:XPTY0004]XP31 occurs if conversion of the supplied value to the required type is not possible, or if this conversion delivers a coerced function whose invocation fails with a type error. A dynamic error occurs if the supplied value after conversion is not one of the permitted values for the option in question: the error codes for this error are defined in the specification of each function.
Note:
It is the responsibility of each function implementation to invoke this conversion; it does not happen automatically as a consequence of the function calling rules.
In cases where an option is list-valued, by convention the value may be supplied
either as a sequence or as an array. Accepting a sequence is convenient if the
value is generated programmatically using an XPath expression; while accepting an
array
allows the options to be held in an external file in JSON format, to be read using
a call on the fn:json-doc
function.
In cases where the value of an option is itself a map, the specification of the particular function must indicate whether or not these rules apply recursively to the contents of that map.
The diagrams in this section show how nodes, functions, primitive simple types, and user defined types fit together into a type system. This type system comprises two distinct subsystems that both include the primitive atomic types. In the diagrams, connecting lines represent relationships between derived types and the types from which they are derived; the arrowheads point toward the type from which they are derived. The dashed line represents relationships not present in this diagram, but that appear in one of the other diagrams. Dotted lines represent additional relationships that follow an evident pattern. The information that appears in each diagram is recapitulated in tabular form.
The xs:IDREFS
, xs:NMTOKENS
,
xs:ENTITIES
types, and xs:numeric
and both the
user-defined list types
and
user-defined union types
are special types in that these types are lists or unions
rather than types derived by extension or restriction.
The first diagram and its corresponding table illustrate the relationship of various item types.
Item types are used to characterize the various types of item that can appear in a sequence (nodes, atomic values, and functions), and they are therefore used in declaring the types of variables or the argument types and result types of functions.
Item types in the data model
form a directed graph, rather than a hierarchy or lattice: in the relationship defined
by the derived-from(A, B)
function, some types are derived
from more than one other type. Examples include functions (function(xs:string) as xs:int
is substitutable for function(xs:NCName) as xs:int
and also for
function(xs:string) as xs:decimal
), and union types (A
is substitutable for union(A, B)
and also for union(A, C)
.
In XDM, item types include node types, function types, and built-in atomic types.
The diagram, which shows only hierarchic relationships, is therefore a simplification
of
the full model.
In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.
| item | |||
| xs:anyAtomicType | |||
| node | |||
| attribute | |||
| user-defined attribute types | |||
| comment | |||
| document | |||
| user-defined document types | |||
| element | |||
| user-defined element types | |||
| namespace | |||
| processing-instruction | |||
| text | |||
| function(*) | |||
| array(*) | |||
| map(*) |
The next diagram and table illustrate the schema type subsystem, in which
all types are derived from the distinguished type xs:anyType
.
Schema types include built-in types defined in the XML Schema specification, and user-defined types defined using mechanisms described in the XML Schema specification. Schema types define the permitted contents of nodes. The main categories are complex types, which define the permitted content of elements, and simple types, which can be used to constrain the values of both elements and attributes.
In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.
| xs:anyType | |||
| xs:anySimpleType | |||
| xs:anyAtomicType | |||
| list types | |||
| xs:IDREFS | |||
| xs:NMTOKENS | |||
| xs:ENTITIES | |||
| user-defined list types | |||
| union types | |||
| xs:numeric | |||
| user-defined union types | |||
| complex types | |||
| xs:untyped | |||
| user-defined complex types |
The final diagram and table show all of the atomic types, including the primitive simple types and the built-in types derived from the primitive simple types. This includes all the built-in datatypes defined in [XML Schema Part 2: Datatypes Second Edition].
Atomic types are both item types and schema types, so the root type xs:anyAtomicType
may be found
in both the previous diagrams.
In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.
| xs:untypedAtomic | ||||||
| xs:dateTime | ||||||
| xs:dateTimeStamp | ||||||
| xs:date | ||||||
| xs:time | ||||||
| xs:duration | ||||||
| xs:yearMonthDuration | ||||||
| xs:dayTimeDuration | ||||||
| xs:float | ||||||
| xs:double | ||||||
| xs:decimal | ||||||
| xs:integer | ||||||
| xs:nonPositiveInteger | ||||||
| xs:negativeInteger | ||||||
| xs:long | ||||||
| xs:int | ||||||
| xs:short | ||||||
| xs:byte | ||||||
| xs:nonNegativeInteger | ||||||
| xs:unsignedLong | ||||||
| xs:unsignedInt | ||||||
| xs:unsignedShort | ||||||
| xs:unsignedByte | ||||||
| xs:positiveInteger | ||||||
| xs:gYearMonth | ||||||
| xs:gYear | ||||||
| xs:gMonthDay | ||||||
| xs:gDay | ||||||
| xs:gMonth | ||||||
| xs:string | ||||||
| xs:normalizedString | ||||||
| xs:token | ||||||
| xs:language | ||||||
| xs:NMTOKEN | ||||||
| xs:Name | ||||||
| xs:NCName | ||||||
| xs:ID | ||||||
| xs:IDREF | ||||||
| xs:ENTITY | ||||||
| xs:boolean | ||||||
| xs:base64Binary | ||||||
| xs:hexBinary | ||||||
| xs:anyURI | ||||||
| xs:QName | ||||||
| xs:NOTATION |
The terminology used to describe the functions and operators on types defined in [XML Schema Part 2: Datatypes Second Edition] is defined in the body of this specification. The terms defined in this section are used in building those definitions.
Note:
Following in the tradition of [XML Schema Part 2: Datatypes Second Edition], the terms type and datatype are used interchangeably.
This document uses the terms string
, character
, and codepoint
with meanings that are normatively defined in [XQuery and XPath Data Model (XDM) 3.1], and which are paraphrased here
for ease of reference:
[Definition] A character is an instance of the CharXML production of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].
Note:
This definition excludes Unicode characters in the surrogate blocks as well as xFFFE and xFFFF, while including characters with codepoints greater than xFFFF which some programming languages treat as two characters. The valid characters are defined by their codepoints, and include some whose codepoints have not been assigned by the Unicode consortium to any character.
[Definition] A string is a sequence of zero or more
·characters·, or equivalently,
a value in the value space of the xs:string
datatype.
[Definition] A codepoint is an integer assigned to a ·character· by the Unicode consortium, or reserved for future assignment to a character.
Note:
The set of codepoints is thus wider than the set of characters.
This specification spells "codepoint" as one word; the Unicode specification spells it as "code point". Equivalent terms found in other specifications are "character number" or "code position". See [Character Model for the World Wide Web 1.0: Fundamentals]
Because these terms appear so frequently, they are hyperlinked to the definition only when there is a particular desire to draw the reader's attention to the definition; the absence of a hyperlink does not mean that the term is being used in some other sense.
It is ·implementation-defined· which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used.
Unless explicitly stated, the xs:string
values returned by the
functions in this document are not normalized in the sense of [Character Model for the World Wide Web 1.0: Fundamentals].
Notes:
In functions that involve character counting such
as fn:substring
, fn:string-length
and
fn:translate
, what is counted is the number of XML ·characters·
in the string (or equivalently, the number of Unicode codepoints). Some
implementations may represent a codepoint above xFFFF using two 16-bit
values known as a surrogate pair. A surrogate pair counts as one character, not two.
This document uses the phrase "namespace URI" to identify the concept identified in [Namespaces in XML] as "namespace name", and the phrase "local name" to identify the concept identified in [Namespaces in XML] as "local part".
It also uses the term "expanded-QName" defined below.
[Definition] An expanded-QName
is a value in the value space of the xs:QName
datatype as defined in the XDM data model
(see [XQuery and XPath Data Model (XDM) 3.1]): that is, a triple containing namespace prefix (optional), namespace URI (optional),
and local name. Two expanded QNames are equal if the namespace URIs are the same (or
both absent)
and the local names are the same. The prefix plays no part in the comparison, but
is used only
if the expanded QName needs to be converted back to a string.
The term URI is used as follows:
[Definition] Within this specification, the term URI refers to Universal Resource Identifiers as
defined in [RFC 3986] and extended in [RFC 3987] with a new name IRI. The term URI
Reference, unless otherwise stated, refers to a string in the lexical space of the xs:anyURI
datatype
as defined in [XML Schema Part 2: Datatypes Second Edition].
Note:
Note that this means, in practice, that where this
specification requires a "URI Reference", an IRI as defined in [RFC 3987] will be
accepted, provided that other relevant specifications also permit an IRI. The term
URI has been
retained in preference to IRI to avoid introducing new names for concepts such as
"Base URI" that
are defined or referenced across the whole family of XML specifications. Note also
that the
definition of xs:anyURI
is a wider definition than the definition in [RFC 3987];
for example it does not require non-ASCII characters to be escaped.
In this specification:
The auxiliary verb must, when rendered in small capitals, indicates a precondition for conformance.
When the sentence relates to an implementation of a function (for example "All implementations must recognize URIs of the form ...") then an implementation is not conformant unless it behaves as stated.
When the sentence relates to the result of a function (for example "The result must have the same type as
$arg
") then the implementation is not conformant unless it delivers a result as stated.
When the sentence relates to the arguments to a function (for example "The value of
$arg
must
be a valid regular expression") then the implementation is not conformant unless it
enforces the condition by raising a dynamic error
whenever the condition is not satisfied.
The auxiliary verb may, when rendered in small capitals, indicates optional or discretionary behavior. The statement "An implementation may do X" implies that it is implementation-dependent whether or not it does X.
The auxiliary verb should, when rendered in small capitals, indicates desirable or recommended behavior. The statement "An implementation should do X" implies that it is desirable to do X, but implementations may choose to do otherwise if this is judged appropriate.
[Definition] Where behavior is described as implementation-defined, variations between processors are permitted, but a conformant implementation must document the choices it has made.
[Definition] Where behavior is described as implementation-dependent, variations between processors are permitted, and conformant implementations are not required to document the choices they have made.
Note:
Where this specification states that something is implementation-defined or implementation-dependent, it is open to host languages to place further constraints on the behavior.
This section is concerned with the question of whether two calls on a function, with the same arguments, may produce different results.
[Definition] An execution scope is a sequence of
calls to the function library during which certain aspects of the state are required
to remain invariant.
For example, two calls to fn:current-dateTime
within the same execution scope will return the same result.
The execution scope is defined by the host language that invokes the function library.
In XSLT, for example, any two function calls executed during
the same transformation are in the same execution scope (except that static expressions,
such as those used in
use-when
attributes, are in a separate execution scope).
The following definition explains more precisely what it means for two function calls to return the same result:
[Definition] Two values are defined to be identical if they contain the same number of items and the items are pairwise identical. Two items are identical if and only if one of the following conditions applies:
Both items are atomic values, of precisely the same type, and the values are equal
as defined using the eq
operator,
using the Unicode codepoint collation when comparing strings.
Both items are nodes, and represent the same node.
Both items are maps, both maps have the same number of entries, and for every entry E1 in the first map there is an entry E2 in the second map such that the keys of E1 and E2 are ·the same key·, and the corresponding values V1 and V2 are ·identical·.
Both items are arrays, both arrays have the same number of members, and the members are pairwise ·identical·.
Both items are function items, neither item is a map or array, and all the following conditions apply:
Either both functions have the same name, or both names are absentDM31.
Both functions have the same arity.
Both functions have the same function signature. Two
function signatures are defined to be the same if the declared result types are identical
and the declared
argument types are pairwise identical. Two types S and T are defined to be
identical if and only if subtype(S, T)
and subtype(T, S)
both hold, where the subtype relation is defined in Section
<IP_ADDRESS> The judgement subtype(A, B)
XP31.
Note:
Under this definition, a union type with memberTypes="xs:double xs:decimal"
is identical to a union type with memberTypes="xs:decimal xs:double"
. However, two functions
whose signatures differ in this way will probably be deemed non-identical under rule
(e) below, because they are likely to
have different effect when invoked with an argument of type xs:untypedAtomic
.
Both functions have the same nonlocal variable bindings (sometimes called the function's closure).
The processor is able to determine that the implementations of the two functions are equivalent, in the sense that for all possible combinations of arguments, the two functions have the same effect.
Note:
There is no function or operator defined in the specification that tests whether two function items are identical. Where the specification requires two function items to be identical, for example in the results of repeated calls of a function whose result is a function, then the processor must ensure that it returns functions that are indistinguishable in their observable effect. Where the specification defines behavior conditional on two function items being identical, the determination of identity is to some degree implementation-dependent. There are cases where function items are definitely not identical (for example if they have different name or arity), but positive determination of identity is possible only using implementation-dependent techniques, for example when both items contain references to the same piece of code representing the function's implementation.
Some functions produce results that depend not only on their explicit arguments, but also on the static and dynamic context.
[Definition] A function may have the property of being context-dependent: the result of such a function depends on the values of properties in the static and dynamic evaluation context as well as on the actual supplied arguments (if any).
[Definition] A function that is not ·context-dependent· is called context-independent.
A function that is context-dependent can be used as a named
function reference, can be partially applied, and can be found using fn:function-lookup
.
The principle in such cases is that the static context used for the function evaluation
is taken from the static context of the named function reference, partial function
application, or the call
on fn:function-lookup
; and the dynamic context for the function evaluation is taken from the dynamic
context of the evaluation of the named function reference, partial function application,
or the call
of fn:function-lookup
. In effect, the static and dynamic part of the context thus act
as part of the closure of the function item.
Context-dependent functions fall into a number of categories:
The functions fn:current-date
, fn:current-dateTime
, fn:current-time
,
fn:default-language
, fn:implicit-timezone
,
fn:adjust-date-to-timezone
, fn:adjust-dateTime-to-timezone
, and
fn:adjust-time-to-timezone
depend on properties of the dynamic context that are
fixed within the ·execution scope·. The same applies to a
number of functions in the op:
namespace that manipulate dates and times and
that make use of the implicit timezone. These functions will return the same
result if called repeatedly during a single ·execution scope·.
A number of functions including fn:base-uri#0
, fn:data#0
,
fn:document-uri#0
, fn:element-with-id#1
, fn:id#1
,
fn:idref#1
, fn:lang#1
, fn:last#0
, fn:local-name#0
,
fn:name#0
, fn:namespace-uri#0
, fn:normalize-space#0
,
fn:number#0
, fn:path#0
, fn:position#0
,
fn:root#0
, fn:string#0
, and
fn:string-length#0
depend on the focusXP31.
These functions will in general return
different results on different calls if the focus is different.
[Definition] A function is focus-dependent if its result depends on the focusXP31 (that is, the context item, position, or size).
[Definition] A function that is not ·focus-dependent· is called focus-independent
The function fn:default-collation
and many string-handling operators and functions depend
on the default collation and the in-scope collations, which are both properties
of the static context. If a particular call of one of these functions is
evaluated twice with the same arguments then it will return the same result
each time (because the static context, by definition, does not change at run
time). However, two distinct calls (that is, two calls on the function
appearing in different places in the source code) may produce different results
even if the explicit arguments are the same.
Functions such as fn:static-base-uri
, fn:doc
, and fn:collection
depend on
other aspects of the static context. As with functions that depend on
collations, a single call will produce the same results on each call if the
explicit arguments are the same, but two calls appearing in different places in
the source code may produce different results.
The fn:function-lookup
function is a special case because it is
potentially dependent on everything in the static and dynamic context. This is because
the static and dynamic
context of the call to fn:function-lookup
are used as the static and dynamic context of the
function that fn:function-lookup
returns.
[Definition] For a ·context-dependent· function, the parts of the context on which it depends are referred to as implicit arguments.
[Definition] A function that is guaranteed to produce ·identical· results from repeated calls within a single ·execution scope· if the explicit and implicit arguments are identical is referred to as deterministic.
[Definition] A function that is not ·deterministic· is referred to as nondeterministic.
All functions defined in this specification are ·deterministic· unless otherwise stated. Exceptions include the following:
[Definition] Some
functions (such as fn:distinct-values
, fn:unordered
, map:keys
,
and map:for-each
) produce results in an
·implementation-defined· or
·implementation-dependent· order.
In such cases two calls with the same arguments are not guaranteed to produce the
results in the same order. These functions are
said to be nondeterministic with respect to ordering.
Some functions (such as fn:analyze-string
,
fn:parse-xml
, fn:parse-xml-fragment
, and fn:json-to-xml
)
construct a tree of nodes to
represent their results. There is no guarantee that repeated calls with the same
arguments will return the same identical node (in the sense of the is
operator). However, if non-identical nodes are returned, their content will be the
same in the sense of the fn:deep-equal
function. Such a function is said
to be non-deterministic with respect to node identity.
Some functions (such as fn:doc
and fn:collection
) create new nodes by reading external
documents. Such functions are guaranteed to be ·deterministic· with the exception that
an implementation is allowed to make them non-deterministic as a user option.
Where the results of a function are described as being (to a greater or lesser extent) ·implementation-defined· or ·implementation-dependent·, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results.
Accessors and their semantics are described in [XQuery and XPath Data Model (XDM) 3.1]. Some of these accessors are exposed to the user through the functions described below.
Each of these functions has an arity-zero signature which is equivalent to the arity-one
form, with the context item supplied as the implicit first argument. In addition,
each of the
arity-one functions accepts an empty sequence as the argument, in which case it generally
delivers
an empty sequence as the result: the exception is fn:string
, which delivers
a zero-length string.
| Function | Accessor | Accepts | Returns |
|---|---|---|---|
fn:node-name
|
node-name
|
node (optional) | xs:QName (optional)
|
fn:nilled
|
nilled
|
node (optional) | xs:boolean (optional)
|
fn:string
|
string-value
|
item (optional) |
xs:string
|
fn:data
|
typed-value
|
zero or more items | a sequence of atomic values |
fn:base-uri
|
base-uri
|
node (optional) | xs:anyURI (optional)
|
fn:document-uri
|
document-uri
|
node (optional) | xs:anyURI (optional)
|
Returns the name of a node, as an xs:QName
.
fn:node-name
() as
xs:QName?
fn:node-name
($arg
as
node()?
) as
xs:QName?
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 $arg
is the empty sequence, the empty sequence is returned.
Otherwise, the function returns the result of the dm:node-name
accessor as
defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section
5.10 node-name Accessor
DM31).
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.
For element and attribute nodes, the name of the node is returned as an
xs:QName
, retaining the prefix, namespace URI, and local part.
For processing instructions, the name of the node is returned as an
xs:QName
in which the prefix and namespace URI are absentDM31.
For a namespace node, the function returns an empty sequence if the node represents
the
default namespace; otherwise it returns an xs:QName
in which prefix and
namespace URI are absentDM31 and the local
part is the namespace prefix being bound.
For all other kinds of node, the function returns the empty sequence.
Returns true for an element that is nilled.
fn:nilled
() as
xs:boolean?
fn:nilled
($arg
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.
If $arg
is the empty sequence, the function returns the empty sequence.
Otherwise the function returns the result of the dm:nilled
accessor as
defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section
5.8 nilled Accessor
DM31).
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.
If $arg
is not an element node, the function returns the empty
sequence.
If $arg
is an untyped element node, the function returns false.
In practice, the function returns true
only for an element node that has
the attribute xsi:nil="true"
and that is successfully validated against a
schema that defines the element to be nillable; the detailed rules, however, are defined
in [XQuery and XPath Data Model (XDM) 3.1].
Returns the value of $arg
represented as an xs:string
.
fn:string
() as
xs:string
fn:string
($arg
as
item()?
) 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·.
In the zero-argument version of the function, $arg
defaults to the context
item. That is, calling fn:string()
is equivalent to calling
fn:string(.)
.
If $arg
is the empty sequence, the function returns the zero-length
string.
If $arg is a node, the function returns the string value of the node, as obtained using the
dm:string-value
accessor defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section
5.12 string-value Accessor
DM31).
If $arg is an atomic value, the function returns the result of the expression $arg cast
as xs:string
(see 19 Casting).
In all other cases, a dynamic error occurs (see below).
A dynamic error is raised [err:XPDY0002]XP31 by the zero-argument version of the function if the context item is absentDM31.
A type error is raised [err:FOTY0014] if
$arg
is a function item (this includes maps and arrays).
Every node has a string value, even an element with element-only content (which has no typed value). Moreover, casting an atomic value to a string always succeeds. Functions, maps, and arrays have no string value, so these are the only arguments that satisfy the type signature but cause failure.
The expression string(23)
returns "23"
.
The expression string(false())
returns "false"
.
The expression string("Paris")
returns "Paris"
.
The expression string((1, 2, 3))
raises error XPTY0004
.
The expression string([[1, 2], [3, 4]])
raises error FOTY0014
.
The expression string(abs#1)
raises error FOTY0014
.
let $para := <para>In a hole in the ground there lived a <term author="Tolkien">hobbit</term>.</para>
The expression string($para)
returns "In a hole in the ground there lived a hobbit."
.
Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values.
fn:data
() as
xs:anyAtomicType*
fn:data
($arg
as
item()*
) as
xs:anyAtomicType*
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.
The result of fn:data
is the sequence of atomic values produced by
applying the following rules to each item in $arg
:
If the item is an atomic value, it is appended to the result sequence.
If the item is a node, the typed value of the node is appended to the result
sequence. The typed value is a sequence of zero or more atomic values:
specifically, the result of the dm:typed-value
accessor as defined in
[XQuery and XPath Data Model (XDM) 3.1] (See Section
5.14 typed-value Accessor
DM31).
If the item is an array, the result of applying fn:data
to
each member of the array, in order, is appended to the result sequence.
A type error is raised [err:FOTY0012] if an item in the
sequence $arg
is a node that does not have a typed value.
A type error is raised [err:FOTY0013] if an item in
the sequence $arg
is a function item other than
an array.
A dynamic error is raised if $arg
is omitted and the context item is
absentDM31.
The process of applying the fn:data
function to a sequence is referred to
as atomization
. In many cases an explicit call on fn:data
is
not required, because atomization is invoked implicitly when a node or sequence of
nodes
is supplied in a context where an atomic value or sequence of atomic values is
required.
The result of atomizing an empty sequence is an empty sequence.
The result of atomizing an empty array is an empty sequence.
The expression data(123)
returns 123
.
The expression data((123, 456))
returns 123, 456
.
The expression data([[1,2],[3,4]])
returns 1, 2, 3, 4
.
let $para := <para>In a hole in the ground there lived a <term author="Tolkien">hobbit</term>.</para>
The expression data($para)
returns xs:untypedAtomic("In a hole in the ground there lived a hobbit.")
.
The expression data($para/term/@author)
returns xs:untypedAtomic("Tolkien")
.
The expression data(abs#1)
raises error FOTY0013
.
Returns the base URI of a node.
fn:base-uri
() as
xs:anyURI?
fn:base-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·.
The zero-argument version of the function returns the base URI of the context node:
it
is equivalent to calling fn:base-uri(.)
.
The single-argument version of the function behaves as follows:
$arg
is the empty sequence, the function returns the empty
sequence.
dm:base-uri
accessor
applied to the node $arg
. This accessor is defined, for each kind of
node, in the XDM specification (See Section
5.2 base-uri Accessor
DM31).
Note:
As explained in XDM, document, element and processing-instruction nodes have a base-uri property which may be empty. The base-uri property for all other node kinds is the empty sequence. The dm:base-uri accessor returns the base-uri property of a node if it exists and is non-empty; otherwise it returns the result of applying the dm:base-uri accessor to its parent, recursively. If the node does not have a parent, or if the recursive ascent up the ancestor chain encounters a parentless node whose base-uri property is empty, the empty sequence is returned. In the case of namespace nodes, however, the result is always an empty sequence — it does not depend on the base URI of the parent element.See also fn:static-base-uri
.
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 URI of a resource where a document can be found, if available.
fn:document-uri
() as
xs:anyURI?
fn:document-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 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 $arg
is the empty sequence, the function returns the empty sequence.
If $arg
is not a document node, the function returns the empty
sequence.
Otherwise, the function returns the value of the document-uri
accessor
applied to $arg
, as defined in [XQuery and XPath Data Model (XDM) 3.1] (See
Section
6.1.2 Accessors
DM31).
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.
In the case of a document node $D
returned by the fn:doc
function, or a document node at the root of a tree containing a node returned by the
fn:collection
function, it will always be true that either
fn:document-uri($D)
returns the empty sequence, or that the following
expression is true: fn:doc(fn:document-uri($D))
is $D
. It is
·implementation-defined· whether this guarantee also holds for
document nodes obtained by other means, for example a document node passed as the
initial context node of a query or transformation.
In this document, as well as in [XQuery 3.1: An XML Query Language] and [XML Path Language (XPath) 3.1],
the phrase "an error is raised"
is used. Raising an error is equivalent to calling the fn:error
function defined in this section with the provided error code. Except
where otherwise
specified, errors defined in this specification are dynamic errors.
Some errors,
however, are classified as type errors. Type errors are typically
used where the presence
of the error can be inferred from knowledge of the type of the actual arguments
to a function, for
example with a call such as fn:string(fn:abs#1)
. Host languages may allow type errors
to be reported statically if they are discovered during static analysis.
When function specifications indicate that an error is to be raised, the notation
"[error code]". os used to specify an error code. Each error defined
in this document is identified by an xs:QName
that is in the
http://www.w3.org/2005/xqt-errors
namespace, represented in this document by the err
prefix. It is this
xs:QName
that is actually passed as an argument to the
fn:error
function. Calling this function raises an error. For a
more detailed treatment of error handing, see Section
2.3.3 Handling Dynamic Errors
XP31.
The fn:error
function is a general function that may be called as above
but may also be called from [XQuery 3.1: An XML Query Language] or [XML Path Language (XPath) 3.1]
applications with, for example, an xs:QName
argument.
Calling the fn:error
function raises an application-defined error.
fn:error
() as
none
fn:error
($code
as
xs:QName?
) as
none
fn:error
($code
as
xs:QName?
, $description
as
xs:string
) as
none
fn:error (
|
$code |
as xs:QName? ,
|
$description |
as xs:string ,
|
|
$error-object |
as item()* ) as none |
This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.
This function never returns a value. Instead it always raises an error. The effect of the error is identical to the effect of dynamic errors raised implicitly, for example when an incorrect argument is supplied to a function.
The parameters to the fn:error
function supply information that is
associated with the error condition and that is made available to a caller that asks
for
information about the error. The error may be caught either by the host language (using
a try/catch construct in XSLT or XQuery, for example), or by the calling application
or
external processing environment. The way in which error information is returned to
the
external processing environment is ·implementation-dependent·.
There are three pieces of information that may be associated with an error:
The $code
is an error code that distinguishes this error from others.
It is an xs:QName
; the namespace URI conventionally identifies the
component, subsystem, or authority responsible for defining the meaning of the
error code, while the local part identifies the specific error condition. The
namespace URI http://www.w3.org/2005/xqt-errors
is used for errors
defined in this specification; other namespace URIs may be used for errors defined
by the application.
If the external processing environment expects the error code to be returned as a
URI or a string rather than as an xs:QName
, then an error code with
namespace URI NS
and local part LP
will be returned in
the form NS#LP
. The namespace URI part of the error code should
therefore not include a fragment identifier.
If no value is supplied for the $code
argument (that is,
if the function is called with no arguments or if the first argument is an empty sequence),
the effective value of the error code is fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000')
.
The $description
is a natural-language description of the error
condition.
If no value is supplied for the $description
argument (that is, if the function is called with less than two arguments), then the
effective value of the description is ·implementation-dependent·.
The $error-object
is an arbitrary value used to convey additional
information about the error, and may be used in any way the application
chooses.
If no value is supplied for the $error-object
argument (that is, if the function is called with less than three arguments), then
the
effective value of the error object is ·implementation-dependent·.
This function always raises a dynamic error. By default, it raises [err:FOER0000]
The value of the $description
parameter may need to be localized.
The type "none" is a special type defined in [XQuery 1.0 and XPath 2.0 Formal Semantics] and is not available to the user. It indicates that the function never returns and ensures that it has the correct static type.
Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.
The expression fn:error()
raises error FOER0000
. (This returns the URI
http://www.w3.org/2005/xqt-errors#FOER0000
(or the corresponding
xs:QName
) to the external processing environment, unless the error
is caught using a try/catch construct in the host language.)
The expression fn:error(fn:QName('http://www.example.com/HR', 'myerr:toohighsal'),
'Does not apply because salary is too high')
raises error myerr:toohighsal
. (This returns http://www.example.com/HR#toohighsal
and the
xs:string
"Does not apply because salary is too high"
(or the corresponding
xs:QName
) to the external processing environment, unless the error
is caught using a try/catch construct in the host language.)
Provides an execution trace intended to be used in debugging queries.
fn:trace
($value
as
item()*
) as
item()*
fn:trace
($value
as
item()*
, $label
as
xs:string
) as
item()*
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns the value of $value
, unchanged.
In addition, the values of $value
, converted to an xs:string
,
and $label
(if supplied)
may be directed to a trace data set. The destination of the trace
output is ·implementation-defined·. The format of the trace output is
·implementation-dependent·. The ordering of output from calls of the
fn:trace
function is ·implementation-dependent·.
Sometimes there is a need to output trace information unrelated to a specific value.
In such cases it can be useful to set $value
to an empty string or an empty
sequence, and to compute the value of the $label
argument:
fn:trace((), "Processing item " || $i)
.
Consider a situation in which a user wants to investigate the actual value passed
to
a function. Assume that in a particular execution, $v
is an
xs:decimal
with value 124.84
. Writing fn:trace($v,
'the value of $v is:')
will put the strings "124.84"
and
"the value of $v is:"
in the trace data set in implementation
dependent order.
This section specifies arithmetic operators on the numeric datatypes defined in [XML Schema Part 2: Datatypes Second Edition].
The operators described in this section are defined on the following atomic types. Each type whose name is indented is derived from the type whose name appears nearest above with one less level of indentation.
| xs:decimal | |
| xs:integer | |
| xs:float | |
| xs:double |
They also apply to types derived by restriction from the above types.
The type xs:numeric
is defined as a union type whose member types are
(in order) xs:double
, xs:float
, and xs:decimal
. This type is implicitly imported
into the static context, so it can also be used in defining the signature of user-written
functions. Apart from the fact that
it is implicitly imported, it behaves exactly like a user-defined type with the same
definition. This means, for example:
If the expected type of a function parameter is given as xs:numeric
, the actual value supplied
can be an instance of any of these three types, or any type derived from these three
by restriction (this includes the built-in
type xs:integer
, which is derived from xs:decimal
).
If the expected type of a function parameter is given as xs:numeric
, and the actual value supplied
is xs:untypedAtomic
(or a node whose atomized value is xs:untypedAtomic
), then it will
be cast to the union type xs:numeric
using the rules in 19.3.5 Casting to union types.
Because the lexical space of xs:double
subsumes the lexical space of the other member types, and
xs:double
is listed first, the effect is that if the untyped atomic value is in the lexical
space of
xs:double
, it will be converted to an xs:double
, and if not, a dynamic error occurs.
When the return type of a function is given as xs:numeric
, the actual value returned will be
an instance of one of the three member types (and perhaps also of types derived from
these by restriction). The rules
for the particular function will specify how the type of the result depends on the
values supplied as arguments.
In many cases, for the functions in this specification, the result is defined to be
the same type as the first
argument.
Note:
This specification uses [IEEE 754-2008] arithmetic for xs:float
and xs:double
values.
One consequence of this is that some operations result in the value NaN
(not-a number), which
has the unusual property that it is not equal to itself. Another consequence is that
some operations return the value negative zero.
This differs from [XML Schema Part 2: Datatypes Second Edition] which defines
NaN
as being equal to itself and defines only a single zero in the value space.
The text accompanying several functions defines behavior for both positive and negative
zero inputs and outputs
in the interest of alignment with [IEEE 754-2008]. A conformant implementation must
respect these semantics. In consequence, the expression -0.0e0
(which is actually a unary minus operator
applied to an xs:double
value) will always return negative zero: see 4.2.8 op:numeric-unary-minus.
As a concession to implementations that rely on implementations of XSD 1.0, however,
when casting from string to double
the lexical form -0
may be converted to positive zero, though negative zero
is recommended.
XML Schema 1.1 introduces support for positive and negative zero as distinct values,
and also uses the [IEEE 754-2008]
semantics for comparisons involving NaN
.
The following functions define the semantics of arithmetic operators defined in [XQuery 3.1: An XML Query Language] and [XML Path Language (XPath) 3.1] on these numeric types.
| Operator | Meaning |
|---|---|
op:numeric-add
|
Addition |
op:numeric-subtract
|
Subtraction |
op:numeric-multiply
|
Multiplication |
op:numeric-divide
|
Division |
op:numeric-integer-divide
|
Integer division |
op:numeric-mod
|
Modulus |
op:numeric-unary-plus
|
Unary plus |
op:numeric-unary-minus
|
Unary minus (negation) |
The parameters and return types for the above operators are in most cases declared
to be of type
xs:numeric
, which permits the basic numeric
types: xs:integer
, xs:decimal
, xs:float
and xs:double
, and types derived from them.
In general the two-argument functions require that both arguments are of the same
primitive type,
and they return a value of this same type.
The exceptions are op:numeric-divide
, which returns
an xs:decimal
if called with two xs:integer
operands,
and op:numeric-integer-divide
which always returns an xs:integer
.
If the two operands of an arithmetic expression are not of the same type, subtype substitution and numeric type promotion are used to obtain two operands of the same type. Section B.1 Type Promotion XP31 and Section B.2 Operator Mapping XP31 describe the semantics of these operations in detail.
The result type of operations depends on their argument datatypes and is defined in the following table:
| Operator | Returns |
|---|---|
op:operation(xs:integer, xs:integer)
|
xs:integer (except for op:numeric-divide(integer,
integer) , which returns xs:decimal )
|
op:operation(xs:decimal, xs:decimal)
|
xs:decimal
|
op:operation(xs:float, xs:float)
|
xs:float
|
op:operation(xs:double, xs:double)
|
xs:double
|
op:operation(xs:integer)
|
xs:integer
|
op:operation(xs:decimal)
|
xs:decimal
|
op:operation(xs:float)
|
xs:float
|
op:operation(xs:double)
|
xs:double
|
These rules define any operation on any pair of arithmetic types. Consider the following example:
op:operation(xs:int, xs:double) => op:operation(xs:double, xs:double)
For this operation, xs:int
must be converted to
xs:double
. This can be done, since by the rules above:
xs:int
can be substituted for xs:integer
,
xs:integer
can be substituted for xs:decimal
,
xs:decimal
can be promoted to xs:double
. As far as possible, the promotions should be done in a
single step. Specifically, when an xs:decimal
is promoted to an
xs:double
, it should not be converted to an xs:float
and then to xs:double
, as this risks loss of precision.
As another example, a user may define height
as a derived type of
xs:integer
with a minimum value of 20 and a maximum value of 100.
They may then derive fenceHeight
using an enumeration to restrict the
permitted set of values to, say, 36, 48 and 60.
op:operation(fenceHeight, xs:integer) => op:operation(xs:integer, xs:integer)
fenceHeight
can be substituted for its base type
height
and height
can be substituted for its base type
xs:integer
.
The basic rules for addition, subtraction, and multiplication
of ordinary numbers are not set out in this specification; they are taken as given.
In the case of xs:double
and xs:float
the rules are as defined in [IEEE 754-2008]. The rules for handling
division and modulus operations, as well as the rules for handling special values
such as infinity and NaN
,
and exception conditions such as overflow and underflow, are described more explicitly
since they are not necessarily obvious.
On overflow and underflow situations during arithmetic operations conforming implementations must behave as follows:
For xs:float
and xs:double
operations, overflow
behavior must be conformant with [IEEE 754-2008]. This specification allows the following options:
Raising a dynamic error [err:FOAR0002] via an overflow trap.
Returning INF
or -INF
.
Returning the largest (positive or negative) non-infinite number.
For xs:float
and xs:double
operations,
underflow behavior must be conformant with [IEEE 754-2008]. This specification allows the following options:
Raising a dynamic error [err:FOAR0002] via an underflow trap.
Returning 0.0E0
or +/- 2**Emin
or a
denormalized value; where Emin
is the smallest
possible xs:float
or xs:double
exponent.
For xs:decimal
operations, overflow behavior must
raise a dynamic error [err:FOAR0002]. On
underflow, 0.0
must be returned.
For xs:integer
operations, implementations that support
limited-precision integer operations must select from
the following options:
They may choose to always raise a dynamic error [err:FOAR0002].
They may provide an ·implementation-defined· mechanism that allows users to choose between raising an error and returning a result that is modulo the largest representable integer value. See [ISO 10967].
The functions op:numeric-add
, op:numeric-subtract
,
op:numeric-multiply
, op:numeric-divide
,
op:numeric-integer-divide
and op:numeric-mod
are each
defined for pairs of numeric operands, each of which has the same
type:xs:integer
, xs:decimal
, xs:float
, or
xs:double
. The functions op:numeric-unary-plus
and
op:numeric-unary-minus
are defined for a single operand whose type
is one of those same numeric types.
For xs:float
and xs:double
arguments, if either
argument is NaN
, the result is NaN
.
For xs:decimal
values, let N be the number of digits
of precision supported by the implementation, and let M (M <= N
) be the minimum limit on the number of digits
required for conformance (18 digits for XSD 1.0, 16 digits for XSD 1.1). Then for
addition, subtraction, and multiplication
operations, the returned result should be accurate to N digits of precision, and for division and modulus operations,
the returned result should be accurate to at least M digits of precision.
The actual precision is ·implementation-defined·. If the number
of digits in the mathematical result exceeds the number of digits that the implementation
retains for that operation, the result is truncated or rounded in an ·implementation-defined· manner.
Note:
This Recommendation does not specify whether xs:decimal
operations are fixed point or floating point.
In an implementation using floating point it is possible for very simple operations
to require more digits of precision than
are available; for example adding 1e100
to 1e-100
requires 200 digits of precision for an
accurate representation of the result.
The [IEEE 754-2008] specification also describes handling of
two exception conditions called divideByZero
and invalidOperation
. The
IEEE divideByZero
exception is raised not only by a direct attempt to divide by zero, but also by
operations such as log(0)
. The IEEE invalidOperation
exception is raised by
attempts to call a function with an argument that is outside the function's domain
(for example,
sqrt(-1)
or log(-1)
).
Although IEEE defines these as exceptions, it also defines "default non-stop exception
handling" in
which the operation returns a defined result, typically positive or negative infinity,
or NaN. With this
function library,
these IEEE exceptions do not cause a dynamic error
at the application level; rather they result in the relevant function or operator
returning
the defined non-error result.
The underlying IEEE exception may be notified to the application
or to the user by some ·implementation-defined·
warning condition, but the observable effect on an application
using the functions and operators defined in this specification is simply to return
the defined
result (typically -INF, +INF, or NaN) with no error.
The [IEEE 754-2008] specification distinguishes two NaN values,
a quiet NaN and a signaling NaN. These two values are not distinguishable in the XDM
model:
the value spaces of xs:float
and xs:double
each include only a single
NaN
value. This does not prevent the implementation distinguishing them internally,
and triggering different ·implementation-defined·
warning conditions, but such distinctions do not affect the observable behavior of
an application
using the functions and operators defined in this specification.
Returns the arithmetic sum of its operands: ($arg1 + $arg2
).
Defines the semantics of the "+" operator when applied to two numeric values
op:numeric-add
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs:numeric
General rules: see 4.2 Arithmetic operators on numeric values.
For xs:float
or xs:double
values, if one of the operands is a
zero or a finite number and the other is INF
or -INF
,
INF
or -INF
is returned. If both operands are
INF
, INF
is returned. If both operands are
-INF
, -INF
is returned. If one of the operands is
INF
and the other is -INF
, NaN
is
returned.
Returns the arithmetic difference of its operands: ($arg1 - $arg2
).
Defines the semantics of the "-" operator when applied to two numeric values.
op:numeric-subtract
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs:numeric
General rules: see 4.2 Arithmetic operators on numeric values.
For xs:float
or xs:double
values, if one of the operands is a
zero or a finite number and the other is INF
or -INF
, an
infinity of the appropriate sign is returned. If both operands are INF
or
-INF
, NaN
is returned. If one of the operands is
INF
and the other is -INF
, an infinity of the appropriate
sign is returned.
Returns the arithmetic product of its operands: ($arg1 * $arg2
).
Defines the semantics of the "*" operator when applied to two numeric values.
op:numeric-multiply
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs:numeric
General rules: see 4.2 Arithmetic operators on numeric values.
For xs:float
or xs:double
values, if one of the operands is a
zero and the other is an infinity, NaN
is returned. If one of the operands
is a non-zero number and the other is an infinity, an infinity with the appropriate
sign
is returned.
Returns the arithmetic quotient of its operands: ($arg1 div $arg2
).
Defines the semantics of the "div" operator when applied to two numeric values.
op:numeric-divide
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs:numeric
General rules: see 4.2 Arithmetic operators on numeric values.
As a special case, if the types of both $arg1
and $arg2
are
xs:integer
, then the return type is xs:decimal
.
A dynamic error is raised [err:FOAR0001] for xs:decimal
and xs:integer
operands, if the divisor is (positive or negative) zero.
For xs:float
and xs:double
operands, floating point division
is performed as specified in [IEEE 754-2008]. A positive number divided by
positive zero returns INF
. A negative number divided by positive zero
returns -INF
. Division by negative zero returns -INF
and
INF
, respectively. Positive or negative zero divided by positive or
negative zero returns NaN
. Also, INF
or -INF
divided by INF
or -INF
returns NaN
.
Performs an integer division.
Defines the semantics of the "idiv" operator when applied to two numeric values.
op:numeric-integer-divide (
|
$arg1 |
as xs:numeric ,
|
$arg2 |
as xs:numeric ) as xs:integer |
General rules: see 4.2 Arithmetic operators on numeric values.
If $arg2
is INF
or -INF
, and $arg1
is not INF
or -INF
, then the result is zero.
Otherwise, subject to limits of precision and overflow/underflow conditions, the result
is the largest (furthest from zero) xs:integer
value $N
such
that the following expression is true:
fn:abs($N * $arg2) le fn:abs($arg1) and fn:compare($N * $arg2, 0) eq fn:compare($arg1, 0).
Note:
The second term in this condition ensures that the result has the correct sign.
The implementation may adopt a different algorithm provided that it is equivalent
to
this formulation in all cases where ·implementation-dependent· or ·implementation-defined· behavior does not affect the outcome, for example,
the implementation-defined precision of the result of xs:decimal
division.
A dynamic error is raised [err:FOAR0001] if the divisor is (positive or negative) zero.
A dynamic error is raised [err:FOAR0002] if either operand is
NaN
or if $arg1
is INF
or
-INF
.
Except in situations involving errors, loss of precision, or overflow/underflow, the
result of $a idiv $b
is the same as ($a div $b) cast as
xs:integer
.
The semantics of this function are different from integer division as defined in programming languages such as Java and C++.
The expression op:numeric-integer-divide(10,3)
returns 3
.
The expression op:numeric-integer-divide(3,-2)
returns -1
.
The expression op:numeric-integer-divide(-3,2)
returns -1
.
The expression op:numeric-integer-divide(-3,-2)
returns 1
.
The expression op:numeric-integer-divide(9.0,3)
returns 3
.
The expression op:numeric-integer-divide(-3.5,3)
returns -1
.
The expression op:numeric-integer-divide(3.0,4)
returns 0
.
The expression op:numeric-integer-divide(3.1E1,6)
returns 5
.
The expression op:numeric-integer-divide(3.1E1,7)
returns 4
.
Returns the remainder resulting from dividing $arg1
, the dividend, by
$arg2
, the divisor.
Defines the semantics of the "mod" operator when applied to two numeric values.
op:numeric-mod
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs:numeric
General rules: see 4.2 Arithmetic operators on numeric values.
The operation a mod b
for operands that are xs:integer
or
xs:decimal
, or types derived from them, produces a result such that
(a idiv b)*b+(a mod b)
is equal to a
and the magnitude of
the result is always less than the magnitude of b
. This identity holds even
in the special case that the dividend is the negative integer of largest possible
magnitude for its type and the divisor is -1 (the remainder is 0). It follows from
this
rule that the sign of the result is the sign of the dividend.
For xs:float
and xs:double
operands the following rules
apply:
If either operand is NaN
, the result is NaN
.
If the dividend is positive or negative infinity, or the divisor is positive or
negative zero (0), or both, the result is NaN
.
If the dividend is finite and the divisor is an infinity, the result equals the dividend.
If the dividend is positive or negative zero and the divisor is finite, the result is the same as the dividend.
In the remaining cases, where neither positive or negative infinity, nor positive
or negative zero, nor NaN
is involved, the result obeys (a idiv
b)*b+(a mod b)
= a
.
Division is truncating division, analogous to integer division, not [IEEE 754-2008] rounding division i.e. additional digits are truncated,
not rounded to the required precision.
A dynamic error is raised [err:FOAR0001] for xs:integer
and xs:decimal
operands, if $arg2
is zero.
The expression op:numeric-mod(10,3)
returns 1
.
The expression op:numeric-mod(6,-2)
returns 0
.
The expression op:numeric-mod(4.5,1.2)
returns 0.9
.
The expression op:numeric-mod(1.23E2, 0.6E1)
returns 3.0E0
.
Returns its operand with the sign unchanged: (+ $arg
).
Defines the semantics of the unary "+" operator applied to a numeric value.
op:numeric-unary-plus
($arg
as
xs:numeric
) as
xs:numeric
General rules: see 4.2 Arithmetic operators on numeric values.
The returned value is equal to $arg
, and is an instance of
xs:integer
, xs:decimal
, xs:double
, or
xs:float
depending on the type of $arg
.
Because function conversion rules are applied in the normal way, the unary
+
operator can be used to force conversion of an untyped node to a
number: the result of +@price
is the same as xs:double(@price)
if the type of @price
is xs:untypedAtomic
.
Returns its operand with the sign reversed: (- $arg
).
Defines the semantics of the unary "-" operator when applied to a numeric value.
op:numeric-unary-minus
($arg
as
xs:numeric
) as
xs:numeric
General rules: see 4.2 Arithmetic operators on numeric values.
The returned value is an instance of xs:integer
, xs:decimal
,
xs:double
, or xs:float
depending on the type of
$arg
.
For xs:integer
and xs:decimal
arguments, 0
and
0.0
return 0
and 0.0
, respectively. For
xs:float
and xs:double
arguments, NaN
returns
NaN
, 0.0E0
returns -0.0E0
and vice versa.
INF
returns -INF
. -INF
returns
INF
.
This specification defines the following comparison operators on numeric values.
Comparisons take two arguments of the same type. If the arguments are of
different types, one argument is promoted to the type of the other as described
above in 4.2 Arithmetic operators on numeric values. Each comparison operator returns a boolean
value. If either, or both, operands are NaN
, false
is
returned.
| Function | Meaning |
|---|---|
op:numeric-equal |
Returns true if and only if the value of $arg1 is equal to the value of
$arg2 .
|
op:numeric-less-than |
Returns true if and only if $arg1 is numerically less than
$arg2 .
|
op:numeric-greater-than |
Returns true if and only if $arg1 is numerically greater than
$arg2 .
|
Returns true if and only if the value of $arg1
is equal to the value of
$arg2
.
Defines the semantics of the "eq" operator when applied to two numeric values, and is also used in defining the semantics of "ne", "le" and "ge".
op:numeric-equal
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs:boolean
General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.
For xs:float
and xs:double
values, positive zero and negative
zero compare equal. INF
equals INF
, and -INF
equals -INF
. NaN
does not equal itself.
Returns true
if and only if $arg1
is numerically less than
$arg2
.
Defines the semantics of the "lt" operator when applied to two numeric values, and is also used in defining the semantics of "le".
op:numeric-less-than
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs:boolean
General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.
For xs:float
and xs:double
values, positive infinity is
greater than all other non-NaN
values; negative infinity is less than all
other non-NaN
values. If $arg1
or $arg2
is
NaN
, the function returns false
.
Returns true
if and only if $arg1
is numerically greater than
$arg2
.
Defines the semantics of the "gt" operator when applied to two numeric values, and is also used in defining the semantics of "ge".
op:numeric-greater-than
($arg1
as
xs:numeric
, $arg2
as
xs:numeric
) as
xs:boolean
The function call op:numeric-greater-than($A, $B)
is defined to return the
same result as op:numeric-less-than($B, $A)
The following functions are defined on numeric types. Each function returns a value of the same type as the type of its argument.
If the argument is the empty sequence, the empty sequence is returned.
For xs:float
and xs:double
arguments, if the
argument is "NaN", "NaN" is returned.
Except for fn:abs
, for xs:float
and
xs:double
arguments, if the argument is positive or
negative infinity, positive or negative infinity is returned.
| Function | Meaning |
|---|---|
fn:abs |
Returns the absolute value of $arg .
|
fn:ceiling |
Rounds $arg upwards to a whole number.
|
fn:floor |
Rounds $arg downwards to a whole number.
|
fn:round |
Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near. |
fn:round-half-to-even |
Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near. |
Note:
fn:round
and fn:round-half-to-even
produce the same result in all cases
except when the argument is exactly midway between two values with the required precision.
Other ways of rounding midway values can be achieved as follows:
Towards negative infinity: -fn:round(-$x)
Away from zero: fn:round(fn:abs($x))*fn:compare($x,0)
Towards zero: fn:abs(fn:round(-$x))*-fn:compare($x,0)
Returns the absolute value of $arg
.
fn:abs
($arg
as
xs:numeric?
) as
xs:numeric?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
If $arg
is negative the function returns -$arg
, otherwise it
returns $arg
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $arg
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example,
if
$arg
is an instance of xs:positiveInteger
then the value of
$arg
may be returned unchanged.
For xs:float
and xs:double
arguments, if the argument is
positive zero or negative zero, then positive zero is returned. If the argument is
positive or negative infinity, positive infinity is returned.
The expression fn:abs(10.5)
returns 10.5
.
The expression fn:abs(-10.5)
returns 10.5
.
Rounds $arg
upwards to a whole number.
fn:ceiling
($arg
as
xs:numeric?
) as
xs:numeric?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the smallest (closest to negative infinity) number with no
fractional part that is not less than the value of $arg
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $arg
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example,
if
$arg
is an instance of xs:decimal
then the result may
be an instance of xs:integer
.
For xs:float
and xs:double
arguments, if the argument is
positive zero, then positive zero is returned. If the argument is negative zero, then
negative zero is returned. If the argument is less than zero and greater than -1,
negative zero is returned.
The expression fn:ceiling(10.5)
returns 11
.
The expression fn:ceiling(-10.5)
returns -10
.
Rounds $arg
downwards to a whole number.
fn:floor
($arg
as
xs:numeric?
) as
xs:numeric?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the largest (closest to positive infinity) number with no
fractional part that is not greater than the value of $arg
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $arg
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example,
if
$arg
is an instance of xs:decimal
then the result may
be an instance of xs:integer
.
For xs:float
and xs:double
arguments, if the argument is
positive zero, then positive zero is returned. If the argument is negative zero, then
negative zero is returned.
The expression fn:floor(10.5)
returns 10
.
The expression fn:floor(-10.5)
returns -11
.
Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.
fn:round
($arg
as
xs:numeric?
) as
xs:numeric?
fn:round
($arg
as
xs:numeric?
, $precision
as
xs:integer
) as
xs:numeric?
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the nearest (that is, numerically closest) value to
$arg
that is a multiple of ten to the power of minus
$precision
. If two such values are equally near (for example, if the
fractional part in $arg
is exactly .5), the function returns the one that
is closest to positive infinity.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $arg
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example,
if
$arg
is an instance of xs:decimal
and $precision
is less than one,
then the result may
be an instance of xs:integer
.
The single-argument version of this function produces the same result as the
two-argument version with $precision=0
(that is, it rounds to a whole
number).
When $arg
is of type xs:float
and xs:double
:
If $arg
is NaN, positive or negative zero, or positive or negative
infinity, then the result is the same as the argument.
For other values, the argument is cast to xs:decimal
using an
implementation of xs:decimal
that imposes no limits on the number of
digits that can be represented. The function is applied to this
xs:decimal
value, and the resulting xs:decimal
is
cast back to xs:float
or xs:double
as appropriate to
form the function result. If the resulting xs:decimal
value is zero,
then positive or negative zero is returned according to the sign of
$arg
.
This function is typically used with a non-zero $precision
in financial
applications where the argument is of type xs:decimal
. For arguments of
type xs:float
and xs:double
the results may be
counter-intuitive. For example, consider round(35.425e0, 2)
. The result is
not 35.43, as might be expected, but 35.42. This is because the xs:double
written as 35.425e0 has an exact value equal to 35.42499999999..., which is closer
to
35.42 than to 35.43.
The expression fn:round(2.5)
returns 3.0
.
The expression fn:round(2.4999)
returns 2.0
.
The expression fn:round(-2.5)
returns -2.0
. (Not the possible alternative, -3
).
The expression fn:round(1.125, 2)
returns 1.13
.
The expression fn:round(8452, -2)
returns 8500
.
The expression fn:round(3.1415e0, 2)
returns 3.14e0
.
Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.
fn:round-half-to-even
($arg
as
xs:numeric?
) as
xs:numeric?
fn:round-half-to-even (
|
$arg |
as xs:numeric? ,
|
$precision |
as xs:integer ) as xs:numeric? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the nearest (that is, numerically closest) value to
$arg
that is a multiple of ten to the power of minus
$precision
. If two such values are equally near (e.g. if the fractional
part in $arg
is exactly .500...), the function returns the one whose least
significant digit is even.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $arg
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example,
if
$arg
is an instance of xs:decimal
and $precision
is less than one, then the result may
be an instance of xs:integer
.
The first signature of this function produces the same result as the second signature
with $precision=0
.
For arguments of type xs:float
and xs:double
:
If the argument is NaN
, positive or negative zero, or positive or
negative infinity, then the result is the same as the argument.
In all other cases, the argument is cast to xs:decimal
using an
implementation of xs:decimal that imposes no limits on the number of digits that
can be represented. The function is applied to this xs:decimal
value,
and the resulting xs:decimal
is cast back to xs:float
or
xs:double
as appropriate to form the function result. If the
resulting xs:decimal
value is zero, then positive or negative zero is
returned according to the sign of the original argument.
This function is typically used in financial applications where the argument is of
type
xs:decimal
. For arguments of type xs:float
and
xs:double
the results may be counter-intuitive. For example, consider
round-half-to-even(xs:float(150.015), 2)
. The result is not 150.02 as
might be expected, but 150.01. This is because the conversion of the
xs:float
value represented by the literal 150.015 to an
xs:decimal
produces the xs:decimal
value<PHONE_NUMBER>89...,
which is closer to 150.01 than to 150.02.
The expression fn:round-half-to-even(0.5)
returns 0.0
.
The expression fn:round-half-to-even(1.5)
returns 2.0
.
The expression fn:round-half-to-even(2.5)
returns 2.0
.
The expression fn:round-half-to-even(3.567812e+3, 2)
returns 3567.81e0
.
The expression fn:round-half-to-even(4.7564e-3, 2)
returns 0.0e0
.
The expression fn:round-half-to-even(35612.25, -2)
returns 35600
.
It is possible to convert strings to values of type xs:integer
,
xs:float
, xs:decimal
, or xs:double
using the constructor functions described in 18 Constructor functions
or using cast
expressions as described in 19 Casting.
In addition the fn:number
function is available to convert strings
to values of type xs:double
. It differs from the xs:double
constructor function in that any value outside the lexical space of the xs:double
datatype is converted to the xs:double
value NaN
.
| Function | Meaning |
|---|---|
fn:number |
Returns the value indicated by $arg or, if $arg is not
specified, the context item after atomization, converted to an xs:double .
|
Returns the value indicated by $arg
or, if $arg
is not
specified, the context item after atomization, converted to an xs:double
.
fn:number
() as
xs:double
fn:number
($arg
as
xs:anyAtomicType?
) as
xs:double
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·.
Calling the zero-argument version of the function is defined to give the same result
as
calling the single-argument version with the context item (.
). That is,
fn:number()
is equivalent to fn:number(.)
, as defined by
the rules that follow.
If $arg
is the empty sequence or if $arg
cannot be converted
to an xs:double
, the xs:double
value NaN
is
returned.
Otherwise, $arg
is converted to an xs:double
following the
rules of <IP_ADDRESS> Casting to xs:double. If the conversion to xs:double
fails, the xs:double
value NaN
is returned.
A dynamic error is raised [err:XPDY0002]XP31
if $arg
is omitted and the context item is absentDM31.
As a consequence of the rules given above, a type error occurs if the context item cannot be atomized, or if the result of atomizing the context item is a sequence containing more than one atomic value.
XSD 1.1 allows the string +INF
as a representation of positive infinity;
XSD 1.0 does not. It is ·implementation-defined· whether XSD 1.1 is
supported.
Generally fn:number
returns NaN
rather than raising a dynamic
error if the argument cannot be converted to xs:double
. However, a type
error is raised in the usual way if the supplied argument cannot be atomized or if
the
result of atomization does not match the required argument type.
The expression fn:number($item1/quantity)
returns 5.0e0
.
The expression fn:number($item2/description)
returns xs:double('NaN')
.
Assume that the context item is the xs:string
value "15
".
Then fn:number()
returns 1.5e1
.
| Function | Meaning |
|---|---|
fn:format-integer |
Formats an integer according to a given picture string, using the conventions of a given natural language if specified. |
Formats an integer according to a given picture string, using the conventions of a given natural language if specified.
fn:format-integer
($value
as
xs:integer?
, $picture
as
xs:string
) as
xs:string
fn:format-integer (
|
$value |
as xs:integer? ,
|
$picture |
as xs:string ,
|
|
$lang |
as xs:string? ) as xs:string |
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default language.
The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is an empty sequence, the function returns a zero-length
string.
In all other cases, the $picture
argument describes the format in which
$value
is output.
The rules that follow describe how non-negative numbers are output. If the value of
$value
is negative, the rules below are applied to the absolute value of
$value
, and a minus sign is prepended to the result.
The value of $picture
consists of a primary format token, optionally
followed by a format modifier. The primary format token is always present and
must not be zero-length. If the string contains one or more
semicolons then everything that precedes the last semicolon is taken as the primary
format token and everything that follows is taken as the format modifier; if the string
contains no semicolon then the entire picture is taken as the primary format token,
and
the format modifier is taken to be absent (which is equivalent to supplying a
zero-length string).
The primary format token is classified as one of the following:
A decimal-digit-pattern made up of optional-digit-signs, mandatory-digit-signs, and grouping-separator-signs.
The optional-digit-sign is the character "#".
A mandatory-digit-sign is a ·character· in Unicode category Nd. All
mandatory-digit-signs within the format token
must be from the same digit family, where a digit
family is a sequence of ten consecutive characters in Unicode category Nd,
having digit values 0 through 9. Within the format token, these digits are
interchangeable: a three-digit number may thus be indicated equivalently by
000
, 001
, or 999
.
a grouping-separator-sign is a non-alphanumeric character, that is a ·character· whose Unicode category is other than Nd, Nl, No, Lu, Ll, Lt, Lm or Lo.
If the primary format token contains at least one Unicode digit then it is taken
as a decimal digit pattern, and in this case it must match the
regular expression ^((\p{Nd}|#|[^\p{N}\p{L}])+?)$
. If it contains a
digit but does not match this pattern, a dynamic error is raised [err:FODF1310].
Note:
If a semicolon is to be used as a grouping separator, then the primary format token as a whole must be followed by another semicolon, to ensure that the grouping separator is not mistaken as a separator between the primary format token and the format modifier.
There must be at least one mandatory-digit-sign. There may be zero or more optional-digit-signs, and (if present) these must precede all mandatory-digit-signs. There may be zero or more grouping-separator-signs. A grouping-separator-sign must not appear at the start or end of the decimal-digit-pattern, nor adjacent to another grouping-separator-sign.
The corresponding output format is a decimal number, using this digit family, with
at least as many digits as there are mandatory-digit-signs in the
format token. Thus, a format token 1
generates the sequence 0 1
2 ... 10 11 12 ...
, and a format token 01
(or equivalently,
00
or 99
) generates the sequence 00 01 02 ...
09 10 11 12 ... 99 100 101
. A format token of ١
(Arabic-Indic digit one) generates the sequence ١
then ٢
then ٣
...
The grouping-separator-signs are handled as follows:
The position of grouping separators within the format token, counting backwards from the last digit, indicates the position of grouping separators to appear within the formatted number, and the character used as the grouping-separator-sign within the format token indicates the character to be used as the corresponding grouping separator in the formatted number.
More specifically, the position of a grouping separator is the number of optional-digit-signs and mandatory-digit-signs appearing between the grouping separator and the right-hand end of the primary format token.
Grouping separators are defined to be regular if the following conditions apply:
There is at least one grouping separator.
Every grouping separator is the same character (call it C).
There is a positive integer G (the grouping size) such that:
The position of every grouping separator is an integer multiple of G, and
Every positive integer multiple of G that is less than the number of optional-digit-signs and mandatory-digit-signs in the primary format token is the position of a grouping separator.
The grouping separator template is a (possibly infinite) set of (position, character) pairs.
If grouping separators are regular, then the grouping separator template contains
one pair of the form (n×G, C)
for every positive integer n where G is the grouping size and C is the grouping character.
Otherwise (when grouping separators are not regular), the grouping separator template
contains one pair of the form
(P, C)
for every grouping separator found in the primary formatting token, where C is the grouping
separator character and P is its position.
Note:
If there are no grouping separators, then the grouping separator template is an empty set.
The number is formatted as follows:
Let S1 be the result of formatting the supplied number in decimal notation as if by casting
it to xs:string
.
Let S2 be the result of padding S1 on the left with as many leading zeroes as are needed to ensure that it contains at least as many digits as the number of mandatory-digit-signs in the primary format token.
Let S3 be the result of replacing all decimal digits (0-9) in S2 with the corresponding digits from the selected digit family.
Let S4 be the result of inserting grouping separators into S3: for every (position P, character C) pair in the grouping separator template where P is less than the number of digits in S3, insert character C into S3 at position P, counting from the right-hand end.
Let S5 be the result of converting S4 into ordinal form, if an ordinal modifier is present, as described below.
The result of the function is then S5.
The format token A
, which generates the sequence A B C ... Z AA
AB AC...
.
The format token a
, which generates the sequence a b c ... z aa
ab ac...
.
The format token i
, which generates the sequence i ii iii iv v
vi vii viii ix x ...
.
The format token I
, which generates the sequence I II III IV V
VI VII VIII IX X ...
.
The format token w
, which generates numbers written as lower-case
words, for example in English, one two three four ...
The format token W
, which generates numbers written as upper-case
words, for example in English, ONE TWO THREE FOUR ...
The format token Ww
, which generates numbers written as title-case
words, for example in English, One Two Three Four ...
Any other format token, which indicates a numbering sequence in which that token
represents the number 1 (one) (but see the note below).
It is ·implementation-defined· which
numbering sequences, additional to those listed above, are supported. If an
implementation does not support a numbering sequence represented by the given
token, it must use a format token of 1
.
Note:
In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers; these are not included in the format token. An example (see also the example below) is classical Greek where a dexia keraia (x0374, ʹ) and sometimes an aristeri keraia (x0375, ͵) is added.
For all format tokens other than a decimal-digit-pattern, there
may be ·implementation-defined· lower and upper bounds on the range of numbers that
can be formatted using this format token; indeed, for some numbering sequences there
may
be intrinsic limits. For example, the format token ①
(circled
digit one, ①) has a range imposed by the Unicode character repertoire — zero to 20
in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering
sequences described above any upper bound imposed by the implementation must
not be less than 1000 (one thousand) and any lower bound must not be
greater than 1. Numbers that fall outside this range must be
formatted using the format token 1
.
The above expansions of numbering sequences for format tokens such as a
and
i
are indicative but not prescriptive. There are various conventions in
use for how alphabetic sequences continue when the alphabet is exhausted, and differing
conventions for how roman numerals are written (for example, IV
versus
IIII
as the representation of the number 4). Sometimes alphabetic
sequences are used that omit letters such as i
and o
. This
specification does not prescribe the detail of any sequence other than those sequences
consisting entirely of decimal digits.
Many numbering sequences are language-sensitive. This applies especially to the sequence
selected by the tokens w
, W
and Ww
. It also
applies to other sequences, for example different languages using the Cyrillic alphabet
use different sequences of characters, each starting with the letter #x410 (Cyrillic
capital letter A). In such cases, the $lang
argument specifies which
language's conventions are to be used. If the argument is specified, the value
should be either an empty sequence or a value that would be valid
for the xml:lang
attribute (see [Extensible Markup Language (XML) 1.0 (Fifth Edition)]). Note that this
permits the identification of sublanguages based on country codes (from ISO 3166-1)
as
well as identification of dialects and regions within a country.
The set of languages for which numbering is supported is ·implementation-defined·. If the $lang
argument is absent, or is
set to an empty sequence, or is invalid, or is not a language supported by the
implementation, then the number is formatted using the default language from the dynamic
context.
The format modifier must be a string that matches the regular
expression ^([co](\(.+\))?)?[at]?$
. That is, if it is present it must
consist of one or more of the following, in order:
either c
or o
, optionally followed by a sequence of
characters enclosed between parentheses, to indicate cardinal or ordinal numbering
respectively, the default being cardinal numbering
either a
or t
, to indicate alphabetic or traditional
numbering respectively, the default being ·implementation-defined·.
If the o
modifier is present, this indicates a request to output ordinal
numbers rather than cardinal numbers. For example, in English, when used with the
format
token 1
, this outputs the sequence 1st 2nd 3rd 4th ...
, and
when used with the format token w
outputs the sequence first second
third fourth ...
.
The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences. The interpretation of this string is ·implementation-defined·. No error occurs if the implementation does not define any interpretation for the defined string.
It is ·implementation-defined· what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead.
The use of the a
or t
modifier disambiguates between numbering
sequences that use letters. In many languages there are two commonly used numbering
sequences that use letters. One numbering sequence assigns numeric values to letters
in
alphabetic sequence, and the other assigns numeric values to each letter in some other
manner traditional in that language. In English, these would correspond to the numbering
sequences specified by the format tokens a
and i
. In some
languages, the first member of each sequence is the same, and so the format token
alone
would be ambiguous. In the absence of the a
or t
modifier, the
default is ·implementation-defined·.
A dynamic error is raised [err:FODF1310] if the format token is invalid, that is, if it violates any mandatory rules (indicated by an emphasized must or required keyword in the above rules). For example, the error is raised if the primary format token contains a digit but does not match the required regular expression.
Note the careful distinction between conditions that are errors and conditions where fallback occurs. The principle is that an error in the syntax of the format picture will be reported by all processors, while a construct that is recognized by some implementations but not others will never result in an error, but will instead cause a fallback representation of the integer to be used.
The following notes apply when a decimal-digit-pattern is used:
If grouping-separator-signs
appear at regular intervals within the format token, then the sequence is extrapolated
to
the left, so grouping separators will be used in the formatted number at every
multiple of N. For example, if the format token is 0'000
then the number one million will be formatted as 1'000'000
, while the
number fifteen will be formatted as 0'015
.
The only purpose of optional-digit-signs is to mark the position of
grouping-separator-signs. For example, if the format token is
#'##0
then the number one million will be formatted as
1'000'000
, while the number fifteen will be formatted as
15
. A grouping separator is included in the formatted number only
if there is a digit to its left, which will only be the case if either (a) the
number is large enough to require that digit, or (b) the number of
mandatory-digit-signs in the format token requires insignificant
leading zeros to be present.
Grouping separators are not designed for effects such as
formatting a US telephone number as<PHONE_NUMBER>
. In general they are not
suitable for such purposes because (a) only single characters are allowed, and (b)
they
cannot appear at the beginning or end of the number.
Numbers will never be truncated. Given the decimal-digit-pattern
01
, the number three hundred will be output as 300
,
despite the absence of any optional-digit-sign.
The following notes apply when ordinal numbering is selected using the o
modifier.
In some languages, the form of numbers (especially ordinal numbers) varies depending
on the grammatical context: they may have different genders and may decline with the
noun that they qualify. In such cases the string appearing in parentheses after the
letter c
or o
may be used to indicate the variation of the
cardinal or ordinal number required.
The way in which the variation is indicated will depend on the conventions of the language.
For inflected languages that vary the ending of the word, the approach recommended
in the previous version of this specification was to indicate the required ending,
preceded by a hyphen: for example in German, appropriate values might be
o(-e)
, o(-er)
, o(-es)
, o(-en)
.
Another approach, which might usefully be adopted by an implementation based on the
open-source ICU localization library [ICU], or any other library making use of the
Unicode Common Locale Data Repository [Unicode CLDR], is to allow the value in parentheses
to be the name of a registered numbering rule set for the language in question,
conventionally prefixed with a percent sign: for example,
o(%spellout-ordinal-masculine)
, or c(%spellout-cardinal-year)
.
The expression format-integer(123, '0000')
returns "0123"
.
format-integer(123, 'w')
might return "one hundred and
twenty-three"
Ordinal numbering in Italian: The specification "1;o(-º)"
with $lang
equal to
it
, if supported, should produce the sequence:
1º 2º 3º 4º ...
The specification "Ww;o"
with $lang
equal to
it
, if supported, should produce the sequence:
Primo Secondo Terzo Quarto Quinto ...
The expression format-integer(21, '1;o', 'en')
returns "21st"
.
format-integer(14, 'Ww;o(-e)', 'de')
might return
"Vierzehnte"
The expression format-integer(7, 'a')
returns "g"
.
The expression format-integer(57, 'I')
returns "LVII"
.
The expression format-integer(1234, '#;##0;')
returns "1;234"
.
This section defines a function for formatting decimal and floating point numbers.
| Function | Meaning |
|---|---|
fn:format-number |
Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context. |
Note:
This function can be used to format any numeric quantity, including an integer. For
integers, however,
the fn:format-integer
function offers additional possibilities. Note also that the picture
strings used by the two functions are not 100% compatible, though they
share some options in common.
Decimal formats are defined in the static context, and the way they are defined is therefore outside the scope of this specification. XSLT and XQuery both provide custom syntax for creating a decimal format.
The static context provides a set of decimal formats. One of the decimal formats is unnamed, the others (if any) are identified by a QName. There is always an unnamed decimal format available, but its contents are ·implementation-defined·.
Each decimal format provides a set of named properties, described in the following table:
| Name | Type | Usage (non-normative) |
|---|---|---|
decimal-separator |
A single ·character· | Defines the character used to represent the decimal point (typically ".") both in the picture string and in the formatted number. |
grouping-separator |
A single ·character· | Defines the character used to separate groups of digits (typically ",") both in the picture string and in the formatted number. |
exponent-separator |
A single ·character· | Defines the character used to separate the mantissa from the exponent in scientific notation (typically "e") both in the picture string and in the formatted number. |
infinity |
A ·string· | Defines the string used to represent the value positive or negative infinity in the formatted number (typically "Infinity") |
minus-sign |
A single ·character· | Defines the character used as a minus sign in the formatted number if there is no subpicture for formatting negative numbers (typically "-", x2D) |
NaN |
A ·string· | Defines the string used to represent the value NaN in the formatted number
|
percent |
A single ·character· | Defines the character used as a percent sign (typically "%") both in the picture string and in the formatted number |
per-mille |
A single ·character· | Defines the character used as a per-mille sign (typically "‰", x2030) both in the picture string and in the formatted number |
zero-digit |
A single ·character·, which must be a character in Unicode category Nd with decimal digit value 0 (zero) | Defines the characters used in the picture string to represent a mandatory digit: for example, if the zero-digit is "0" then any of the digits "0" to "9" may be used (interchangeably) in the picture string to represent a mandatory digit, and in the formatted number the characters "0" to "9" will be used to represent the digits zero to nine. |
digit |
A single ·character· | Defines the character used in the picture string to represent an optional digit (typically "#") |
pattern-separator |
A single ·character· | Defines the character used in the picture string to separate the positive and negative subpictures (typically ";") |
Note:
A phrase such as "The minus-signXP31 character" is to be read as "the character assigned to the minus-signXP31 property in the relevant decimal format within the static context".
[Definition] The decimal digit family of a decimal format is the sequence of ten digits with consecutive Unicode ·codepoints· starting with the character that is the value of the zero-digitXP31 property.
[Definition] The optional digit character is the character that is the value of the digitXP31 property.
For any named or unnamed decimal format, the properties representing characters used in a ·picture string· must have distinct values. These properties are decimal-separatorXP31 , grouping-separatorXP31, exponent-separatorXP31, percentXP31, per-milleXP31, digitXP31, and pattern-separatorXP31. Furthermore, none of these properties may be equal to any ·character· in the ·decimal digit family·.
Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.
fn:format-number
($value
as
xs:numeric?
, $picture
as
xs:string
) as
xs:string
fn:format-number (
|
$value |
as xs:numeric? ,
|
$picture |
as xs:string ,
|
|
$decimal-format-name |
as xs:string? ) as xs:string |
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on decimal formats, and namespaces.
The effect of the two-argument form of the function is equivalent to calling the three-argument form with an empty sequence as the value of the third argument.
The function formats $value
as a string using the ·picture string· specified by the
$picture
argument and the decimal-format named by the
$decimal-format-name
argument, or the unnamed decimal-format, if there
is no $decimal-format-name
argument. The syntax of the picture string is
described in 4.7.3 Syntax of the picture string.
The $value
argument may be of any numeric data type
(xs:double
, xs:float
, xs:decimal
, or their
subtypes including xs:integer
). Note that if an xs:decimal
is
supplied, it is not automatically promoted to an xs:double
, as such
promotion can involve a loss of precision.
If the supplied value of the $value
argument is an empty sequence, the
function behaves as if the supplied value were the xs:double
value
NaN
.
The value of $decimal-format-name
, if present and non-empty,
must be a string which after removal of leading and trailing
whitespace is in the form of an EQName
as defined in the XPath 3.0
grammar, that is one of the following:
A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).
A URIQualifiedName
using the syntax Q{uri}local
, where
the URI can be zero-length to indicate a name in no namespace.
The decimal format that is used is the decimal format in the static context whose
name
matches $decimal-format-name
if supplied, or the unnamed decimal format in
the static context otherwise.
The evaluation of the fn:format-number
function takes place in two
phases, an analysis phase described in 4.7.4 Analyzing the picture string and a
formatting phase described in 4.7.5 Formatting the number.
The analysis phase takes as its inputs the ·picture string· and the variables derived from the relevant decimal format in the static context, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.
The result of the function is the formatted string representation of the supplied number.
A dynamic error is raised [err:FODF1280] if the name specified as
the $decimal-format-name
argument is neither a valid lexical QName nor a
valid URIQualifiedName
, or if it uses a prefix that is not found in the
statically known namespaces, or if the static context does not contain a declaration
of
a decimal-format with a matching expanded QName. If the processor is able to detect
the
error statically (for example, when the argument is supplied as a string literal),
then
the processor may optionally signal this as a static error.
A string is an ordered sequence of characters, and this specification uses terms such as "left" and "right", "preceding" and "following" in relation to this ordering, irrespective of the position of the characters when visually rendered on some output medium. Both in the picture string and in the result string, digits with higher significance (that is, representing higher powers of ten) always precede digits with lower significance, even when the rendered text flow is from right to left.
The following examples assume a default decimal format in which the chosen digits are the ASCII digits 0-9, the decimal separator is ".", the grouping separator is ",", the minus-sign is "-", and the percent-sign is "%".
The expression format-number(12345.6, '#,###.00')
returns "12,345.60"
.
The expression format-number(12345678.9, '9,999.99')
returns "12,345,678.90"
.
The expression format-number(123.9, '9999')
returns "0124"
.
The expression format-number(0.14, '01%')
returns "14%"
.
The expression format-number(-6, '000')
returns "-006"
.
The following example assumes the existence of a decimal format named 'ch' in which
the grouping separator is ʹ
and the decimal separator is
·
:
The expression format-number(1234.5678, '#ʹ##0·00',
'ch')
returns "1ʹ234·57"
.
The following examples assume that the exponent separator is in decimal format 'fortran' is 'E':
The expression format-number(1234.5678, '00.000E0', 'fortran')
returns "12.346E2"
.
The expression format-number(0.234, '0.0E0', 'fortran')
returns "2.3E-1"
.
The expression format-number(0.234, '#.00E0', 'fortran')
returns "0.23E0"
.
The expression format-number(0.234, '.00E0', 'fortran')
returns ".23E0"
.
Note:
This differs from the format-number
function previously defined in XSLT 2.0 in that
any digit can be used in the picture string to represent a mandatory digit:
for example the picture
strings '000', '001', and '999' are equivalent. The digits will all be from
the same decimal digit family,
specifically, the sequence of ten consecutive digits starting with the digit
assigned to the zero-digit property.
This change is to align format-number
(which previously used '000') with format-dateTime
(which used '001').
[Definition] The formatting of a number is controlled by a picture string. The picture string is a sequence of ·characters·, in which the characters assigned to the properties decimal-separatorXP31 , exponent-separatorXP31, grouping-separatorXP31, and digitXP31, and pattern-separatorXP31 and the members of the ·decimal digit family·, are classified as active characters, and all other characters (including the values of the properties percentXP31 and per-milleXP31) are classified as passive characters.
A dynamic error is raised [err:FODF1310] if the ·picture string· does not conform to the following rules. Note that in these rules the words "preceded" and "followed" refer to characters anywhere in the string, they are not to be read as "immediately preceded" and "immediately followed".
A picture-string consists either of a sub-picture, or of two sub-pictures separated by the pattern-separatorXP31 character. A picture-string must not contain more than one instance of the pattern-separatorXP31 character. If the picture-string contains two sub-pictures, the first is used for positive and unsigned zero values and the second for negative values.
A sub-picture must not contain more than one instance of the decimal-separatorXP31 character.
A sub-picture must not contain more than one instance of the percentXP31 or per-milleXP31 characters, and it must not contain one of each.
The mantissa part of a sub-picture (defined below) must contain at least one character that is either an ·optional digit character· or a member of the ·decimal digit family·.
A sub-picture must not contain a passive character that is preceded by an active character and that is followed by another active character.
A sub-picture must not contain a grouping-separatorXP31 character that appears adjacent to a decimal-separatorXP31 character, or in the absence of a decimal-separatorXP31 character, at the end of the integer part.
A sub-picture must not contain two adjacent instances of the grouping-separatorXP31 character.
The integer part of a sub-picture (defined below) must not contain a member of the ·decimal digit family· that is followed by an instance of the ·optional digit character·. The fractional part of a sub-picture (defined below) must not contain an instance of the ·optional digit character· that is followed by a member of the ·decimal digit family·.
A character that matches the exponent-separatorXP31 property is treated as an exponent-separator-sign if it is both preceded and followed within the sub-picture by an active character. Otherwise, it is treated as a passive character. A sub-picture must not contain more than one character that is treated as an exponent-separator-sign.
A sub-picture that contains a percentXP31 or per-milleXP31 character must not contain a character treated as an exponent-separator-sign.