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.

Note:

The XML Schema 1.1 recommendation introduces one new concrete datatype:xs:dateTimeStamp; it also incorporates the typesxs:dayTimeDuration,xs:yearMonthDuration, andxs: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 asxs:NCName based on the rules in XML 1.1 rather than 1.0.

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.

fn:xml-to-json($input, map{'indent':true()})

1.6.1 Item Types

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 thederived-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 forfunction(xs:NCName) as xs:int and also forfunction(xs:string) as xs:decimal), and union types (A is substitutable forunion(A, B) and also forunion(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.

1.6.2 Schema Type Hierarchy

The next diagram and table illustrate the schema type subsystem, in which all types are derived from the distinguished typexs: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.

1.6.3 Atomic Type Hierarchy

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 typexs: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.

Note:

Following in the tradition of[XML Schema Part 2: Datatypes Second Edition], the termstype anddatatype are used interchangeably.

1.7.1 Strings, characters, and codepoints

This document uses the termsstring,character, andcodepoint 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] Acharacter is an instance of theChar^XML production of[Extensible Markup Language (XML) 1.0 (Fifth Edition)].

[Definition] Astring is a sequence of zero or more·characters·, or equivalently, a value in the value space of thexs:string datatype.

[Definition] Acodepoint is an integer assigned to a·character· by the Unicode consortium, or reserved for future assignment to a character.

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, thexs: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].

1.7.2 Namespaces and URIs

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] Anexpanded-QName is a value in the value space of thexs: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 termURI refers to Universal Resource Identifiers as defined in[RFC 3986] and extended in[RFC 3987] with a new nameIRI. The termURI Reference, unless otherwise stated, refers to a string in the lexical space of thexs:anyURI datatype as defined in[XML Schema Part 2: Datatypes Second Edition].

1.7.3 Conformance terminology

In this specification:

• The auxiliary verbmust, when rendered in small capitals, indicates a precondition for conformance.

  • When the sentence relates to an implementation of a function (for example "All implementationsmust 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 resultmust 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$argmust 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 verbmay, when rendered in small capitals, indicates optional or discretionary behavior. The statement "An implementationmay do X" implies that it is implementation-dependent whether or not it does X.

• The auxiliary verbshould, when rendered in small capitals, indicates desirable or recommended behavior. The statement "An implementationshould 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 asimplementation-defined, variations between processors are permitted, but a conformant implementationmust document the choices it has made.

[Definition] Where behavior is described asimplementation-dependent, variations between processors are permitted, and conformant implementations are not required to document the choices they have made.

1.7.4 Properties of functions

This section is concerned with the question of whether two calls on a function, with the same arguments, may produce different results.

[Definition] Anexecution 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 tofn: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 inuse-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 beidentical 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:

1. Both items are atomic values, of precisely the same type, and the values are equal as defined using theeq operator, using the Unicode codepoint collation when comparing strings.

2. Both items are nodes, and represent the same node.

3. Both items are maps, both maps have the same number of entries, and for every entryE1 in the first map there is an entryE2 in the second map such that the keys ofE1 andE2 are·the same key·, and the corresponding valuesV1 andV2 are·identical·.

4. Both items are arrays, both arrays have the same number of members, and the members are pairwise·identical·.

5. Both items are function items,neither item is a map or array, and all the following conditions apply:

   1. Either both functions have the same name, or both names areabsent^DM31.

   2. Both functions have the same arity.

   3. 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 typesS andT are defined to be identical if and only ifsubtype(S, T) andsubtype(T, S) both hold, where the subtype relation is defined inSection 2.5.6.1 The judgement subtype(A, B)^XP31.

      Note:

      Under this definition, a union type withmemberTypes="xs:double xs:decimal" is identical to a union type withmemberTypes="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 typexs:untypedAtomic.

   4. Both functions have the same nonlocal variable bindings (sometimes called the function's closure).

   5. 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 beingcontext-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 calledcontext-independent.

A function that is context-dependent can be used as a named function reference, can be partially applied, and can be found usingfn: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 onfn: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 offn: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:

1. The functionsfn:current-date,fn:current-dateTime,fn:current-time,fn:default-language,fn:implicit-timezone,fn:adjust-date-to-timezone,fn:adjust-dateTime-to-timezone, andfn: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 theop: 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·.

2. A number of functions includingfn: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, andfn:string-length#0 depend on thefocus^XP31. These functions will in general return different results on different calls if the focus is different.

   [Definition] A function isfocus-dependent if its result depends on thefocus^XP31 (that is, the context item, position, or size).

   [Definition] A function that is not·focus-dependent· is calledfocus-independent

3. The functionfn: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.

4. Functions such asfn:static-base-uri,fn:doc, andfn: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.

Thefn: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 tofn:function-lookup are used as the static and dynamic context of the function thatfn:function-lookup returns.

[Definition] For a·context-dependent· function, the parts of the context on which it depends are referred to asimplicit arguments.

[Definition] A function that is guaranteed to produce·identical· results from repeated callswithin a single·execution scope· if the explicit and implicit arguments are identical is referred to asdeterministic.

[Definition] A function that is not·deterministic· is referred to asnondeterministic.

All functions defined in this specification are·deterministic· unless otherwise stated. Exceptions include the following:

• [Definition] Some functions (such asfn:distinct-values,fn:unordered,map:keys, andmap: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 benondeterministic with respect to ordering.

• Some functions (such asfn:analyze-string,fn:parse-xml,fn:parse-xml-fragment, andfn: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 theis operator). However, if non-identical nodes are returned, their content will be the same in the sense of thefn:deep-equal function. Such a function is said to benon-deterministic with respect to node identity.

• Some functions (such asfn:doc andfn: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 argumentsmust return identical results.

3.1.1 fn:error

Summary

Calling thefn:error function raises an application-defined error.

Signatures

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

Properties

This function is·nondeterministic·,·context-independent·, and·focus-independent·.

Rules

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 thefn: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 anxs: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 URIhttp://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 anxs:QName, then an error code with namespace URINS and local partLP will be returned in the formNS#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 isfn: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·.

Error Conditions

This function always raises a dynamic error. By default, it raises [err:FOER0000]

Notes

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.

Examples

The expressionfn:error() raises errorFOER0000.(This returns the URIhttp://www.w3.org/2005/xqt-errors#FOER0000 (or the correspondingxs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.)

The expressionfn:error(fn:QName('http://www.example.com/HR', 'myerr:toohighsal'), 'Does not apply because salary is too high') raises errormyerr:toohighsal.(This returnshttp://www.example.com/HR#toohighsal and thexs:string"Does not apply because salary is too high" (or the correspondingxs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.)

3.2.1 fn:trace

Summary

Provides an execution trace intended to be used in debugging queries.

Signatures

fn:trace($value as item()*) as item()*

fn:trace($value as item()*,$label as xs:string) as item()*

Properties

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

Rules

The function returns the value of$value, unchanged.

In addition, the values of$value, converted to anxs: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 thefn:trace function is·implementation-dependent·.

Notes

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

Examples

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 anxs:decimal with value124.84. Writingfn: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.

Note:

This specification uses[IEEE 754-2008] arithmetic forxs:float andxs:double values. One consequence of this is that some operations result in the valueNaN (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 definesNaN 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 anxs:double value) will always return negative zero: see4.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-0may be converted to positive zero, though negative zero isrecommended.

XML Schema 1.1 introduces support for positive and negative zero as distinct values, and also uses the[IEEE 754-2008] semantics for comparisons involvingNaN.

op:operation(xs:int, xs:double) => op:operation(xs:double, xs:double)

op:operation(fenceHeight, xs:integer) => op:operation(xs:integer, xs:integer)

Note:

This Recommendation does not specify whetherxs: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 adding1e100 to1e-100 requires 200 digits of precision for an accurate representation of the result.

4.2.1 op:numeric-add

Summary

Returns the arithmetic sum of its operands: ($arg1 + $arg2).

Operator Mapping

Defines the semantics of the "+" operator when applied to two numeric values

Signature

op:numeric-add($arg1 as xs:numeric,$arg2 as xs:numeric) as xs:numeric

Rules

General rules: see4.2 Arithmetic operators on numeric values.

Notes

Forxs:float orxs:double values, if one of the operands is a zero or a finite number and the other isINF or-INF,INF or-INF is returned. If both operands areINF,INF is returned. If both operands are-INF,-INF is returned. If one of the operands isINF and the other is-INF,NaN is returned.

4.2.2 op:numeric-subtract

Summary

Returns the arithmetic difference of its operands: ($arg1 - $arg2).

Operator Mapping

Defines the semantics of the "-" operator when applied to two numeric values.

Signature

op:numeric-subtract($arg1 as xs:numeric,$arg2 as xs:numeric) as xs:numeric

Rules

General rules: see4.2 Arithmetic operators on numeric values.

Notes

Forxs:float orxs:double values, if one of the operands is a zero or a finite number and the other isINF or-INF, an infinity of the appropriate sign is returned. If both operands areINF or-INF,NaN is returned. If one of the operands isINF and the other is-INF, an infinity of the appropriate sign is returned.

4.2.3 op:numeric-multiply

Summary

Returns the arithmetic product of its operands: ($arg1 * $arg2).

Operator Mapping

Defines the semantics of the "*" operator when applied to two numeric values.

Signature

op:numeric-multiply($arg1 as xs:numeric,$arg2 as xs:numeric) as xs:numeric

Rules

General rules: see4.2 Arithmetic operators on numeric values.

Notes

Forxs:float orxs: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.

4.2.4 op:numeric-divide

Summary

Returns the arithmetic quotient of its operands: ($arg1 div $arg2).

Operator Mapping

Defines the semantics of the "div" operator when applied to two numeric values.

Signature

op:numeric-divide($arg1 as xs:numeric,$arg2 as xs:numeric) as xs:numeric

Rules

General rules: see4.2 Arithmetic operators on numeric values.

As a special case, if the types of both$arg1 and$arg2 arexs:integer, then the return type isxs:decimal.

Error Conditions

A dynamic error is raised [err:FOAR0001] forxs:decimal andxs:integer operands, if the divisor is (positive or negative) zero.

Notes

Forxs:float andxs:double operands, floating point division is performed as specified in[IEEE 754-2008]. A positive number divided by positive zero returnsINF. A negative number divided by positive zero returns-INF. Division by negative zero returns-INF andINF, respectively. Positive or negative zero divided by positive or negative zero returnsNaN. Also,INF or-INF divided byINF or-INF returnsNaN.

4.2.5 op:numeric-integer-divide

Summary

Performs an integer division.

Operator Mapping

Defines the semantics of the "idiv" operator when applied to two numeric values.

Signature

op:numeric-integer-divide(	$arg1	as xs:numeric,
	$arg2	as xs:numeric) as xs:integer

Rules

General rules: see4.2 Arithmetic operators on numeric values.

If$arg2 isINF or-INF, and$arg1 is notINF 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 ofxs:decimal division.

Error Conditions

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 isNaN or if$arg1 isINF or-INF.

Notes

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

Examples

The expressionop:numeric-integer-divide(10,3) returns3.

The expressionop:numeric-integer-divide(3,-2) returns-1.

The expressionop:numeric-integer-divide(-3,2) returns-1.

The expressionop:numeric-integer-divide(-3,-2) returns1.

The expressionop:numeric-integer-divide(9.0,3) returns3.

The expressionop:numeric-integer-divide(-3.5,3) returns-1.

The expressionop:numeric-integer-divide(3.0,4) returns0.

The expressionop:numeric-integer-divide(3.1E1,6) returns5.

The expressionop:numeric-integer-divide(3.1E1,7) returns4.

4.2.6 op:numeric-mod

Summary

Returns the remainder resulting from dividing$arg1, the dividend, by$arg2, the divisor.

Operator Mapping

Defines the semantics of the "mod" operator when applied to two numeric values.

Signature

op:numeric-mod($arg1 as xs:numeric,$arg2 as xs:numeric) as xs:numeric

Rules

General rules: see4.2 Arithmetic operators on numeric values.

The operationa mod b for operands that arexs:integer orxs:decimal, or types derived from them, produces a result such that(a idiv b)*b+(a mod b) is equal toa and the magnitude of the result is always less than the magnitude ofb. 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.

Forxs:float andxs:double operands the following rules apply:

• If either operand isNaN, the result isNaN.

• If the dividend is positive or negative infinity, or the divisor is positive or negative zero (0), or both, the result isNaN.

• 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, norNaN 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.

Error Conditions

A dynamic error is raised [err:FOAR0001] forxs:integer andxs:decimal operands, if$arg2 is zero.

Examples

The expressionop:numeric-mod(10,3) returns1.

The expressionop:numeric-mod(6,-2) returns0.

The expressionop:numeric-mod(4.5,1.2) returns0.9.

The expressionop:numeric-mod(1.23E2, 0.6E1) returns3.0E0.

4.2.7 op:numeric-unary-plus

Summary

Returns its operand with the sign unchanged: (+ $arg).

Operator Mapping

Defines the semantics of the unary "+" operator applied to a numeric value.

Signature

op:numeric-unary-plus($arg as xs:numeric) as xs:numeric

Rules

General rules: see4.2 Arithmetic operators on numeric values.

The returned value is equal to$arg, and is an instance ofxs:integer,xs:decimal,xs:double, orxs:float depending on the type of$arg.

Notes

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 asxs:double(@price) if the type of@price isxs:untypedAtomic.

4.2.8 op:numeric-unary-minus

Summary

Returns its operand with the sign reversed: (- $arg).

Operator Mapping

Defines the semantics of the unary "-" operator when applied to a numeric value.

Signature

op:numeric-unary-minus($arg as xs:numeric) as xs:numeric

Rules

General rules: see4.2 Arithmetic operators on numeric values.

The returned value is an instance ofxs:integer,xs:decimal,xs:double, orxs:float depending on the type of$arg.

Forxs:integer andxs:decimal arguments,0 and0.0 return0 and0.0, respectively. Forxs:float andxs:double arguments,NaN returnsNaN,0.0E0 returns-0.0E0 and vice versa.INF returns-INF.-INF returnsINF.

4.3.1 op:numeric-equal

Summary

Returns true if and only if the value of$arg1 is equal to the value of$arg2.

Operator Mapping

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

Signature

op:numeric-equal($arg1 as xs:numeric,$arg2 as xs:numeric) as xs:boolean

Rules

General rules: see4.2 Arithmetic operators on numeric values and4.3 Comparison operators on numeric values.

Forxs:float andxs:double values, positive zero and negative zero compare equal.INF equalsINF, and-INF equals-INF.NaN does not equal itself.

4.3.2 op:numeric-less-than

Summary

Returnstrue if and only if$arg1 is numerically less than$arg2.

Operator Mapping

Defines the semantics of the "lt" operator when applied to two numeric values, and is also used in defining the semantics of "le".

Signature

op:numeric-less-than($arg1 as xs:numeric,$arg2 as xs:numeric) as xs:boolean

Rules

General rules: see4.2 Arithmetic operators on numeric values and4.3 Comparison operators on numeric values.

Forxs:float andxs: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 isNaN, the function returnsfalse.

4.3.3 op:numeric-greater-than

Summary

Returnstrue if and only if$arg1 is numerically greater than$arg2.

Operator Mapping

Defines the semantics of the "gt" operator when applied to two numeric values, and is also used in defining the semantics of "ge".

Signature

op:numeric-greater-than($arg1 as xs:numeric,$arg2 as xs:numeric) as xs:boolean

Rules

The function callop:numeric-greater-than($A, $B) is defined to return the same result asop:numeric-less-than($B, $A)

Note:

fn:round andfn: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)

4.4.1 fn:abs

Summary

Returns the absolute value of$arg.

Signature

fn:abs($arg as xs:numeric?) as xs:numeric?

Properties

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

Rules

General rules: see4.4 Functions on numeric values.

If$arg is negative the function returns-$arg, otherwise it returns$arg.

For the four typesxs:float,xs:double,xs:decimal andxs:integer, it is guaranteed that if the type of$arg is an instance of typeT then the result will also be an instance ofT. The resultmay also be an instance of a type derived from one of these four by restriction. For example, if$arg is an instance ofxs:positiveInteger then the value of$argmay be returned unchanged.

Forxs:float andxs: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.

Examples

The expressionfn:abs(10.5) returns10.5.

The expressionfn:abs(-10.5) returns10.5.

4.4.2 fn:ceiling

Summary

Rounds$arg upwards to a whole number.

Signature

fn:ceiling($arg as xs:numeric?) as xs:numeric?

Properties

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

Rules

General rules: see4.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 typesxs:float,xs:double,xs:decimal andxs:integer, it is guaranteed that if the type of$arg is an instance of typeT then the result will also be an instance ofT. The resultmay also be an instance of a type derived from one of these four by restriction. For example, if$arg is an instance ofxs:decimal then the resultmay be an instance ofxs:integer.

Forxs:float andxs: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.

Examples

The expressionfn:ceiling(10.5) returns11.

The expressionfn:ceiling(-10.5) returns-10.

4.4.3 fn:floor

Summary

Rounds$arg downwards to a whole number.

Signature

fn:floor($arg as xs:numeric?) as xs:numeric?

Properties

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

Rules

General rules: see4.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 typesxs:float,xs:double,xs:decimal andxs:integer, it is guaranteed that if the type of$arg is an instance of typeT then the result will also be an instance ofT. The resultmay also be an instance of a type derived from one of these four by restriction. For example, if$arg is an instance ofxs:decimal then the resultmay be an instance ofxs:integer.

Forxs:float andxs:double arguments, if the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned.

Examples

The expressionfn:floor(10.5) returns10.

The expressionfn:floor(-10.5) returns-11.

4.4.4 fn:round

Summary

Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.

Signatures

fn:round($arg as xs:numeric?) as xs:numeric?

fn:round($arg as xs:numeric?,$precision as xs:integer) as xs:numeric?

Properties

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

Rules

General rules: see4.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 typesxs:float,xs:double,xs:decimal andxs:integer, it is guaranteed that if the type of$arg is an instance of typeT then the result will also be an instance ofT. The resultmay also be an instance of a type derived from one of these four by restriction. For example, if$arg is an instance ofxs:decimal and$precision is less than one, then the resultmay be an instance ofxs: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 typexs:float andxs:double:

1. If$arg is NaN, positive or negative zero, or positive or negative infinity, then the result is the same as the argument.

2. For other values, the argument is cast toxs:decimal using an implementation ofxs:decimal that imposes no limits on the number of digits that can be represented. The function is applied to thisxs:decimal value, and the resultingxs:decimal is cast back toxs:float orxs:double as appropriate to form the function result. If the resultingxs:decimal value is zero, then positive or negative zero is returned according to the sign of$arg.

Notes

This function is typically used with a non-zero$precision in financial applications where the argument is of typexs:decimal. For arguments of typexs:float andxs:double the results may be counter-intuitive. For example, considerround(35.425e0, 2). The result is not 35.43, as might be expected, but 35.42. This is because thexs:double written as 35.425e0 has an exact value equal to 35.42499999999..., which is closer to 35.42 than to 35.43.

Examples

The expressionfn:round(2.5) returns3.0.

The expressionfn:round(2.4999) returns2.0.

The expressionfn:round(-2.5) returns-2.0.(Not the possible alternative,-3).

The expressionfn:round(1.125, 2) returns1.13.

The expressionfn:round(8452, -2) returns8500.

The expressionfn:round(3.1415e0, 2) returns3.14e0.

4.4.5 fn:round-half-to-even

Summary

Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.

Signatures

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?

Properties

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

Rules

General rules: see4.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 typesxs:float,xs:double,xs:decimal andxs:integer, it is guaranteed that if the type of$arg is an instance of typeT then the result will also be an instance ofT. The resultmay also be an instance of a type derived from one of these four by restriction. For example, if$arg is an instance ofxs:decimal and$precision is less than one, then the resultmay be an instance ofxs:integer.

The first signature of this function produces the same result as the second signature with$precision=0.

For arguments of typexs:float andxs:double:

1. If the argument isNaN, positive or negative zero, or positive or negative infinity, then the result is the same as the argument.

2. In all other cases, the argument is cast toxs: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 thisxs:decimal value, and the resultingxs:decimal is cast back toxs:float orxs:double as appropriate to form the function result. If the resultingxs:decimal value is zero, then positive or negative zero is returned according to the sign of the original argument.

Notes

This function is typically used in financial applications where the argument is of typexs:decimal. For arguments of typexs:float andxs:double the results may be counter-intuitive. For example, considerround-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 thexs:float value represented by the literal 150.015 to anxs:decimal produces thexs:decimal value 150.014999389..., which is closer to 150.01 than to 150.02.

Examples

The expressionfn:round-half-to-even(0.5) returns0.0.

The expressionfn:round-half-to-even(1.5) returns2.0.

The expressionfn:round-half-to-even(2.5) returns2.0.

The expressionfn:round-half-to-even(3.567812e+3, 2) returns3567.81e0.

The expressionfn:round-half-to-even(4.7564e-3, 2) returns0.0e0.

The expressionfn:round-half-to-even(35612.25, -2) returns35600.

4.5.1 fn:number

Summary

Returns the value indicated by$arg or, if$arg is not specified, the context item after atomization, converted to anxs:double.

Signatures

fn:number() as xs:double

fn:number($arg as xs:anyAtomicType?) as xs:double

Properties

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

Rules

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 tofn:number(.), as defined by the rules that follow.

If$arg is the empty sequence or if$arg cannot be converted to anxs:double, thexs:double valueNaN is returned.

Otherwise,$arg is converted to anxs:double following the rules of19.1.2.2 Casting to xs:double. If the conversion toxs:double fails, thexs:double valueNaN is returned.

Error Conditions

A dynamic error is raised [err:XPDY0002]^XP31 if$arg is omitted and the context item isabsent^DM31.

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.

Notes

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.

Generallyfn:number returnsNaN rather than raising a dynamic error if the argument cannot be converted toxs: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.

Examples

The expressionfn:number($item1/quantity) returns5.0e0.

The expressionfn:number($item2/description) returnsxs:double('NaN').

Assume that the context item is thexs:string value "15". Thenfn:number() returns1.5e1.

4.6.1 fn:format-integer

Summary

Formats an integer according to a given picture string, using the conventions of a given natural language if specified.

Signatures

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

Properties

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

Rules

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 andmust 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:

1. Adecimal-digit-pattern made up ofoptional-digit-signs,mandatory-digit-signs, andgrouping-separator-signs.

   • Theoptional-digit-sign is the character "#".

   • Amandatory-digit-sign is a·character· in Unicode categoryNd. Allmandatory-digit-signs within the format tokenmust be from the same digit family, where a digit family is a sequence of ten consecutive characters in Unicode categoryNd, having digit values 0 through 9. Within the format token, these digits are interchangeable: a three-digit number may thus be indicated equivalently by000,001, or999.

   • agrouping-separator-sign is a non-alphanumeric character, that is a·character· whose Unicode category is other thanNd,Nl,No,Lu,Ll,Lt,Lm orLo.

   If the primary format token contains at least one Unicode digit then it is taken as a decimal digit pattern, and in this case itmust 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.

   Theremust be at least onemandatory-digit-sign. There may be zero or moreoptional-digit-signs, and (if present) thesemust precede allmandatory-digit-signs. There may be zero or moregrouping-separator-signs. Agrouping-separator-signmust not appear at the start or end of thedecimal-digit-pattern, nor adjacent to anothergrouping-separator-sign.

   The corresponding output format is a decimal number, using this digit family, with at least as many digits as there aremandatory-digit-signs in the format token. Thus, a format token1 generates the sequence0 1 2 ... 10 11 12 ..., and a format token01 (or equivalently,00 or99) generates the sequence00 01 02 ... 09 10 11 12 ... 99 100 101. A format token of١ (Arabic-Indic digit one) generates the sequence١ then٢ then٣ ...

   Thegrouping-separator-signs are handled as follows:

   1. 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 thegrouping-separator-sign within the format token indicates the character to be used as the corresponding grouping separator in the formatted number.

   2. More specifically, theposition of a grouping separator is the number ofoptional-digit-signs andmandatory-digit-signs appearing between the grouping separator and the right-hand end of the primary format token.

   3. Grouping separators are defined to beregular if the following conditions apply:

      1. There is at least one grouping separator.

      2. Every grouping separator is the same character (call itC).

      3. There is a positive integerG (the grouping size) such that:

         1. The position of every grouping separator is an integer multiple ofG, and

         2. Every positive integer multiple ofG that is less than the number ofoptional-digit-signs andmandatory-digit-signs in the primary format token is the position of a grouping separator.

   4. Thegrouping separator template is a (possibly infinite) set of (position, character) pairs.

   5. If grouping separators are regular, then the grouping separator template contains one pair of the form(n×G, C) for every positive integern whereG is the grouping size andC is the grouping character.

   6. 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, whereC is the grouping separator character andP is its position.

   7. Note:

      If there are no grouping separators, then the grouping separator template is an empty set.

   The number is formatted as follows:

   1. LetS₁ be the result of formatting the supplied number in decimal notation as if by casting it toxs:string.

   2. LetS₂ be the result of paddingS₁ on the left with as many leading zeroes as are needed to ensure that it contains at least as many digits as the number ofmandatory-digit-signs in the primary format token.

   3. LetS₃ be the result of replacing all decimal digits (0-9) inS₂ with the corresponding digits from the selected digit family.

   4. LetS₄ be the result of inserting grouping separators intoS₃: for every (positionP, characterC) pair in the grouping separator template whereP is less than the number of digits inS₃, insert characterC intoS₃ at positionP, counting from the right-hand end.

   5. LetS₅ be the result of convertingS₄ into ordinal form, if an ordinal modifier is present, as described below.

   6. The result of the function is thenS₅.

2. The format tokenA, which generates the sequenceA B C ... Z AA AB AC....

3. The format tokena, which generates the sequencea b c ... z aa ab ac....

4. The format tokeni, which generates the sequencei ii iii iv v vi vii viii ix x ....

5. The format tokenI, which generates the sequenceI II III IV V VI VII VIII IX X ....

6. The format tokenw, which generates numbers written as lower-case words, for example in English,one two three four ...

7. The format tokenW, which generates numbers written as upper-case words, for example in English,ONE TWO THREE FOUR ...

8. The format tokenWw, which generates numbers written as title-case words, for example in English,One Two Three Four ...

9. 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, itmust use a format token of1.

   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 adexia keraia (x0374, ʹ) and sometimes anaristeri keraia (x0375, ͵) is added.

For all format tokens other than adecimal-digit-pattern, theremay 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 to3.2, orzero to 50 in subsequent versions. For the numbering sequences described above any upper bound imposed by the implementationmust not be less than 1000 (one thousand) and any lower bound must not be greater than 1. Numbers that fall outside this rangemust be formatted using the format token1.

The above expansions of numbering sequences for format tokens such asa andi 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 versusIIII as the representation of the number 4). Sometimes alphabetic sequences are used that omit letters such asi ando. 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 tokensw,W andWw. 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 valueshould be either an empty sequence or a value that would be valid for thexml: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 modifiermust 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:

• eitherc oro, optionally followed by a sequence of characters enclosed between parentheses, to indicate cardinal or ordinal numbering respectively, the default being cardinal numbering

• eithera ort, to indicate alphabetic or traditional numbering respectively, the default being·implementation-defined·.

If theo modifier is present, this indicates a request to output ordinal numbers rather than cardinal numbers. For example, in English, when used with the format token1, this outputs the sequence1st 2nd 3rd 4th ..., and when used with the format tokenw outputs the sequencefirst 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 thea ort 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 tokensa andi. 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 thea ort modifier, the default is·implementation-defined·.

Error Conditions

A dynamic error is raised [err:FODF1310] if the format token is invalid, that is, if it violates any mandatory rules (indicated by an emphasizedmust orrequired 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.

Notes

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

2. The following notes apply when adecimal-digit-pattern is used:

   1. Ifgrouping-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 ofN. For example, if the format token is0'000 then the number one million will be formatted as1'000'000, while the number fifteen will be formatted as0'015.

   2. The only purpose ofoptional-digit-signs is to mark the position ofgrouping-separator-signs. For example, if the format token is#'##0 then the number one million will be formatted as1'000'000, while the number fifteen will be formatted as15. 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 ofmandatory-digit-signs in the format token requires insignificant leading zeros to be present.

   3. Grouping separators arenot designed for effects such as formatting a US telephone number as(365)123-9876. 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.

   4. Numbers will never be truncated. Given thedecimal-digit-pattern01, the number three hundred will be output as300, despite the absence of anyoptional-digit-sign.

3. The following notes apply when ordinal numbering is selected using theo 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 letterc oro 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 beo(-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), orc(%spellout-cardinal-year).

Examples

The expressionformat-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 toit, if supported, should produce the sequence:

1º 2º 3º 4º ...

The specification"Ww;o" with$lang equal toit, if supported, should produce the sequence:

Primo Secondo Terzo Quarto Quinto ...

The expressionformat-integer(21, '1;o', 'en') returns"21st".

format-integer(14, 'Ww;o(-e)', 'de') might return"Vierzehnte"

The expressionformat-integer(7, 'a') returns"g".

The expressionformat-integer(57, 'I') returns"LVII".

The expressionformat-integer(1234, '#;##0;') returns"1;234".

Note:

This function can be used to format any numeric quantity, including an integer. For integers, however, thefn: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.

4.7.1 Defining a decimal format

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:

[Definition] Thedecimal 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 thezero-digit^XP31 property.

[Definition] Theoptional digit character is the character that is the value of thedigit^XP31 property.

For any named or unnamed decimal format, the properties representing characters used in a·picture string· must have distinct values. These properties aredecimal-separator^XP31 ,grouping-separator^XP31,exponent-separator^XP31,percent^XP31,per-mille^XP31,digit^XP31, andpattern-separator^XP31. Furthermore, none of these properties may be equal to any·character· in the·decimal digit family·.

4.7.2 fn:format-number

Summary

Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.

Signatures

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

Properties

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.

Rules

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 in4.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 includingxs:integer). Note that if anxs:decimal is supplied, it is not automatically promoted to anxs: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 thexs:double valueNaN.

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

• AURIQualifiedName using the syntaxQ{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 thefn:format-number function takes place in two phases, an analysis phase described in4.7.4 Analyzing the picture string and a formatting phase described in4.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.

Error Conditions

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 validURIQualifiedName, 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 processormay optionally signal this as a static error.

Notes

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.

Examples

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 expressionformat-number(12345.6, '#,###.00') returns"12,345.60".

The expressionformat-number(12345678.9, '9,999.99') returns"12,345,678.90".

The expressionformat-number(123.9, '9999') returns"0124".

The expressionformat-number(0.14, '01%') returns"14%".

The expressionformat-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 expressionformat-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 expressionformat-number(1234.5678, '00.000E0', 'fortran') returns"12.346E2".

The expressionformat-number(0.234, '0.0E0', 'fortran') returns"2.3E-1".

The expressionformat-number(0.234, '#.00E0', 'fortran') returns"0.23E0".

The expressionformat-number(0.234, '.00E0', 'fortran') returns".23E0".

4.7.3 Syntax of the picture string

[Definition] The formatting of a number is controlled by apicture string. The picture string is a sequence of·characters·, in which the characters assigned to the propertiesdecimal-separator^XP31 ,exponent-separator^XP31,grouping-separator^XP31, anddigit^XP31, andpattern-separator^XP31 and the members of the·decimal digit family·, are classified as active characters, and all other characters (including the values of the propertiespercent^XP31 andper-mille^XP31) 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 thepattern-separator^XP31 character. A picture-stringmust not contain more than one instance of thepattern-separator^XP31 character. If the picture-string contains two sub-pictures, the first is used for positiveand unsigned zero values and the second for negative values.

• A sub-picturemust not contain more than one instance of thedecimal-separator^XP31 character.

• A sub-picturemust not contain more than one instance of thepercent^XP31 orper-mille^XP31 characters, and itmust not contain one of each.

• Themantissa 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-picturemust not contain a passive character that is preceded by an active character and that is followed by another active character.

• A sub-picturemust not contain agrouping-separator^XP31 character that appears adjacent to adecimal-separator^XP31 character, or in the absence of adecimal-separator^XP31 character, at the end of theinteger part.

• A sub-picturemust not contain two adjacent instances of thegrouping-separator^XP31 character.

• Theinteger 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·. Thefractional 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 theexponent-separator^XP31 property is treated as anexponent-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-picturemust not contain more than one character that is treated as anexponent-separator-sign.

• A sub-picture that contains apercent^XP31 orper-mille^XP31 charactermust not contain a character treated as anexponent-separator-sign.

• If a sub-picture contains a character treated as anexponent-separator-sign then thismust be followed by one or more characters that are members of the·decimal digit family·, and itmust not be followed by any active character that is not a member of the·decimal digit family·.

Themantissa part of the sub-picture is defined as the part that appears to the left of theexponent-separator-sign if there is one, or the entire sub-picture otherwise. Theexponent part of the subpicture is defined as the part that appears to the right of theexponent-separator-sign; if there is noexponent-separator-sign then theexponent part is absent.

Theinteger part of the sub-picture is defined as the part that appears to the left of thedecimal-separator^XP31 character if there is one, or the entiremantissa part otherwise.

Thefractional part of the sub-picture is defined asthat part of themantissa part that appears to the right of thedecimal-separator^XP31 character if there is one, or the part that appears to the right of the rightmost active character otherwise. The fractional part may be zero-length.

4.7.4 Analyzing the picture string

This phase of the algorithm analyzes the·picture string· and the properties from the selected decimal format in the static context, and it has the effect of setting the values of various variables, which are used in the subsequent formatting phase. These variables are listed below. Each is shown with its initial setting and its datatype.

Several variables are associated with each sub-picture. If there are two sub-pictures, then these rules are applied to one sub-picture to obtain the values that apply to positiveand unsigned zero numbers, and to the other to obtain the values that apply to negative numbers. If there is only one sub-picture, then the values for both cases are derived from this sub-picture.

The variables are as follows:

• Theinteger-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the integer part of the sub-picture. For eachgrouping-separator^XP31 character that appears within the integer part of the sub-picture, this sequence contains an integer that is equal to the total number of·optional digit character· and·decimal digit family· characters that appear within the integer part of the sub-picture and to the right of thegrouping-separator^XP31 character.

  The grouping is defined to beregular if the following conditions apply:

  1. There is an least one grouping-separator in the integer part of the sub-picture.

  2. There is a positive integerG (the grouping size) such that the position of every grouping-separator in the integer part of the sub-picture is a positive integer multiple ofG.

  3. Every position in the integer part of the sub-picture that is a positive integer multiple ofG is occupied by a grouping-separator.

  If the grouping is regular, then theinteger-part-grouping-positions sequence contains all integer multiples ofG as far as necessary to accommodate the largest possible number.

• Theminimum-integer-part-size is an integer indicating the minimum number of digits that will appear to the left of thedecimal-separator character. It isinitially set to the number of·decimal digit family· characters found in the integer part of the sub-picture,but may be adjusted as described below.

  Note:

  There is no maximum integer part size. All significant digits in the integer part of the number will be displayed, even if this exceeds the number of·optional digit character· and·decimal digit family· characters in the subpicture.

• Thescaling factor is a non-negative integer used to determine the scaling of the mantissa in exponential notation. It is set to the number of·decimal digit family· characters found in the integer part of the sub-picture.

• Theprefix is set to contain all passive characters in the sub-picture to the left of the leftmost active character. If the picture string contains only one sub-picture, theprefix for the negative sub-picture is set by concatenating theminus-sign^XP31 character and theprefix for the positive sub-picture (if any), in that order.

• Thefractional-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the fractional part of the sub-picture. For eachgrouping-separator^XP31 character that appears within the fractional part of the sub-picture, this sequence contains an integer that is equal to the total number of·optional digit character· and·decimal digit family· characters that appear within the fractional part of the sub-picture and to the left of thegrouping-separator^XP31 character.

  Note:

  There is no need to extrapolate grouping positions on the fractional side, because the number of digits in the output will never exceed the number of·optional digit character· and·decimal digit family· characters in the fractional part of the sub-picture.

• Theminimum-fractional-part-size is set to the number of·decimal digit family· characters found in the fractional part of the sub-picture.

• Themaximum-fractional-part-size is set to the total number of·optional digit character· and·decimal digit family· characters found in the fractional part of the sub-picture.

• If the effect of the above rules is thatminimum-integer-part-size andmaximum-fractional-part-size are both zero, then an adjustment is applied as follows:

  • If an exponent separator is present then:

    • minimum-fractional-part-size is changed to 1 (one).

    • maximum-fractional-part-size is changed to 1 (one).

    Note:

    This has the effect that with the picture#.e9, the value0.123 is formatted as0.1e0

  • Otherwise:

    • minimum-integer-part-size is changed to 1 (one).

    Note:

    This has the effect that with the picture#, the value0.23 is formatted as0

• If all the following conditions are true:

  • An exponent separator is present

  • Theminimum-integer-part-size is zero

  • There is at least one·optional digit character· in the integer part of the sub-picture

  then theminimum-integer-part-size is changed to 1 (one).

  Note:

  This has the effect that with the picture.9e9, the value0.1 is formatted as.1e0, while with the picture#.9e9, it is formatted as0.1e0

• If (after making the above adjustments) theminimum-integer-part-size and theminimum-fractional-part-size are both zero, then theminimum-fractional-part-size is set to 1 (one).

• Theminimum-exponent-size is set to the number of·decimal digit family· characters found in the exponent part of the sub-picture if present, or zero otherwise.

  Note:

  The rules for the syntax of the picture string ensure that if an exponent separator is present, then theminimum-exponent-size will always be greater than zero.

• Thesuffix is set to contain all passive characters to the right of the rightmost active character in the sub-picture.

4.7.5 Formatting the number

This section describes the second phase of processing of thefn:format-number function. This phase takes as input a number to be formatted (referred to as theinput number), and the variables set up by analyzing the decimal format in the static context and the·picture string·, as described above. The result of this phase is a string, which forms the return value of thefn:format-number function.

The algorithm for this second stage of processing is as follows:

1. If the input number is NaN (not a number), the result is the value of thepattern separator^XP31 property (with noprefix orsuffix).

2. In the rules below, the positive sub-picture and its associated variables are used if the input number is positive, and the negative sub-picture and its associated variables are used ifit is negative. Forxs:double andxs:float, negative zero is taken as negative, positive zero as positive. Forxs:decimal andxs:integer, the positive sub-picture is used for zero.

3. Theadjusted number is determined as follows:

   • If the sub-picture contains apercent^XP31 character, theadjusted number is the input number multiplied by 100.

   • If the sub-picture contains aper-mille^XP31 character, theadjusted number is the input number multiplied by 1000.

   • Otherwise, theadjusted number is the input number.

   If the multiplication causes numeric overflow, no error occurs, and theadjusted number is positive or negative infinity as appropriate.

4. If theadjusted number is positive or negative infinity, the result is the concatenation of the appropriateprefix, the value of theinfinity^XP31 property, and the appropriatesuffix.

5. If theminimum exponent size is non-zero, then theadjusted number is scaled to establish amantissa and an integerexponent. Themantissa andexponent are chosen such that all the following conditions are true:

   • The primitive type of themantissa is the same as the primitive type of theadjusted number (integer, decimal, float, or double).

   • Themantissa multiplied by ten to the power of the exponent is equal to theadjusted number.

   • Themantissa is less than 10^N, and at least 10^N-1, whereN is thescaling factor.

   If theminimum exponent size is zero, then themantissa is theadjusted number and there is noexponent.

6. Themantissa is converted (if necessary) to anxs:decimal value, using an implementation ofxs:decimal that imposes no limits on thetotalDigits orfractionDigits facets. If there are several such values that are numerically equal to themantissa (bearing in mind that if themantissa is anxs:double orxs:float, the comparison will be done by converting the decimal value back to anxs:double orxs:float), the one that is chosenshould be one with the smallest possible number of digits not counting leading or trailing zeroes (whether significant or insignificant). For example, 1.0 is preferred to 0.9999999999, and 100000000 is preferred to 100000001. This value is then rounded so that it uses no more thanmaximum-fractional-part-size digits in its fractional part. Therounded number is defined to be the result of converting themantissa to anxs:decimal value, as described above, and then calling the functionfn:round-half-to-even with this converted number as the first argument and themaximum-fractional-part-size as the second argument, again with no limits on thetotalDigits orfractionDigits in the result.

7. The absolute value of therounded number is converted to a string in decimal notation, using the digits in the·decimal digit family· to represent the ten decimal digits, and thedecimal-separator^XP31 character to separate the integer part and the fractional part. This string must always contain adecimal-separator^XP31, and it must contain no leading zeroes and no trailing zeroes. The value zero will at this stage be represented by adecimal-separator^XP31 on its own.

8. If the number of digits to the left of thedecimal-separator^XP31 character is less thanminimum-integer-part-size, leadingzero digit^XP31 characters are added to pad out to that size.

9. If the number of digits to the right of thedecimal-separator^XP31 character is less thanminimum-fractional-part-size, trailingzero digit^XP31 characters are added to pad out to that size.

10. For each integerN in theinteger-part-grouping-positions list, agrouping-separator^XP31 character is inserted into the string immediately after that digit that appears in the integer part of the number and hasN digits between it and thedecimal-separator^XP31 character, if there is such a digit.

11. For each integerN in thefractional-part-grouping-positions list, agrouping-separator^XP31 character is inserted into the string immediately before that digit that appears in the fractional part of the number and hasN digits between it and thedecimal-separator^XP31 character, if there is such a digit.

12. If there is nodecimal-separator^XP31 character in the sub-picture, or if there are no digits to the right of thedecimal-separator character in the string, then thedecimal-separator character is removed from the string (it will be the rightmost character in the string).

13. If anexponent exists, then the string produced from themantissa as described above is extended with the following, in order: (a) theexponent-separator^XP31 character; (b) if theexponent is negative, theminus-sign^XP31 character; (c) the value of theexponent represented as a decimal integer, extended if necessary with leading zeroes to make it up to theminimum exponent size, using digits taken from the·decimal digit family·.

14. The result of the function is the concatenation of the appropriateprefix, the string conversion of the number as obtained above, and the appropriatesuffix.

4.8.1 math:pi

Summary

Returns an approximation to the mathematical constantπ.

Signature

math:pi() as xs:double

Properties

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

Rules

This function returns thexs:double value whose lexical representation is 3.141592653589793e0

Examples

The expression2*math:pi() returns6.283185307179586e0.

The expression60 * (math:pi() div 180) converts an angle of 60 degrees to radians.

4.8.2 math:exp

Summary

Returns the value ofe^x.

Signature

math:exp($arg as xs:double?) as xs:double?

Properties

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

Rules

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

Otherwise the result is the mathematical constante raised to the power of$arg, as defined in the[IEEE 754-2008] specification of theexp function applied to 64-bit binary floating point values.

Notes

The treatment of overflow and underflow is defined in4.2 Arithmetic operators on numeric values.

Examples

The expressionmath:exp(()) returns().

The expressionmath:exp(0) returns1.0e0.

The expressionmath:exp(1) returns2.7182818284590455e0 (approximately).

The expressionmath:exp(2) returns7.38905609893065e0.

The expressionmath:exp(-1) returns0.36787944117144233e0.

The expressionmath:exp(math:pi()) returns23.140692632779267e0.

The expressionmath:exp(xs:double('NaN')) returnsxs:double('NaN').

The expressionmath:exp(xs:double('INF')) returnsxs:double('INF').

The expressionmath:exp(xs:double('-INF')) returns0.0e0.

4.8.3 math:exp10

Summary

Returns the value of10^x.

Signature

math:exp10($arg as xs:double?) as xs:double?

Properties

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

Rules

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

Otherwise the result is ten raised to the power of$arg, as defined in the[IEEE 754-2008] specification of theexp10 function applied to 64-bit binary floating point values.

Notes

The treatment of overflow and underflow is defined in4.2 Arithmetic operators on numeric values.

Examples

The expressionmath:exp10(()) returns().

The expressionmath:exp10(0) returns1.0e0.

The expressionmath:exp10(1) returns1.0e1.

The expressionmath:exp10(0.5) returns3.1622776601683795e0.

The expressionmath:exp10(-1) returns1.0e-1.

The expressionmath:exp10(xs:double('NaN')) returnsxs:double('NaN').

The expressionmath:exp10(xs:double('INF')) returnsxs:double('INF').

The expressionmath:exp10(xs:double('-INF')) returns0.0e0.

4.8.4 math:log

Summary

Returns the natural logarithm of the argument.

Signature

math:log($arg as xs:double?) as xs:double?

Properties

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

Rules

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

Otherwise the result is the natural logarithm of$arg, as defined in the[IEEE 754-2008] specification of thelog function applied to 64-bit binary floating point values.

Notes

The treatment ofdivideByZero andinvalidOperation exceptions is defined in4.2 Arithmetic operators on numeric values.The effect is that if the argument is zero, the result is-INF, and if it is negative, the result isNaN.

Examples

The expressionmath:log(()) returns().

The expressionmath:log(0) returnsxs:double('-INF').

The expressionmath:log(math:exp(1)) returns1.0e0.

The expressionmath:log(1.0e-3) returns-6.907755278982137e0.

The expressionmath:log(2) returns0.6931471805599453e0.

The expressionmath:log(-1) returnsxs:double('NaN').

The expressionmath:log(xs:double('NaN')) returnsxs:double('NaN').

The expressionmath:log(xs:double('INF')) returnsxs:double('INF').

The expressionmath:log(xs:double('-INF')) returnsxs:double('NaN').

4.8.5 math:log10

Summary

Returns the base-ten logarithm of the argument.

Signature

math:log10($arg as xs:double?) as xs:double?

Properties

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

Rules

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

Otherwise the result is the base-10 logarithm of$arg, as defined in the[IEEE 754-2008] specification of thelog10 function applied to 64-bit binary floating point values.

Notes

The treatment ofdivideByZero andinvalidOperation exceptions is defined in4.2 Arithmetic operators on numeric values.The effect is that if the argument is zero, the result is-INF, and if it is negative, the result isNaN.

Examples

The expressionmath:log10(()) returns().

The expressionmath:log10(0) returnsxs:double('-INF').

The expressionmath:log10(1.0e3) returns3.0e0.

The expressionmath:log10(1.0e-3) returns-3.0e0.

The expressionmath:log10(2) returns0.3010299956639812e0.

The expressionmath:log10(-1) returnsxs:double('NaN').

The expressionmath:log10(xs:double('NaN')) returnsxs:double('NaN').

The expressionmath:log10(xs:double('INF')) returnsxs:double('INF').

The expressionmath:log10(xs:double('-INF')) returnsxs:double('NaN').

4.8.6 math:pow

Summary

Returns the result of raising the first argument to the power of the second.

Signature

math:pow($x as xs:double?,$y as xs:numeric) as xs:double?

Properties

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

Rules

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

If$y is an instance ofxs:integer, the result is$x raised to the power of$y as defined in the[IEEE 754-2008] specification of thepown function applied to a 64-bit binary floating point value and an integer.

Otherwise$y is converted to anxs:double by numeric promotion, and the result is the value of$x raised to the power of$y as defined in the[IEEE 754-2008] specification of thepow function applied to two 64-bit binary floating point values.

Notes

The treatment of thedivideByZero andinvalidOperation exceptions is defined in4.2 Arithmetic operators on numeric values. Some of the consequences are illustrated in the examples below.

Examples

The expressionmath:pow((), 93.7) returns().

The expressionmath:pow(2, 3) returns8.0e0.

The expressionmath:pow(-2, 3) returns-8.0e0.

The expressionmath:pow(2, -3) returns0.125e0.

The expressionmath:pow(-2, -3) returns-0.125e0.

The expressionmath:pow(2, 0) returns1.0e0.

The expressionmath:pow(0, 0) returns1.0e0.

The expressionmath:pow(xs:double('INF'), 0) returns1.0e0.

The expressionmath:pow(xs:double('NaN'), 0) returns1.0e0.

The expressionmath:pow(-math:pi(), 0) returns1.0e0.

The expressionmath:pow(0e0, 3) returns0.0e0.

The expressionmath:pow(0e0, 4) returns0.0e0.

The expressionmath:pow(-0e0, 3) returns-0.0e0.

The expressionmath:pow(0, 4) returns0.0e0.

The expressionmath:pow(0e0, -3) returnsxs:double('INF').

The expressionmath:pow(0e0, -4) returnsxs:double('INF').

The expressionmath:pow(-0e0, -3) returnsxs:double('-INF').

The expressionmath:pow(0, -4) returnsxs:double('INF').

The expressionmath:pow(16, 0.5e0) returns4.0e0.

The expressionmath:pow(16, 0.25e0) returns2.0e0.

The expressionmath:pow(0e0, -3.0e0) returnsxs:double('INF').

The expressionmath:pow(-0e0, -3.0e0) returnsxs:double('-INF').(Odd-valued whole numbers are treated specially).

The expressionmath:pow(0e0, -3.1e0) returnsxs:double('INF').

The expressionmath:pow(-0e0, -3.1e0) returnsxs:double('INF').

The expressionmath:pow(0e0, 3.0e0) returns0.0e0.

The expressionmath:pow(-0e0, 3.0e0) returns-0.0e0.(Odd-valued whole numbers are treated specially).

The expressionmath:pow(0e0, 3.1e0) returns0.0e0.

The expressionmath:pow(-0e0, 3.1e0) returns0.0e0.

The expressionmath:pow(-1, xs:double('INF')) returns1.0e0.

The expressionmath:pow(-1, xs:double('-INF')) returns1.0e0.

The expressionmath:pow(1, xs:double('INF')) returns1.0e0.

The expressionmath:pow(1, xs:double('-INF')) returns1.0e0.

The expressionmath:pow(1, xs:double('NaN')) returns1.0e0.

The expressionmath:pow(-2.5e0, 2.0e0) returns6.25e0.

The expressionmath:pow(-2.5e0, 2.00000001e0) returnsxs:double('NaN').

4.8.7 math:sqrt

Summary

Returns the non-negative square root of the argument.

Signature

math:sqrt($arg as xs:double?) as xs:double?

Properties

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

Rules

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

Otherwise the result is the mathematical non-negative square root of$arg as defined in the[IEEE 754-2008] specification of thesquareRoot function applied to 64-bit binary floating point values.

Notes

The treatment of theinvalidOperation exception is defined in4.2 Arithmetic operators on numeric values. The effect is that if the argument is less than zero, the result isNaN.

If$arg is positive or negative zero, positive infinity, orNaN, then the result is$arg. (Negative zero is the only case where the result can have negative sign)

Examples

The expressionmath:sqrt(()) returns().

The expressionmath:sqrt(0.0e0) returns0.0e0.

The expressionmath:sqrt(-0.0e0) returns-0.0e0.

The expressionmath:sqrt(1.0e6) returns1.0e3.

The expressionmath:sqrt(2.0e0) returns1.4142135623730951e0.

The expressionmath:sqrt(-2.0e0) returnsxs:double('NaN').

The expressionmath:sqrt(xs:double('NaN')) returnsxs:double('NaN').

The expressionmath:sqrt(xs:double('INF')) returnsxs:double('INF').

The expressionmath:sqrt(xs:double('-INF')) returnsxs:double('NaN').

4.8.8 math:sin

Summary

Returns the sine of the argument. The argument is an angle in radians.

Signature

math:sin($θ as xs:double?) as xs:double?

Properties

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

Rules

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

Otherwise the result is the sine of$θ (which is treated as an angle in radians) as defined in the[IEEE 754-2008] specification of thesin function applied to 64-bit binary floating point values.

Notes

The treatment of theinvalidOperation andunderflow exceptions is defined in4.2 Arithmetic operators on numeric values.

If$θ is positive or negative zero, the result is$θ.

If$θ is positive or negative infinity, orNaN, then the result isNaN.

Otherwise the result is always in the range -1.0e0 to +1.0e0

Examples

The expressionmath:sin(()) returns().

The expressionmath:sin(0) returns0.0e0.

The expressionmath:sin(-0.0e0) returns-0.0e0.

The expressionmath:sin(math:pi() div 2) returns1.0e0 (approximately).

The expressionmath:sin(-math:pi() div 2) returns-1.0e0 (approximately).

The expressionmath:sin(math:pi()) returns0.0e0 (approximately).

The expressionmath:sin(xs:double('NaN')) returnsxs:double('NaN').

The expressionmath:sin(xs:double('INF')) returnsxs:double('NaN').

The expressionmath:sin(xs:double('-INF')) returnsxs:double('NaN').

4.8.9 math:cos

Summary

Returns the cosine of the argument. The argument is an angle in radians.

Signature

math:cos($θ as xs:double?) as xs:double?

Properties

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

Rules

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

If$θ is positive or negative infinity, orNaN, then the result isNaN.

Otherwise the result is the cosine of$θ (which is treated as an angle in radians) as defined in the[IEEE 754-2008] specification of thecos function applied to 64-bit binary floating point values.

Notes

The treatment of theinvalidOperation exception is defined in4.2 Arithmetic operators on numeric values.

If$θ is positive or negative zero, the result is$θ.

If$θ is positive or negative infinity, orNaN, then the result isNaN.

Otherwise the result is always in the range -1.0e0 to +1.0e0

Examples

The expressionmath:cos(()) returns().

The expressionmath:cos(0) returns1.0e0.

The expressionmath:cos(-0.0e0) returns1.0e0.

The expressionmath:cos(math:pi() div 2) returns0.0e0 (approximately).

The expressionmath:cos(-math:pi() div 2) returns0.0e0 (approximately).

The expressionmath:cos(math:pi()) returns-1.0e0 (approximately).

The expressionmath:cos(xs:double('NaN')) returnsxs:double('NaN').

The expressionmath:cos(xs:double('INF')) returnsxs:double('NaN').

The expressionmath:cos(xs:double('-INF')) returnsxs:double('NaN').

4.8.10 math:tan

Summary

Returns the tangent of the argument. The argument is an angle in radians.

Signature

math:tan($θ as xs:double?) as xs:double?

Properties

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

Rules

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

Otherwise the result is the tangent of$θ (which is treated as an angle in radians) as defined in the[IEEE 754-2008] specification of thetan function applied to 64-bit binary floating point values.

Notes

The treatment of theinvalidOperation andunderflow exceptions is defined in4.2 Arithmetic operators on numeric values.

If$θ is positive or negative infinity, orNaN, then the result isNaN.

Examples

The expressionmath:tan(()) returns().

The expressionmath:tan(0) returns0.0e0.

The expressionmath:tan(-0.0e0) returns-0.0e0.

The expressionmath:tan(math:pi() div 4) returns1.0e0 (approximately).

The expressionmath:tan(-math:pi() div 4) returns-1.0e0 (approximately).

The expression1 div math:tan(math:pi() div 2) returns0.0e0 (approximately).(Mathematically,tan(π/2) is positive infinity. But becausemath:pi() div 2 returns an approximation, the result ofmath:tan(math:pi() div 2) will be a large but finite number.)

The expression1 div math:tan(-math:pi() div 2) returns-0.0e0 (approximately).(Mathematically,tan(-π/2) is negative infinity. But because-math:pi() div 2 returns an approximation, the result ofmath:tan(-math:pi() div 2) will be a large but finite negative number.)

The expressionmath:tan(math:pi()) returns0.0e0 (approximately).

The expressionmath:tan(xs:double('NaN')) returnsxs:double('NaN').

The expressionmath:tan(xs:double('INF')) returnsxs:double('NaN').

The expressionmath:tan(xs:double('-INF')) returnsxs:double('NaN').

4.8.11 math:asin

Summary

Returns the arc sine of the argument.

Signature

math:asin($arg as xs:double?) as xs:double?

Properties

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

Rules

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

Otherwise the result is the arc sine of$arg as defined in the[IEEE 754-2008] specification of theasin function applied to 64-bit binary floating point values. The result is in the range -π/2 to +π/2 radians.

Notes

The treatment of theinvalidOperation andunderflow exceptions is defined in4.2 Arithmetic operators on numeric values.

If$arg is positive or negative zero, the result is$arg.

If$arg isNaN, or if its absolute value is greater than one, then the result isNaN.

In other cases the result is anxs:double value representing an angleθ in radians in the range -π/2 <=θ <= +π/2.

Examples

The expressionmath:asin(()) returns().

The expressionmath:asin(0) returns0.0e0.

The expressionmath:asin(-0.0e0) returns-0.0e0.

The expressionmath:asin(1.0e0) returns1.5707963267948966e0 (approximately).

The expressionmath:asin(-1.0e0) returns-1.5707963267948966e0 (approximately).

The expressionmath:asin(2.0e0) returnsxs:double('NaN').

The expressionmath:asin(xs:double('NaN')) returnsxs:double('NaN').

The expressionmath:asin(xs:double('INF')) returnsxs:double('NaN').

The expressionmath:asin(xs:double('-INF')) returnsxs:double('NaN').

4.8.12 math:acos

Summary

Returns the arc cosine of the argument.

Signature

math:acos($arg as xs:double?) as xs:double?

Properties

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

Rules

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

Otherwise the result is the arc cosine of$arg, as defined in the[IEEE 754-2008] specification of theacos function applied to 64-bit binary floating point values. The result is in the range zero to +π radians.

Notes

The treatment of theinvalidOperation exception is defined in4.2 Arithmetic operators on numeric values.

If$arg isNaN, or if its absolute value is greater than one, then the result isNaN.

In other cases the result is anxs:double value representing an angleθ in radians in the range0 <=θ <= +π.

Examples

The expressionmath:acos(()) returns().

The expressionmath:acos(0) returns1.5707963267948966e0 (approximately).

The expressionmath:acos(-0.0e0) returns1.5707963267948966e0 (approximately).

The expressionmath:acos(1.0e0) returns0.0e0.

The expressionmath:acos(-1.0e0) returns3.141592653589793e0 (approximately).

The expressionmath:acos(2.0e0) returnsxs:double('NaN').

The expressionmath:acos(xs:double('NaN')) returnsxs:double('NaN').

The expressionmath:acos(xs:double('INF')) returnsxs:double('NaN').

The expressionmath:acos(xs:double('-INF')) returnsxs:double('NaN').

4.8.13 math:atan

Summary

Returns the arc tangent of the argument.

Signature

math:atan($arg as xs:double?) as xs:double?

Properties

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

Rules

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

Otherwise the result is the arc tangent of$arg, as defined in the[IEEE 754-2008] specification of theatan function applied to 64-bit binary floating point values. The result is in the range -π/2 to +π/2 radians.

Notes

The treatment of theunderflow exception is defined in4.2 Arithmetic operators on numeric values.

If$arg is positive or negative zero, the result is$arg.

If$arg isNaN then the result isNaN.

In other cases the result is anxs:double value representing an angleθ in radians in the range -π/2 <=θ <= +π/2.

Examples

The expressionmath:atan(()) returns().

The expressionmath:atan(0) returns0.0e0.

The expressionmath:atan(-0.0e0) returns-0.0e0.

The expressionmath:atan(1.0e0) returns0.7853981633974483e0 (approximately).

The expressionmath:atan(-1.0e0) returns-0.7853981633974483e0 (approximately).

The expressionmath:atan(xs:double('NaN')) returnsxs:double('NaN').

The expressionmath:atan(xs:double('INF')) returns1.5707963267948966e0 (approximately).

The expressionmath:atan(xs:double('-INF')) returns-1.5707963267948966e0 (approximately).

4.8.14 math:atan2

Summary

Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis.

Signature

math:atan2($y as xs:double,$x as xs:double) as xs:double

Properties

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

Rules

The result is the value ofatan2(y, x) as defined in the[IEEE 754-2008] specification of theatan2 function applied to 64-bit binary floating point values. The result is in the range -π to +π radians.

Notes

The treatment of theunderflow exception is defined in4.2 Arithmetic operators on numeric values.

If either argument isNaN then the result isNaN.

If$y is positive and$x is positive and finite, then (subject to rules for overflow, underflow and approximation) the value ofatan2($y, $x) isatan($y div $x).

If$y is positive and$x is negative and finite, then (subject to the same caveats) the value ofatan2($y, $x) isπ- atan($y div $x).

Some results for special values of the arguments are shown in the examples below.

Examples

The expressionmath:atan2(+0.0e0, 0.0e0) returns0.0e0.

The expressionmath:atan2(-0.0e0, 0.0e0) returns-0.0e0.

The expressionmath:atan2(+0.0e0, -0.0e0) returns3.141592653589793e0.

The expressionmath:atan2(-0.0e0, -0.0e0) returns-3.141592653589793e0.

The expressionmath:atan2(-1, 0.0e0) returns-1.5707963267948966e0.

The expressionmath:atan2(+1, 0.0e0) returns1.5707963267948966e0.

The expressionmath:atan2(-0.0e0, -1) returns-3.141592653589793e0.

The expressionmath:atan2(+0.0e0, -1) returns3.141592653589793e0.

The expressionmath:atan2(-0.0e0, +1) returns-0.0e0.

The expressionmath:atan2(+0.0e0, +1) returns+0.0e0.

4.9.1 fn:random-number-generator

Summary

Returns a random number generator, which can be used to generate sequences of random numbers.

Signatures

fn:random-number-generator() as map(xs:string, item())

fn:random-number-generator(

$seed

as xs:anyAtomicType?) as map(xs:string, item())

Properties

This function is·deterministic·,·context-independent·,·focus-independent·, and·higher-order·.

Rules

The function returns a random number generator. A random number generator is represented as a map containing three entries. The keys of each entry are strings:

1. The entry with key"number" holds a random number; it is anxs:double greater than or equal to zero (0.0e0), and less than one (1.0e0).

2. The entry with key"next" is a zero-arity function that can be called to return another random number generator.

   The properties of this function are as follows:

   • name: absent

   • parameter names: ()

   • signature:() => map(xs:string, item())

   • non-local variable bindings: none

   • implementation: implementation-dependent

3. The entry with key"permute" is a function with arity 1 (one), which takes an arbitrary sequence as its argument, and returns a random permutation of that sequence.

   The properties of this function are as follows:

   • name: absent

   • parameter names: ("arg")

   • signature:(item()*) => item()*

   • non-local variable bindings: none

   • implementation: implementation-dependent

Calling thefn:random-number-generator function with no arguments is equivalent to calling the single-argument form of the function with an implementation-dependent seed.

Calling thefn:random-number-generator function with an empty sequence as the value of$seed is equivalent to calling the single-argument form of the function with an implementation-dependent seed.

If a$seed is supplied, it may be an atomic value of any type.

Both forms of the function are·deterministic·: calling the function twice with the same arguments, within a single·execution scope·, produces the same results.

The value of thenumber entryshould be such that all eligiblexs:double values are equally likely to be chosen.

The function returned in thepermute entryshould be such that all permutations of the supplied sequence are equally likely to be chosen.

The map returned by thefn:random-number-generator functionmay contain additional entries beyond those specified here, but itmust match the typemap(xs:string, item()). The meaning of any additional entries is·implementation-defined·. To avoid conflict with any future version of this specification, the keys of any such entriesshould start with an underscore character.

Notes

It is not meaningful to ask whether the functions returned in thenext andpermute functions resulting from two separate calls with the same seed are "the same function", but the functions must be equivalent in the sense that calling them produces the same sequence of random numbers.

The repeatability of the results of function calls in different execution scopes is outside the scope of this specification. It isrecommended that when the same seed is provided explicitly, the same random number sequence should be delivered even in different execution scopes; while if no seed is provided, the processor should choose a seed that is likely to be different from one execution scope to another. (The same effect can be achieved explicitly by usingfn:current-dateTime() as a seed.)

The specification does not place strong conformance requirements on the actual randomness of the result; this is left to the implementation. It is desirable, for example, when generating a sequence of random numbers that the sequence should not get into a repeating loop; but the specification does not attempt to dictate this.

Examples

The following example returns a random permutation of the integers in the range 1 to 100:fn:random-number-generator()?permute(1 to 100)

The following example returns a 10% sample of the items in an input sequence$seq, chosen at random:fn:random-number-generator()?permute($seq)[position() = 1 to (count($seq) idiv 10)]

The following code defines a function that can be called to produce a random sequence ofxs:double values in the range zero to one, of specified length:

declare %public function r:random-sequence($length as xs:integer) as xs:double* {  r:random-sequence($length, fn:random-number-generator())};declare %private function r:random-sequence($length as xs:integer,                                             $G as map(xs:string, item())) {  if ($length eq 0)  then ()  else ($G?number, r:random-sequence($length - 1, $G?next()))};r:random-sequence(200);

5.2.1 fn:codepoints-to-string

Summary

Returns anxs:string whose characters have supplied·codepoints·.

Signature

fn:codepoints-to-string($arg as xs:integer*) as xs:string

Properties

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

Rules

The function returns the string made up from the·characters· whose Unicode·codepoints· are supplied in$arg. This will be the zero-length string if$arg is the empty sequence.

Error Conditions

A dynamic error is raised [err:FOCH0001] if any of the codepoints in$arg is not a permitted XML character.

Examples

The expressionfn:codepoints-to-string((66, 65, 67, 72)) returns"BACH".

The expressionfn:codepoints-to-string((2309, 2358, 2378, 2325)) returns"अशॊक".

The expressionfn:codepoints-to-string(()) returns"".

The expressionfn:codepoints-to-string(0) raises errorFOCH0001.

5.2.2 fn:string-to-codepoints

Summary

Returns the sequence of·codepoints· that constitute anxs:string value.

Signature

fn:string-to-codepoints($arg as xs:string?) as xs:integer*

Properties

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

Rules

The function returns a sequence of integers, each integer being the Unicode·codepoint· of the corresponding·character· in$arg.

If$arg is a zero-length string or the empty sequence, the function returns the empty sequence.

Examples

The expressionfn:string-to-codepoints("Thérèse") returns(84, 104, 233, 114, 232, 115, 101).

5.3.1 Collations

A collation is a specification of the manner in which·strings· are compared and, by extension, ordered. When values whose type isxs:string or a type derived fromxs:string are compared (or, equivalently, sorted), the comparisons are inherently performed according to some collation (even if that collation is defined entirely on codepoint values). The[Character Model for the World Wide Web 1.0: Fundamentals] observes that some applications may require different comparison and ordering behaviors than other applications. Similarly, some users having particular linguistic expectations may require different behaviors than other users. Consequently, the collation must be taken into account when comparing strings in any context. Several functions in this and the following section make use of a collation.

Collations can indicate that two different codepoints are, in fact, equal for comparison purposes (e.g., "v" and "w" are considered equivalent in some Swedish collations). Strings can be compared codepoint-by-codepoint or in a linguistically appropriate manner, as defined by the collation.

Some collations, especially those based on the Unicode Collation Algorithm (see[UTS #10]) can be "tailored" for various purposes. This document does not discuss such tailoring, nor does it provide a mechanism to perform tailoring. Instead, it assumes that the collation argument to the various functions below is a tailored and named collation.

The·Unicode codepoint collation· is a collation available in every implementation, which sorts based on codepoint values. For further details see5.3.2 The Unicode Codepoint Collation.

Collations may or may not perform Unicode normalization on strings before comparing them.

This specification assumes that collations are named and that the collation name may be provided as an argument to string functions. Functions that allow specification of a collation do so with an argument whose type isxs:string but whose lexical form must conform to anxs:anyURI. If the collation is specified using a relative URI reference, it is resolved relative to the value of the static base URI property from the static context. This specification also defines the manner in which a default collation is determined if the collation argument is not specified in calls of functions that use a collation but allow it to be omitted.

This specification does not define whether or not the collation URI is dereferenced. The collation URI may be an abstract identifier, or it may refer to an actual resource describing the collation. If it refers to a resource, this specification does not define the nature of that resource. One possible candidate is that the resource is a locale description expressed using the Locale Data Markup Language: see[UTS #35].

Functions such asfn:compare andfn:max that comparexs:string values use a single collation URI to identify all aspects of the collation rules. This means that any parameters such as the strength of the collation must be specified as part of the collation URI. For example, suppose there is a collationhttp://www.example.com/collations/French that refers to a French collation that compares on the basis of base characters. Collations that use the same basic rules, but with higher strengths, for example, base characters and accents, or base characters, accents and case, would need to be given different names, sayhttp://www.example.com/collations/French1 andhttp://www.example.com/collations/French2. Note that some specifications use the term collation to refer to an algorithm that can be parameterized, but in this specification, each possible parameterization is considered to be a distinct collation.

The XQuery/XPath static context includes a provision for a default collation that can be used for string comparisons and ordering operations. See the description of the static context inSection 2.1.1 Static Context^XP31. If the default collation is not specified by the user or the system, the default collation is the·Unicode codepoint collation·.

5.3.2 The Unicode Codepoint Collation

[Definition] The collation URIhttp://www.w3.org/2005/xpath-functions/collation/codepoint identifies a collation which must be recognized by every implementation: it is referred to as theUnicode codepoint collation (not to be confused with the Unicode collation algorithm).

The Unicode codepoint collation does not perform any normalization on the supplied strings.

The collation is defined as follows. Each of the two strings is converted to a sequence of integers using thefn:string-to-codepoints function. These two sequences$A and$B are then compared as follows:

• If both sequences are empty, the strings are equal.

• If one sequence is empty and the other is not, then the string corresponding to the empty sequence is less than the other string.

• If the first integer in$A is less than the first integer in$B, then the string corresponding to$A is less than the string corresponding to$B.

• If the first integer in$A is greater than the first integer in$B, then the string corresponding to$A is greater than the string corresponding to$B.

• Otherwise (the first pair of integers are equal), the result is obtained by applying the same rules recursively tofn:tail($A) andfn:tail($B)

5.3.3 The Unicode Collation Algorithm

This specification defines a family of collation URIs representing tailorings of the Unicode Collation Algorithm (UCA) as defined in[UTS #10]. The parameters used for tailoring the UCA are based on the parameters defined in the Locale Data Markup Language (LDML), defined in[UTS #35].

This family of URIs use the scheme and pathhttp://www.w3.org/2013/collation/UCA followed by an optional query part. The query part, if present, consists of a question mark followed by a sequence of zero or more semicolon-separated parameters. Each parameter is a keyword-value pair, the keyword and value being separated by an equals sign.

All implementations must recognize URIs in this family in thecollation argument of functions that take a collation argument.

If thefallback parameter is present with the valueno, then the implementationmust either use a collation that conforms with the rules in the Unicode specifications for the requested tailoring, or fail with a static or dynamic error indicating that it does not provide the collation (the error code should be the same as if the collation URI were not recognized). If thefallback parameter is omitted or takes the valueyes, and if the collation URI is well-formed according to the rules in this section, then the implementationmust accept the collation URI, andshould use the available collation that most closely reflects the user's intentions. For example, if the collation URI requested ishttp://www.w3.org/2013/collation/UCA?lang=se;fallback=yes and the implementation does not include a fully conformant version of the UCA tailored for Swedish, then itmay choose to use a Swedish collation that is known to differ from the UCA definition, or one whose conformance has not been established. It might even, as a last resort, fall back to using codepoint collation.

If two query parameters use the same keyword then the last one wins. If a query parameter uses a keyword or value which is not defined in this specification then the meaning is·implementation-defined·. If the implementation recognizes the meaning of the keyword and value then itshould interpret it accordingly; if it does not recognize the keyword or value then if thefallback parameter is present with the valueno it should reject the collation as unsupported, otherwise it should ignore the unrecognized parameter.

The following query parameters are defined. If any parameter is absent, the default is·implementation-defined· except where otherwise stated. The meaning given for each parameter is non-normative; the normative specification is found in[UTS #35].

5.3.4 The HTML ASCII Case-Insensitive Collation

The collation URIhttp://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive must be recognized by every implementation. It is used to refer to the HTML ASCII case-insensitive collation as defined in[HTML5: A vocabulary and associated APIs for HTML and XHTML] (section 2.5,Case sensitivity and string comparison). It is used, for example, when matching HTMLclass attribute values.

HTML5 defines the semantics of equality matching using this collation; it does not define rules for ordering. If the collation is used for ordering, the results are·implementation-defined·. The collation supports collation units and can therefore be used with functions such asfn:contains; each Unicode codepoint is a single collation unit.

5.3.5 Choosing a collation

Many functions have two signatures, where one signature includes a$collation argument and the other omits this argument.

The collation to use for these functions is determined by the following rules:

1. If the function specifies an explicit collation, CollationA (e.g., if the optional collation argument is specified in a call of thefn:compare function), then:

   • If CollationA is supported by the implementation, then CollationA is used.

   • Otherwise, a dynamic error is raised [err:FOCH0002].

2. If no collation is explicitly specified for the function and the default collation in the XQuery/XPath static context is CollationB, then:

   • If CollationB is supported by the implementation, then CollationB is used.

   • Otherwise, a dynamic error is raised [err:FOCH0002].

If the value of the collation argument is a relative URI reference, it is resolved against the base-URI from the static context. If it is a relative URI reference and cannot be resolved, perhaps because the base-URI property in the static context is absent, a dynamic error is raised [err:FOCH0002].

5.3.6 fn:compare

Summary

Returns -1, 0, or 1, depending on whether$comparand1 collates before, equal to, or after$comparand2 according to the rules of a selected collation.

Signatures

fn:compare($comparand1 as xs:string?,$comparand2 as xs:string?) as xs:integer?

fn:compare(	$comparand1	as xs:string?,
	$comparand2	as xs:string?,
	$collation	as xs:string) as xs:integer?

Properties

The two-argument form of this function is·deterministic·,·context-dependent·, and·focus-independent·. It depends on collations.

The three-argument form of this function is·deterministic·,·context-dependent·, and·focus-independent·. It depends on collations, and static base URI.

Rules

Returns -1, 0, or 1, depending on whether the value of the$comparand1 is respectively less than, equal to, or greater than the value of$comparand2, according to the rules of the collation that is used.

The collation used by this function is determined according to the rules in5.3.5 Choosing a collation.

If either$comparand1 or$comparand2 is the empty sequence, the function returns the empty sequence.

This function, called with the first signature, defines the semantics of the "eq", "ne", "gt", "lt", "le" and "ge" operators onxs:string values.

Examples

The expressionfn:compare('abc', 'abc') returns0.

The expressionfn:compare('Strasse', 'Straße') returns0.(Assuming the default collation includes provisions that equate "ss" and the (German) character "ß" ("sharp-s"). Otherwise, the returned value depends on the semantics of the default collation.)

The expressionfn:compare('Strasse', 'Straße', 'http://www.w3.org/2013/collation/UCA?lang=de;strength=primary') returns0.(The specified collation equates "ss" and the (German) character "ß" ("sharp-s").)

The expressionfn:compare('Strassen', 'Straße') returns1.(Assuming the default collation includes provisions that treat differences between "ss" and the (German) character "ß" ("sharp-s") with less strength than the differences between the base characters, such as the final "n". ).

5.3.7 fn:codepoint-equal

Summary

Returns true if two strings are equal, considered codepoint-by-codepoint.

Signature

fn:codepoint-equal(	$comparand1	as xs:string?,
	$comparand2	as xs:string?) as xs:boolean?

Properties

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

Rules

If either argument is the empty sequence, the function returns the empty sequence.

Otherwise, the function returnstrue orfalse depending on whether the value of$comparand1 is equal to the value of$comparand2, according to the Unicode codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

Notes

This function allowsxs:anyURI values to be compared without having to specify the Unicode codepoint collation.

Examples

The expressionfn:codepoint-equal("abcd", "abcd") returnstrue().

The expressionfn:codepoint-equal("abcd", "abcd ") returnsfalse().

The expressionfn:codepoint-equal("", "") returnstrue().

The expressionfn:codepoint-equal("", ()) returns().

The expressionfn:codepoint-equal((), ()) returns().

5.3.8 fn:collation-key

Summary

Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation.

Signatures

fn:collation-key($key as xs:string) as xs:base64Binary

fn:collation-key($key as xs:string,$collation as xs:string) as xs:base64Binary

Properties

This function is·deterministic·,·context-dependent·, and·focus-independent·. It depends on collations.

Rules

Calling the one-argument version of this function is equivalent to calling the two-argument version supplying the default collation as the second argument.

The function returns an·implementation-dependent· value with the property that, for any two strings$K1 and$K2:

• collation-key($K1, $C) eq collation-key($K2, $C) if and only ifcompare($K1, $K2, $C) eq 0

• collation-key($K1, $C) lt collation-key($K2, $C) if and only ifcompare($K1, $K2, $C) lt 0

The collation used by this function is determined according to the rules in5.3.5 Choosing a collation. Collation keys are defined asxs:base64Binary values to ensure unambiguous and context-free comparison semantics.

An implementation is free to generate a collation key in any convenient way provided that it always generates the same collation key for two strings that are equal under the collation, and different collation keys for strings that are not equal. This holds only within a single·execution scope·; an implementation is under no obligation to generate the same collation keys during a subsequent unrelated query or transformation.

It is possible to define collations that do not have the ability to generate collation keys. Supplying such a collation will cause the function to fail. The ability to generate collation keys is an·implementation-defined· property of the collation.

Error Conditions

An error is raised [err:FOCH0004] if the specified collation does not support the generation of collation keys.

Notes

The function is provided primarily for use with maps. If a map is required where codepoint equality is inappropriate for comparing keys, then a common technique is to normalize the key so that equality matching becomes feasible. There are many ways keys can be normalized, for example by use of functions such asfn:upper-case,fn:lower-case,fn:normalize-space, orfn:normalize-unicode, but this function provides a way of normalizing them according to the rules of a specified collation. For example, if the collation ignores accents, then the function will generate the same collation key for two input strings that differ only in their use of accents.

The result of the function is defined to be anxs:base64Binary value. Binary values are chosen because they have unambiguous and context-free comparison semantics, because the value space is unbounded, and because the ordering rules are such that between any two values in the ordered value space, an arbitrary number of further values can be interpolated. The choice betweenxs:base64Binary andxs:hexBinary is arbitrary; the only operation that behaves differently between the two binary data types is conversion to/from a string, and this operation is not one that is normally required for effective use of collation keys.

For collations based on the Unicode Collation Algorithm, an algorithm for computing collation keys is provided in[UTS #10]. Implementations arenot required to use this algorithm.

This specification does not mandate that collation keys should retain ordering. This is partly because the primary use case is for maps, where only equality comparisons are required, and partly to allow the use of binary data types (which are currently unordered types) for the result. The specification may be revised in a future release to specify that ordering is preserved.

The fact that collation keys are ordered can be exploited in XQuery, whoseorder by clause does not allow the collation to be selected dynamically. This restriction can be circumvented by rewriting the clauseorder by $e/@key collation "URI" asorder by fn:collation-key($e/@key, $collation), where$collation allows the collation to be chosen dynamically.

Note thatxs:base64Binary becomes an ordered type in XPath 3.1, making binary collation keys possible.

Examples

let $C := 'http://www.w3.org/2013/collation/UCA?strength=primary'

The expressionmap:merge((map{collation-key("A", $C):1}, map{collation-key("a", $C):2}), map{"duplicates":"use-last"})(collation-key("A", $C)) returns2.(Given that the keys of the two entries are equal under the rules of the chosen collation, only one of the entries can appear in the result; the one that is chosen is the one from the last map in the input sequence.)

The expressionlet $M := map{collation-key("A", $C):1, collation-key("B", $C):2} return $M(collation-key("a", $C)) returns1.(The strings "A" and "a" have the same collation key under this collation.)

As the above examples illustrate, it is important that when thecollation-key function is used to add entries to a map, then it must also be used when retrieving entries from the map. This process can be made less error-prone by encapsulating the map within a function:function($k) {$M(collation-key($k, $collation)}.

5.3.9 fn:contains-token

Summary

Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation.

Signatures

fn:contains-token($input as xs:string*,$token as xs:string) as xs:boolean

fn:contains-token(	$input	as xs:string*,
	$token	as xs:string,
	$collation	as xs:string) as xs:boolean

Properties

The two-argument form of this function is·deterministic·,·context-dependent·, and·focus-independent·. It depends on collations.

The three-argument form of this function is·deterministic·,·context-dependent·, and·focus-independent·. It depends on collations, and static base URI.

Rules

If$input is the empty sequence, the function returnsfalse.

Leading and trailing whitespace is trimmed from the supplied value of$token. If the trimmed value of$token is a zero-length string, the function returnsfalse.

The collation used by this function is determined according to the rules in5.3.5 Choosing a collation.

The function returns true if and only if there is string in$input which, after tokenizing at whitespace boundaries, contains a token that is equal to the trimmed value of$token under the rules of the selected collation.

That is, the function returns the value of the expression:

some $t in $input!fn:tokenize(.) satisfies                  compare($t, fn:replace($token, '^\s*|\s*$', ''), $collation) eq 0)

Notes

Interior whitespace within$token will cause the function to returnfalse, unless such whitespace is ignored by the selected collation.

This function can be used for processing space-separated attribute values (for example, the XHTML and DITA class attribute), where one often needs to test for the presence of a single token in a space-separated list. The function is designed to work both when the attribute has been validated against an XSD list type, and when it appears as a single untyped string. It differs from the HTML 5 definition in that HTML 5 recognizes form feed (x0C) as a separator. To reproduce the HTML token matching behavior, the HTML ASCII case-insensitive collation should be used: see5.3.4 The HTML ASCII Case-Insensitive Collation.

Examples

The expressionfn:contains-token("red green blue ", "red") returnstrue().

The expressionfn:contains-token(("red", "green", "blue"), " red ") returnstrue().

The expressionfn:contains-token("red, green, blue", "red") returnsfalse().

The expressionfn:contains-token("red green blue", "RED", "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive") returnstrue().

Notes:

When the above operators and functions are applied to datatypes derived fromxs:string, they are guaranteed to return values that are instances ofxs:string, but the value might or might not be an instance of the particular subtype ofxs:string to which they were applied.

The strings returned byfn:concat andfn:string-join are not guaranteed to be normalized. But see note infn:concat.

5.4.1 fn:concat

Summary

Returns the concatenation of the string values of the arguments.

Operator Mapping

The two-argument form of this function defines the semantics of the "||" operator.

Signature

fn:concat(	$arg1	as xs:anyAtomicType?,
	$arg2	as xs:anyAtomicType?,
	...	) as xs:string

Properties

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

Rules

This function accepts two or morexs:anyAtomicType arguments and casts each one toxs:string. The function returns thexs:string that is the concatenation of the values of its arguments after conversion. If any argument is the empty sequence, that argument is treated as the zero-length string.

Thefn:concat function is specified to allow two or more arguments, which are concatenated together. This is the only function specified in this document that allows a variable number of arguments. This capability is retained for compatibility with[XML Path Language (XPath) Version 1.0].

Notes

As mentioned in5.1 String types Unicode normalization is not automatically applied to the result offn:concat. If a normalized result is required,fn:normalize-unicode can be applied to thexs:string returned byfn:concat. The following XQuery:

let $v1 := "I plan to go to Mu"let $v2 := "?nchen in September"return concat($v1, $v2)

where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈", will return:

"I plan to go to Mu?nchen in September"

where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈". It is worth noting that the returned value is not normalized in NFC; however, it is normalized in NFD.

However, the following XQuery:

let $v1 := "I plan to go to Mu"let $v2 := "?nchen in September"return normalize-unicode(concat($v1, $v2))

where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈", will return:

"I plan to go to München in September"

This returned result is normalized in NFC.

Examples

The expressionfn:concat('un', 'grateful') returns"ungrateful".

The expressionfn:concat('Thy ', (), 'old ', "groans", "", ' ring', ' yet', ' in', ' my', ' ancient',' ears.') returns"Thy old groans ring yet in my ancient ears.".

The expressionfn:concat('Ciao!',()) returns"Ciao!".

The expressionfn:concat('Ingratitude, ', 'thou ', 'marble-hearted', ' fiend!') returns"Ingratitude, thou marble-hearted fiend!".

The expressionfn:concat(01, 02, 03, 04, true()) returns"1234true".

The expression10 || '/' || 6 returns"10/6".

5.4.2 fn:string-join

Summary

Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.

Signatures

fn:string-join($arg1 as xs:anyAtomicType*) as xs:string

fn:string-join($arg1 as xs:anyAtomicType*,$arg2 as xs:string) as xs:string

Properties

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

Rules

The effect of calling the single-argument version of this function is the same as calling the two-argument version with$arg2 set to a zero-length string.

The function returns anxs:string created bycasting each item in the sequence$arg1 to anxs:string, and then concatenating the result strings in order, using the value of$arg2 as a separator between adjacent strings. If the value of$arg2 is the zero-length string, then the members of$arg1 are concatenated without a separator.

Notes

If the value of$arg1 is the empty sequence, the function returns the zero-length string.

Examples

The expressionfn:string-join(1 to 9) returns"123456789".

The expressionfn:string-join(('Now', 'is', 'the', 'time', '...'), ' ') returns"Now is the time ...".

The expressionfn:string-join(('Blow, ', 'blow, ', 'thou ', 'winter ', 'wind!'), '') returns"Blow, blow, thou winter wind!".

The expressionfn:string-join((), 'separator') returns"".

The expressionfn:string-join(1 to 5, ', ') returns"1, 2, 3, 4, 5".

let $doc := <doc>  <chap>    <section xml:id="xyz"/>  </chap></doc>

The expression$doc//@xml:id ! fn:string-join((node-name(), '="', ., '"')) returns'xml:id="xyz"'.

The expression$doc//section ! fn:string-join(ancestor-or-self::*/name(), '/') returns"doc/chap/section".

5.4.3 fn:substring

Summary

Returns the portion of the value of$sourceString beginning at the position indicated by the value of$start and continuing for the number of·characters· indicated by the value of$length.

Signatures

fn:substring($sourceString as xs:string?,$start as xs:double) as xs:string

fn:substring(	$sourceString	as xs:string?,
	$start	as xs:double,
	$length	as xs:double) as xs:string

Properties

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

Rules

If the value of$sourceString is the empty sequence, the function returns the zero-length string.

Otherwise, the function returns a string comprising those·characters· of$sourceString whose index position (counting from one) is greater than or equal to the value of$start (rounded to an integer), and (if$length is specified) less than the sum of$start and$length (both rounded to integers).

The characters returned do not extend beyond$sourceString. If$start is zero or negative, only those characters in positions greater than zero are returned.

More specifically, the three argument version of the function returns the characters in$sourceString whose position$p satisfies:

fn:round($start) <= $p and $p < fn:round($start) + fn:round($length)

The two argument version of the function assumes that$length is infinite and thus returns the·characters· in$sourceString whose position$p satisfies:

fn:round($start) <= $p

In the above computations, the rules forop:numeric-less-than andop:numeric-greater-than apply.

Notes

The first character of a string is located at position 1, not position 0.

The second and third arguments allowxs:double values (rather than requiringxs:integer) in order to achieve compatibility with XPath 1.0.

A surrogate pair counts as one character, not two.

The consequences of supplying values such asNaN or positive or negative infinity for the$start or$length arguments follow from the above rules, and are not always intuitive.

Examples

The expressionfn:substring("motor car", 6) returns" car".(Characters starting at position 6 to the end of$sourceString are selected.)

The expressionfn:substring("metadata", 4, 3) returns"ada".(Characters at positions greater than or equal to 4 and less than 7 are selected.)

The expressionfn:substring("12345", 1.5, 2.6) returns"234".(Characters at positions greater than or equal to 2 and less than 5 are selected.)

The expressionfn:substring("12345", 0, 3) returns"12".(Characters at positions greater than or equal to 0 and less than 3 are selected. Since the first position is 1, these are the characters at positions 1 and 2.)

The expressionfn:substring("12345", 5, -3) returns"".(Characters at positions greater than or equal to 5 and less than 2 are selected.)

The expressionfn:substring("12345", -3, 5) returns"1".(Characters at positions greater than or equal to -3 and less than 2 are selected. Since the first position is 1, this is the character at position 1.)

The expressionfn:substring("12345", 0 div 0E0, 3) returns"".(Since0 div 0E0 returnsNaN, andNaN compared to any other number returnsfalse, no characters are selected.)

The expressionfn:substring("12345", 1, 0 div 0E0) returns"".(As above.)

The expressionfn:substring((), 1, 3) returns"".

The expressionfn:substring("12345", -42, 1 div 0E0) returns"12345".(Characters at positions greater than or equal to -42 and less thanINF are selected.)

The expressionfn:substring("12345", -1 div 0E0, 1 div 0E0) returns"".(Since the value of-INF + INF isNaN, no characters are selected.)