XPath and XQuery Functions and Operators 4.0

1.7.1 Item Types

The first diagram illustrates the relationship of various item types.

Item types are used to characterize the various types of item that can appear in a sequence (nodes, atomic values, and functions), and they are therefore used in declaring the types of variables or the argument types and result types of functions.

Item types in the data model form a directed graph, rather than a hierarchy or lattice: in the relationship defined by the derived-from(A, B) function, some types are derived from more than one other type. Examples include functions (function(xs:string) as xs:int is substitutable for function(xs:NCName) as xs:int and also for function(xs:string) as xs:decimal), and union types (A is substitutable for union(A, B) and also for union(A, C). In XDM, item types include node types, function types, and built-in atomic types. The diagram, which shows only hierarchic relationships, is therefore a simplification of the full model.

1.7.2 Schema Type Hierarchy

The next diagram illustrate the schema type subsystem, in which all types are derived from xs:anyType.

Schema types include built-in types defined in the XML Schema specification, and user-defined types defined using mechanisms described in the XML Schema specification. Schema types define the permitted contents of nodes. The main categories are complex types, which define the permitted content of elements, and simple types, which can be used to constrain the values of both elements and attributes.

1.7.3 Atomic Type Hierarchy

The final diagram shows all of the atomic types, including the primitive simple types and the built-in types derived from the primitive simple types. This includes all the built-in datatypes defined in [XML Schema Part 2: Datatypes Second Edition].

Atomic types are both item types and schema types, so the root type xs:anyAtomicType may be found in both the previous diagrams.

1.8.1 Strings, characters, and codepoints

This document uses the terms string, character, and codepoint with meanings that are normatively defined in [XQuery and XPath Data Model (XDM) 3.1], and which are paraphrased here for ease of reference:

[Definition] A character is an instance of the Char^XML production of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].

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

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

Because these terms appear so frequently, they are hyperlinked to the definition only when there is a particular desire to draw the reader’s attention to the definition; the absence of a hyperlink does not mean that the term is being used in some other sense.

It is ·implementation-defined· which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used.

Unless explicitly stated, the functions in this document do not ensure that any returned xs:string values are normalized in the sense of [Character Model for the World Wide Web 1.0: Fundamentals].

1.8.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] An expanded-QName is a value in the value space of the xs:QName datatype as defined in the XDM data model (see [XQuery and XPath Data Model (XDM) 3.1]): that is, a triple containing namespace prefix (optional), namespace URI (optional), and local name. Two expanded QNames are equal if the namespace URIs are the same (or both absent) and the local names are the same. The prefix plays no part in the comparison, but is used only if the expanded QName needs to be converted back to a string.

The term URI is used as follows:

[Definition] Within this specification, the term URI refers to Universal Resource Identifiers as defined in [RFC 3986] and extended in [RFC 3987] with a new name IRI. The term URI Reference, unless otherwise stated, refers to a string in the lexical space of the xs:anyURI datatype as defined in [XML Schema Part 2: Datatypes Second Edition].

1.8.3 Conformance terminology

In this specification:

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

  • When the sentence relates to an implementation of a function (for example "All implementations must recognize URIs of the form ...") then an implementation is not conformant unless it behaves as stated.

  • When the sentence relates to the result of a function (for example "The result must have the same type as $arg") then the implementation is not conformant unless it delivers a result as stated.

  • When the sentence relates to the arguments to a function (for example "The value of $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 verb may, when rendered in small capitals, indicates optional or discretionary behavior. The statement “An implementation may do X” implies that it is implementation-dependent whether or not it does X.

• The auxiliary verb should, when rendered in small capitals, indicates desirable or recommended behavior. The statement “An implementation should do X” implies that it is desirable to do X, but implementations may choose to do otherwise if this is judged appropriate.

[Definition] Where behavior is described as implementation-defined, variations between processors are permitted, but a conformant implementation must document the choices it has made.

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

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

In this section the term function, unless otherwise specified, applies equally to function definitions^XP40 (which can be the target of a static function call) and function items^DM40 (which can be the target of a dynamic function call).

[Definition] An execution scope is a sequence of calls to the function library during which certain aspects of the state are required to remain invariant. For example, two calls to fn:current-dateTime within the same execution scope will return the same result. The execution scope is defined by the host language that invokes the function library. In XSLT, for example, any two function calls executed during the same transformation are in the same execution scope (except that static expressions, such as those used in use-when attributes, are in a separate execution scope).

The following definition explains more precisely what it means for two function calls to return the same result:

[Definition] Two values $V1 and $V2 are defined to be identical if they contain the same number of items and the items are pairwise identical. Two items are identical if and only if one of the following conditions applies:

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

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 entry E₁ in the first map there is an entry E₂ in the second map such that the keys of E₁ and E₂ are ·the same key·, and the corresponding values V₁ and V₂ 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 the two function items have the same function identity. The concept of function identity is explained in Section 2.9.4 Function Items^DM40.Both items are function items, neither item is a map or array, and the two function items have the same function identity. The concept of function identity is explained in Section 2.9.1 Function Items^DM40.Both items are function items, neither item is a map or array, and the two function items have the same function identity. The concept of function identity is explained in Section 2.9.42.9.1 Function Items^DM40.

Some functions produce results that depend not only on their explicit arguments, but also on the static and dynamic context.

[Definition] A function definition^XP40 may have the property of being context-dependent: the result of such a function depends on the values of properties in the static and dynamic evaluation context of the caller as well as on the actual supplied arguments (if any). A function definition may be context-dependent for some arities in its arity range, and context-independent for others: for example fn:name#0 is context-dependent while fn:name#1 is context-independent.

[Definition] A function definition^XP40 that is not ·context-dependent· is called context-independent.

The main categories of context-dependent functions are:

• Functions that explicitly deliver the value of a component of the static or dynamic context, for example fn:static-base-uri, fn:default-collation, fn:position, or fn:last.

• Functions with an optional parameter whose default value is taken from the static or dynamic context of the caller, usually either the context item (for example, fn:node-name) or the default collation (for example, fn:index-of).

• Functions that use the static context of the caller to expand or disambiguate the values of supplied arguments: for example fn:doc expands its first argument using the static base URI of the caller, and xs:QName expands its first argument using the in-scope namespaces of the caller.

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

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

A function definition that is context-dependent can be used as the target of a named function reference, can be partially applied, and can be found using fn:function-lookup. The principle in such cases is that the static context used for the function evaluation is taken from the static context of the named function reference, partial function application, or the call on fn:function-lookup; and the dynamic context for the function evaluation is taken from the dynamic context of the evaluation of the named function reference, partial function application, or the call of fn:function-lookup. These constructs all deliver a function item^DM40 having a captured context based on the static and dynamic context of the construct that created the function item. This captured context forms part of the closure of the function item.

The result of a dynamic call to a function item never depends on the static or dynamic context of the dynamic function call, only (where relevant) on the the captured context held within the function item itself.

The fn:function-lookup function is a special case because it is potentially dependent on everything in the static and dynamic context. This is because the static and dynamic context of the call to fn:function-lookupform the captured context of the function item that fn:function-lookup returns.

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

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

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

• [Definition] Some functions (such as fn:distinct-values, fn:unordered, map:keys, and map:for-each) produce results in an ·implementation-defined· or ·implementation-dependent· order. In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are said to be nondeterministic with respect to ordering.

• Some functions (such as fn:analyze-string, fn:parse-xml, fn:parse-xml-fragment, and fn:json-to-xml) construct a tree of nodes to represent their results. There is no guarantee that repeated calls with the same arguments will return the same identical node (in the sense of the is operator). However, if non-identical nodes are returned, their content will be the same in the sense of the fn:deep-equal function. Such a function is said to be nondeterministic with respect to node identity.Some functions (such as fn:analyze-string, fn:parse-xml, fn:parse-xml-fragment, and fn:json-to-xml) construct a tree of nodes to represent their results. There is no guarantee that repeated calls with the same arguments will return the same identical node (in the sense of the is operator). However, if non-identical nodes are returned, their content will be the same in the sense of the fn:deep-equal function. Such a function is said to be non-deterministic with respect to node identity.Some functions (such as fn:analyze-string, fn:parse-xml, fn:parse-xml-fragment, and fn:json-to-xml) construct a tree of nodes to represent their results. There is no guarantee that repeated calls with the same arguments will return the same identical node (in the sense of the is operator). However, if non-identical nodes are returned, their content will be the same in the sense of the fn:deep-equal function. Such a function is said to be nondeterministicnon-deterministic with respect to node identity.

• Some functions (such as fn:doc and fn:collection) create new nodes by reading external documents. Such functions are guaranteed to be ·deterministic· with the exception that an implementation is allowed to make them nondeterministicnon-deterministic as a user option.

Where the results of a function are described as being (to a greater or lesser extent) ·implementation-defined· or ·implementation-dependent·, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results.

3.1.1 fn:error

Summary

Calling the fn:error function raises an application-defined error.

Signature

fn:error(
$code	as xs:QName?	:= (),
$description	as xs:string?	:= (),
$value	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 the fn:error function supply information that is associated with the error condition and that is made available to a caller that asks for information about the error. The error may be caught either by the host language (using a try/catch construct in XSLT or XQuery, for example), or by the calling application or external processing environment. The way in which error information is returned to the external processing environment is ·implementation-dependent·.

There are three pieces of information that may be associated with an error.

• The $code is an error code that distinguishes this error from others. It is an xs:QName; the namespace URI conventionally identifies the component, subsystem, or authority responsible for defining the meaning of the error code, while the local part identifies the specific error condition. The namespace URI http://www.w3.org/2005/xqt-errors is used for errors defined in this specification; other namespace URIs may be used for errors defined by the application.

  If the external processing environment expects the error code to be returned as a URI or a string rather than as an xs:QName, then an error code with namespace URI NS and local part LP will be returned in the form NS#LP. The namespace URI part of the error code should therefore not include a fragment identifier.

  If no value is supplied for the $code argument, or if the value supplied is an empty sequence, the effective value of the error code is fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000').

• The $description is a natural-language description of the error condition.

  If no value is supplied for the $description argument, or if the value supplied is an empty sequence, then the effective value of the description is ·implementation-dependent·.

• The $value 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 $value argument or if the value supplied is an empty sequence, 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

Expression:	error()
Expression:	error()
Result:	error()	Raises error FOER0000. (This returns the URI http://www.w3.org/2005/xqt-errors#FOER0000 (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.)
Expression:	error( QName( 'http://www.example.com/HR', 'myerr:toohighsal' ), 'Salary is too high' )
Expression:	error( QName( 'http://www.example.com/HR', 'myerr:toohighsal' ), 'Salary is too high' )
Result:	error( QName( 'http://www.example.com/HR', 'myerr:toohighsal' ), 'Salary is too high' )	Raises error myerr:toohighsal. (This returns http://www.example.com/HR#toohighsal and the xs:string"Salary is too high" (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.)

History

Changed in 4.0: All three arguments are now optional, and each argument can be set to an empty sequence. Previously if $description was supplied, it could not be empty.All three arguments are now optional, and each argument can be set to an empty sequence. Previously if $description was supplied, it could not be empty.Changed in 4.0: All three arguments are now optional, and each argument can be set to an empty sequence. Previously if $description was supplied, it could not be empty.

3.2.1 fn:trace

Summary

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

Signature

fn:trace(
$input	as item()*,
$label	as xs:string?	:= ()
) as item()*

Properties

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

Rules

The function returns $input, unchanged.

In addition, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an ·implementation-defined· destination.

Any serialization of the implementation's trace output must not raise an error. This can be achieved (for example) by using a serialization method that can handle arbitrary input, such as the adaptive output method (see Section 10 Adaptive Output Method ^SER31).The serialization of the trace output must not raise an error. This can be achieved (for example) by using a serialization method that can handle arbitrary input, such as the adaptive output method (see Section 10 Adaptive Output Method ^SER31).AnyThe serialization of the implementation's trace output must not raise an error. This can be achieved (for example) by using a serialization method that can handle arbitrary input, such as the adaptive output method (see Section 10 Adaptive Output Method ^SER31).

The format of the trace output and its order are ·implementation-dependent·. Therefore, the order in which the output appears is not predictable. This also means that if dynamic errors occur (whether or not they are caught using try/catch), it may be unpredictable whether any output is reportedlogged before the error occurs.

Notes

If the trace information is unrelated to a specific value, fn:message can be used instead.If the trace information is unrelated to a specific value, fn:log can be used instead.If the trace information is unrelated to a specific value, fn:messagefn:log can be used instead.

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 an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will return $v. The processor may output "124.84" and "the value of $v is:" to an ·implementation-defined· destination.Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, $v is an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will output the strings "124.84" and "the value of $v is:" in an implementation-dependent order.Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, $v is an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will returnoutput $vthe. The processor strings may output "124.84" and "the value of $v is:" toin an ·implementation-defined· destinationimplementation-dependent order.

The following two XPath expressions are identical, but only the second provides trace feedback to the user:

The following two XPath expressions are identical, but only the second provides trace feedback to the user:

//book[xs:decimal(@price) gt 100] //book[xs:decimal(@price) gt 100] => trace('books more expensive than €100:')

//book[xs:decimal(@price) gt 100] //book[xs:decimal(@price) gt 100] => trace('books more expensive than €100:')

History

Changed in 4.0: The $label argument can now be set to an empty sequence. Previously if $label was supplied, it could not be empty.The $label argument can now be set to an empty sequence. Previously if $label was supplied, it could not be empty.Changed in 4.0: The $label argument can now be set to an empty sequence. Previously if $label was supplied, it could not be empty.

3.2.2 fn:messagefn:log

Summary

Outputs trace information and discards the result.

Signature

fn:message(fn:log(fn:messagefn:log(
$input	as item()*,
$label	as xs:string?	:= ()
) as empty-sequence()

Properties

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

Rules

Similar to fn:trace, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an ·implementation-defined· destination.

In contrast to fn:trace, the function returns an empty sequence.

Any serialization of the implementation’s log output must not raise an error. This can e.g. be achieved by using a serialization method that can handle arbitrary input, such as the Section 10 Adaptive Output Method ^SER31.The serialization of the log output must not raise an error. This can e.g. be achieved by using a serialization method that can handle arbitrary input, such as the Section 10 Adaptive Output Method ^SER31.AnyThe serialization of the implementation’s log output must not raise an error. This can e.g. be achieved by using a serialization method that can handle arbitrary input, such as the Section 10 Adaptive Output Method ^SER31.

The format of the logtrace output and its order are ·implementation-dependent·. Therefore, the order in which the output appears is not predictable. This also means that if dynamic errors occur (whether or not they are caught using try/catch), it may be unpredictable whether any output is logged before the error occurs.

Notes

The function can be used for debugging. It can also be helpful in productive environments, e.g. to store dynamic input and evaluations to log files.

Examples

The following two XPath expressions are identical, but only the second logs any feedback:

//book[xs:decimal(@price) lt 1000] //book[if (xs:decimal(@price) lt 1000) then true() else message(@price, @title || ' is unexpectedly expensive: ')]

History

New function.

3.2.3 fn:stack-trace

Summary

Returns implementation-dependent information about the current state of execution.

Signature

fn:stack-trace() as xs:string

Properties

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

Rules

The result of the function is an ·implementation-dependent· string containing diagnostic information about the current state of execution.

The function is nondeterministicnon-deterministic: multiple calls will typically produce different results.

Notes

The function will typically be called to assist in diagnosing dynamic errors.

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: see 4.2 Arithmetic operators on numeric values.

Notes

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

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: see 4.2 Arithmetic operators on numeric values.

Notes

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

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: see 4.2 Arithmetic operators on numeric values.

Notes

For xs:float or xs:double values, if one of the operands is a zero and the other is an infinity, NaN is returned. If one of the operands is a non-zero number and the other is an infinity, an infinity with the appropriate sign is returned.

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: see 4.2 Arithmetic operators on numeric values.

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

Error Conditions

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

Notes

For xs:float and xs:double operands, floating point division is performed as specified in [IEEE 754-2008]. A positive number divided by positive zero returns INF. A negative number divided by positive zero returns -INF. Division by negative zero returns -INF and INF, respectively. Positive or negative zero divided by positive or negative zero returns NaN. Also, INF or -INF divided by INF or -INF returns NaN.

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: see 4.2 Arithmetic operators on numeric values.

If $arg2 is INF or -INF, and $arg1 is not INF or -INF, then the result is zero.

Otherwise, subject to limits of precision and overflow/underflow conditions, the result is the largest (furthest from zero) xs:integer value $N such that the following expression is true:

abs($N * $arg2) le abs($arg1) 
               and compare($N * $arg2, 0) eq compare($arg1, 0).

Note:

The second term in this condition ensures that the result has the correct sign.

The implementation may adopt a different algorithm provided that it is equivalent to this formulation in all cases where ·implementation-dependent· or ·implementation-defined· behavior does not affect the outcome, for example, the implementation-defined precision of the result of xs:decimal division.

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 is NaN or if $arg1 is INF 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

Expression	Result
op:numeric-integer-divide(10,3) op:numeric-integer-divide(10,3)	3 3
op:numeric-integer-divide(3,-2) op:numeric-integer-divide(3,-2)	-1 -1
op:numeric-integer-divide(-3,2) op:numeric-integer-divide(-3,2)	-1 -1
op:numeric-integer-divide(-3,-2) op:numeric-integer-divide(-3,-2)	1 1
op:numeric-integer-divide(9.0,3) op:numeric-integer-divide(9.0,3)	3 3
op:numeric-integer-divide(-3.5,3) op:numeric-integer-divide(-3.5,3)	-1 -1
op:numeric-integer-divide(3.0,4) op:numeric-integer-divide(3.0,4)	0 0
op:numeric-integer-divide(3.1E1,6) op:numeric-integer-divide(3.1E1,6)	5 5
op:numeric-integer-divide(3.1E1,7) op:numeric-integer-divide(3.1E1,7)	4 4

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: see 4.2 Arithmetic operators on numeric values.

The operation a mod b for operands that are xs:integer or xs:decimal, or types derived from them, produces a result such that (a idiv b)*b+(a mod b) is equal to a and the magnitude of the result is always less than the magnitude of b. This identity holds even in the special case that the dividend is the negative integer of largest possible magnitude for its type and the divisor is -1 (the remainder is 0). It follows from this rule that the sign of the result is the sign of the dividend.

For xs:float and xs:double operands the following rules apply:

• If either operand is NaN, the result is NaN.

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

• If the dividend is finite and the divisor is an infinity, the result equals the dividend.

• If the dividend is positive or negative zero and the divisor is finite, the result is the same as the dividend.

• In the remaining cases, where neither positive or negative infinity, nor positive or negative zero, nor NaN is involved, the result obeys (a idiv b)*b+(a mod b) = a. Division is truncating division, analogous to integer division, not [IEEE 754-2008] rounding division i.e. additional digits are truncated, not rounded to the required precision.

Error Conditions

A dynamic error is raised [err:FOAR0001] for xs:integer and xs:decimal operands, if $arg2 is zero.

Examples

Expression	Result
op:numeric-mod(10,3) op:numeric-mod(10,3)	1 1
op:numeric-mod(6,-2) op:numeric-mod(6,-2)	0 0
op:numeric-mod(4.5,1.2) op:numeric-mod(4.5,1.2)	0.9 0.9
op:numeric-mod(1.23E2, 0.6E1) op:numeric-mod(1.23E2, 0.6E1)	3.0E0 3.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: see 4.2 Arithmetic operators on numeric values.

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

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 as xs:double(@price) if the type of @price is xs: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: see 4.2 Arithmetic operators on numeric values.

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

For xs:integer and xs:decimal arguments, 0 and 0.0 return 0 and 0.0, respectively. For xs:float and xs:double arguments, NaN returns NaN, 0.0E0 returns -0.0E0 and vice versa. INF returns -INF. -INF returns INF.

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: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.

Notes

For xs:float and xs:double values, positive zero and negative zero compare equal. INF equals INF and -INF equals -INF. If $arg1 or $arg2 is NaN, the function returns false.

4.3.2 op:numeric-less-than

Summary

Returns true 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, gt, and ge.

Signature

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

Rules

General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.

Notes

For xs:float and xs:double values, positive infinity is greater than all other non-NaN values; negative infinity is less than all other non-NaN values. Positive and negative zero compare equal. If $arg1 or $arg2 is NaN, the function returns false.

4.4.1 fn:abs

Summary

Returns the absolute value of $value.

Signature

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

Properties

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

Rules

General rules: see 4.4 Functions on numeric values.

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

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:positiveInteger then the value of $valuemay be returned unchanged.

For xs:float and xs:double arguments, if the argument is positive zero or negative zero, then positive zero is returned. If the argument is positive or negative infinity, positive infinity is returned.

Examples

Expression	Result
abs(10.5) abs(10.5)	10.5 10.5
abs(-10.5) abs(-10.5)	10.5 10.5
abs(-math:log(0)) abs(-math:log(0))	xs:double('INF') xs:double('INF')

4.4.2 fn:ceiling

Summary

Rounds $value upwards to a whole number.

Signature

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

Properties

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

Rules

General rules: see 4.4 Functions on numeric values.

The function returns the smallest (closest to negative infinity) number with no fractional part that is not less than $value.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal then the result may be an instance of xs:integer.

For xs:float and xs:double arguments, if the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned. If the argument is less than zero and greater than -1, negative zero is returned. If the argument is positive or negative infinity, the value of the argument is returned.

Examples

Expression	Result
ceiling(10.5) ceiling(10.5)	11 11
ceiling(-10.5) ceiling(-10.5)	-10 -10
ceiling(math:log(0)) ceiling(math:log(0))	-xs:double('INF') -xs:double('INF')

4.4.3 fn:floor

Summary

Rounds $value downwards to a whole number.

Signature

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

Properties

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

Rules

General rules: see 4.4 Functions on numeric values.

The function returns the largest (closest to positive infinity) number with no fractional part that is not greater than $value.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal then the result may be an instance of xs:integer.

For xs:float and xs:double arguments, if the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned. If the argument is positive or negative infinity, the value of the argument is returned.

Examples

Expression	Result
floor(10.5) floor(10.5)	10 10
floor(-10.5) floor(-10.5)	-11 -11
math:log(0) => floor() math:log(0) => floor()	-xs:double('INF') -xs:double('INF')

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.

Signature

fn:round(
$value	as xs:numeric?,
$precision	as xs:integer?as xs:integeras xs:integer?	:= 0
) as xs:numeric?

Properties

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

Rules

General rules: see 4.4 Functions on numeric values.

The function returns the nearest (that is, numerically closest) value to $value 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 $value is exactly .5), the function returns the one that is closest to positive infinity.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal and $precision is less than one, then the result may be an instance of xs:integer.

If the second argument is omitted or an empty sequence, the function produces the same result as the two-argument version with $precision=0 (that is, it rounds to a whole number).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).If the second argument is omitted or an empty sequence, theThe 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 $value is of type xs:float and xs:double:

1. If $value 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 to xs:decimal using an implementation of xs:decimal that imposes no limits on the number of digits that can be represented. The function is applied to this xs:decimal value, and the resulting xs:decimal is cast back to xs:float or xs:double as appropriate to form the function result. If the resulting xs:decimal value is zero, then positive or negative zero is returned according to the sign of $value.

Notes

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

Examples

Expression	Result
round(2.5) round(2.5)	3.0 3.0
round(2.4999) round(2.4999)	2.0 2.0
round(-2.5) round(-2.5)	-2.0 -2.0 (Not the possible alternative, -3).
round(1.125, 2) round(1.125, 2)	1.13 1.13
round(8452, -2) round(8452, -2)	8500 8500
round(3.1415e0, 2) round(3.1415e0, 2)	3.14e0 3.14e0
math:log(0) => round() math:log(0) => round()	-xs:double('INF') -xs:double('INF')

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.

Signature

fn:round-half-to-even(
$value	as xs:numeric?,
$precision	as xs:integer?as xs:integeras xs:integer?	:= 0
) as xs:numeric?

Properties

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

Rules

General rules: see 4.4 Functions on numeric values.

The function returns the nearest (that is, numerically closest) value to $value 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 $value is exactly .500...), the function returns the one whose least significant digit is even.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal and $precision is less than one, then the result may be an instance of xs:integer.

If the second argument is omitted or an empty sequence, the function produces the same result as the two-argument version with $precision=0. The one-argument form of this function produces the same result as the two-argument form with $precision=0. If the second argument is omitted or an empty sequence, theThe one-argument form of this function produces the same result as the two-argument versionform with $precision=0.

For arguments of type xs:float and xs:double:

1. If the argument is NaN, 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 to xs:decimal using an implementation of xs:decimal that imposes no limits on the number of digits that can be represented. The function is applied to this xs:decimal value, and the resulting xs:decimal is cast back to xs:float or xs:double as appropriate to form the function result. If the resulting xs:decimal value is zero, then positive or negative zero is returned according to the sign of the original argument.

Notes

This function is typically used in financial applications where the argument is of type xs:decimal. For arguments of type xs:float and xs:double the results may be counter-intuitive. For example, consider round-half-to-even(xs:float(150.015), 2). The result is not 150.02 as might be expected, but 150.01. This is because the conversion of the xs:float value represented by the literal 150.015 to an xs:decimal produces the xs:decimal value 150.014999389..., which is closer to 150.01 than to 150.02.

Examples

Expression	Result
round-half-to-even(0.5) round-half-to-even(0.5)	0.0 0.0
round-half-to-even(1.5) round-half-to-even(1.5)	2.0 2.0
round-half-to-even(2.5) round-half-to-even(2.5)	2.0 2.0
round-half-to-even(3.567812e+3, 2) round-half-to-even(3.567812e+3, 2)	3567.81e0 3567.81e0
round-half-to-even(4.7564e-3, 2) round-half-to-even(4.7564e-3, 2)	0.0e0 0.0e0
round-half-to-even(35612.25, -2) round-half-to-even(35612.25, -2)	35600 35600
math:log(0) => round-half-to-even() math:log(0) => round-half-to-even()	-xs:double('INF') -xs:double('INF')

4.4.6 fn:is-NaN

Summary

Returns true if the argument is the xs:float or xs:double value NaN.

Signature

fn:is-NaN(
$value	as xs:anyAtomicType
) as xs:boolean

Properties

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

Rules

The function returns true if the argument is the xs:float or xs:double value NaN; otherwise it returns false.

Examples

Expression	Result
is-NaN(23) is-NaN(23)	false() false()
is-NaN("NaN") is-NaN("NaN")	false() false()
is-NaN(number("twenty-three")) is-NaN(number("twenty-three"))	true() true()
is-NaN(math:sqrt(-1)) is-NaN(math:sqrt(-1))	true() true()

History

New in 4.0. Accepted 2022-09-20.

4.5.1 fn:number

Summary

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

Signature

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

If $value is the empty sequence or if $value cannot be converted to an xs:double, the xs:double value NaN is returned.

Otherwise, $value is converted to an xs:double following the rules of 21.1.2.2 Casting to xs:double. If the conversion to xs:double fails, the xs:double value NaN is returned.

Error Conditions

A dynamic error is raised [err:XPDY0002]^XP if $value is omitted and the context item is absent^DM40.

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.

Generally fn:number returns NaN rather than raising a dynamic error if the argument cannot be converted to xs:double. However, a type error is raised in the usual way if the supplied argument cannot be atomized or if the result of atomization does not match the required argument type.

Examples

Variables
let $e := <e price="12.1" discount="NONE"/>

Expression	Result
number(12) number($item1/quantity)	1.2e1 5.0e0
number('12') number($item2/description)	1.2e1 xs:double('NaN')
number('INF') Assume that the context item is the xs:string value "15". Then fn:number() returns 1.5e1.		xs:double('INF')
number('NaN')	xs:double('NaN')
number('NaN')	xs:double('NaN')
number('non-numeric')	xs:double('NaN')
number('non-numeric')	xs:double('NaN')
number($e/@price)	1.21e1
number($e/@price)	1.21e1
number($e/@discount)	xs:double('NaN')
number($e/@discount)	xs:double('NaN')
number($e/@misspelt)	xs:double('NaN')
number($e/@misspelt)	xs:double('NaN')
("10", "11", "12")!number()	1.0e1, 1.1e1, 1.2e1
("10", "11", "12")!number()	1.0e1, 1.1e1, 1.2e1

4.5.2 fn:parse-integer

Summary

Converts a string to an integer, recognizing any radix in the range 2 to 36.

Signature

fn:parse-integer(
$value	as xs:string,
$radix	as xs:integer?as xs:integeras xs:integer?	:= 10
) as xs:integer

Properties

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

Rules

The supplied $radix must be in the range 2 to 36 inclusive.

The string $value is preprocessed by stripping all whitespace characters (including internal whitespace) and underscore characters.

After this process, the supplied value must consist of an optional sign (+ or -) followed by a sequence of one or more generalized digits drawn from the first $radix characters in the alphabet 0123456789abcdefghijklmnopqrstuvwxyz; upper-case alphabetics A-Z may be used in place of their lower-case equivalents.

The value of a generalized digit corresponds to its position in this alphabet. More formally, in non-error cases the result of the function is given by the XQuery expression:

let $alphabet := characters("0123456789abcdefghijklmnopqrstuvwxyz")
let $preprocessed-value := translate($value, "_ 	

", "")
let $digits := translate($preprocessed-value, "+-", "")
let $abs := sum(
  for $char at $p in reverse(characters($digits))
  return (index-of($alphabet, $char) - 1) * xs:integer(math:pow($radix, $p - 1)))
return if (starts-with($preprocessed-value, "-")) then -$abs else +$abs

Error Conditions

A dynamic error is raised [err:FORG0011] if $radix is not in the range 2 to 36.

A dynamic error is raised [err:FORG0012] if, after stripping whitespace and underscores and the optional leading sign, $value is a zero-length string, or if it contains a character that is not among the first $radix characters in the alphabet 0123456789abcdefghijklmnopqrstuvwxyz, or the upper-case equivalent of such a character.

A dynamic error is raised [err:FOCA0003] if the value of the resulting integer exceeds the implementation-dependent limit on the size of an xs:integer.

Notes

When $radix takes its default value of 10, the function delivers the same result as casting $value (after removal of whitespace and underscores) to xs:integer.

If underscores or whitespace in the input need to be rejected, then the string should first be validated, perhaps using fn:matches.

If other characters may legitimately appear in the input, for example a leading 0x, then this must first be removed by pre-processing the input.

If the input uses a different family of digits, then the value should first be converted to the required digits using fn:translate.

A string in the lexical space of xs:hexBinary will always be an acceptable input, provided it is not too long. So, for example, the expression "1DE=" => xs:base64Binary() => xs:hexBinary() => xs:string() => parse-integer(16) can be used to convert the Base 64 value 1DE= to the integer 54321, via the hexadecimal string D431.

Examples

Expression	Result
Expression:	parse-integer(" 200 ")	200
Result:	200
Result:	200
Expression:	parse-integer("-20")	-20
Result:	-20
Result:	-20
Expression:	parse-integer(" +100")	100
Result:	100
Result:	100
Expression:	parse-integer("ff", 16)	255
Result:	255
Result:	255
Expression:	parse-integer("FFFF FFFF", 16)	4294967295
Result:	4294967295
Result:	4294967295
Expression:	parse-integer("-FFFF_FFFF", 16)	-4294967295
Result:	-4294967295
Result:	-4294967295
Expression:	parse-integer("377", 8)	255
Result:	255
Result:	255
Expression:	parse-integer("101", 2)	5
Result:	5
Result:	5
Expression:	parse-integer("vv", 32)	1023
Result:	1023
Result:	1023
Alphabetic base-26 numbering systems (hexavigesimal) can be parsed via translation. Note, enumerating systems that do not assign a symbol to zero (e.g., spreadsheet columns) must be preprocessed in a different fashion.
Expression:	lower-case("AAB") => translate("abcdefghijklmnopqrstuvwxyz", "0123456789abcdefghijklmnop") => parse-integer(26)	1
Result:	1
Result:	1
Digit-based numeration systems comparable to the Arabic numbers 0 through 9 can be parsed via translation.
Expression:	translate('٢٠٢٣', '٠١٢٣٤٥٦٧٨٩', '0123456789') => parse-integer()	2023
Result:	2023
Result:	2023

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.

Signature

fn:format-integer(
$value	as xs:integer?,
$picture	as xs:string,
$language	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 the following, in order:

1. An optional radix, which is an integer in the range 2 to 36, written using ASCII digits (0-9) without any leading zero;

2. A circumflex (^), which is present if the radix is present, and absent otherwise.

   A circumflex is recognized as marking the presence of a radix only if (a) it is immediately preceded by an integer in the range 2 to 36, and (b) it is followed (somewhere within the primary format token) by an "X" or "x". In other cases, the circumflex is treated as a grouping separator. For example, the picture 9^000 outputs the number 2345 as "2^345", whereas 9^XXX outputs "3185". This rule is to ensure backwards compatibility.A circumflex is recognized as marking the presence of a radix only if (a) it is immediately preceded by an integer in the range 2 to 36, and (b) it is followed (somewhere within the primary format token) by an "X" or "x". In other cases, the circumflex is treated as a grouping separator. For example, the picture 9^000 outputs the number 2345 as "2^345", whereas 9^XXX outputs "4451". This rule is to ensure backwards compatibility.A circumflex is recognized as marking the presence of a radix only if (a) it is immediately preceded by an integer in the range 2 to 36, and (b) it is followed (somewhere within the primary format token) by an "X" or "x". In other cases, the circumflex is treated as a grouping separator. For example, the picture 9^000 outputs the number 2345 as "2^345", whereas 9^XXX outputs "31854451". This rule is to ensure backwards compatibility.

3. A primary format token. This is always present and must not be zero-length.

4. An optional format modifier.

   If the string contains one or more semicolons then the last semicolon is taken as terminating the primary format token, and everything that follows is taken as the format modifier; if the string contains no semicolon then the format modifier is taken to be absent (which is equivalent to supplying a zero-length string).

If a radix is present, then the primary format token must follow the rules for a digit-pattern.

The primary format token is classified as one of the following:

1. A digit-pattern made up of optional-digit-signs, mandatory-digit-signs, and grouping-separator-signs.

   • The optional-digit-sign is the character #.

   • If the radix is absent, then a mandatory-digit-sign is a ·character· in Unicode category Nd. All mandatory-digit-signs within the format token must be from the same digit family, where a digit family is a sequence of ten consecutive characters in Unicode category Nd, having digit values 0 through 9. Within the format token, these digits are interchangeable: a three-digit number may thus be indicated equivalently by 000, 001, or 999.

     If the primary format token contains at least one Unicode digit, then the primary format token is taken as a decimal digit pattern, and in this case it must match the regular expression ^((\p{Nd}|#|[^\p{N}\p{L}])+?)$. If it contains a digit but does not match this pattern, a dynamic error is raised [err:FODF1310].

   • If the radix (call it R) is present (including the case where an explicit radix of 10 is used), then the character used as the mandatory-digit-sign is either "x" or "X". If any mandatory-digit-sign is upper-case "X", then all mandatory-digit-signs must be upper-case "X". The digit family used in the output comprises the first R characters of the alphabet 0123456789abcdefghijklmnopqrstuvwxyz, but using upper-case letters in place of lower-case if an upper-case "X" is used as the mandatory-digit-sign.

     In this case the primary format token must match the regular expression ^(([Xx#]|[^\p{N}\p{L}])+?)$

   • a grouping-separator-sign is a non-alphanumeric character, that is a ·character· whose Unicode category is other than Nd, Nl, No, Lu, Ll, Lt, Lm or Lo.

   Note:

   If a semicolon is to be used as a grouping separator, then the primary format token as a whole must be followed by another semicolon, to ensure that the grouping separator is not mistaken as a separator between the primary format token and the format modifier.

   There must be at least one mandatory-digit-sign. There may be zero or more optional-digit-signs, and (if present) these must precede all mandatory-digit-signs. There may be zero or more grouping-separator-signs. A grouping-separator-signmust not appear at the start or end of the digit-pattern, nor adjacent to another grouping-separator-sign.

   The corresponding output is a number in the specified radix, using this digit family, with at least as many digits as there are mandatory-digit-signs in the format token. Thus:

   • A format token 1 generates the sequence 0 1 2 ... 10 11 12 ...

   • A format token 01 (or equivalently, 00 or 99) generates the sequence 00 01 02 ... 09 10 11 12 ... 99 100 101

   • A format token of ١ (Arabic-Indic digit one) generates the sequence ١ then ٢ then ٣ ...

   • A format token of 16^xx generates the sequence 00 01 02 03 ... 08 09 0a 0b 0c 0d 0e 0f 10 11 ...

   • A format token of 16^X generates the sequence 0 1 2 3 ... 8 9 A B C D E F 10 11 ...

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

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

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

      1. There is at least one grouping separator.

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

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

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

         2. Every positive integer multiple of G that is less than the number of optional-digit-signs and mandatory-digit-signs in the primary format token is the position of a grouping separator.

   4. The grouping 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 integer n where G is the grouping size and C 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, where C is the grouping separator character and P 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. Let S₁ be the result of formatting the supplied number in the appropriate radix: for radix 10 this will be the value obtained by casting it to xs:string.

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

   3. Let S₃ be the result of replacing all decimal digits (0-9) in S₂ with the corresponding digits from the selected digit family. (This has no effect when the selected digit family uses ASCII digits (0-9), which will always be the case if a radix is specified.)

   4. Let S₄ be the result of inserting grouping separators into S₃: for every (position P, character C) pair in the grouping separator template where P is less than the number of digits in S₃, insert character C into S₃ at position P, counting from the right-hand end.

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

   6. The result of the function is then S₅.

2. The format token A, which generates the sequence A B C ... Z AA AB AC....

3. The format token a, which generates the sequence a b c ... z aa ab ac....

4. The format token i, which generates the sequence i ii iii iv v vi vii viii ix x ....

5. The format token I, which generates the sequence I II III IV V VI VII VIII IX X ....

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

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

8. The format token Ww, 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, it must use a format token of 1.

   Note:

   In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers, for example, in ancient Greek the dexia keraia (x0374, ʹ) and sometimes the aristeri keraia (x0375, ͵). These should not be included in the format token.

For all format tokens other than a digit-pattern, there may be ·implementation-defined· lower and upper bounds on the range of numbers that can be formatted using this format token; indeed, for some numbering sequences there may be intrinsic limits. For example, the format token ① (circled digit one, ①) has a range imposed by the Unicode character repertoire — zero to 20 in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering sequences described above any upper bound imposed by the implementation must not be less than 1000 (one thousand) and any lower bound must not be greater than 1. Numbers that fall outside this range must be formatted using the format token 1.

The above expansions of numbering sequences for format tokens such as a and i are indicative but not prescriptive. There are various conventions in use for how alphabetic sequences continue when the alphabet is exhausted, and differing conventions for how roman numerals are written (for example, IV versus IIII as the representation of the number 4). Sometimes alphabetic sequences are used that omit letters such as i and o. This specification does not prescribe the detail of any sequence other than those sequences consisting entirely of decimal digits.

Many numbering sequences are language-sensitive. This applies especially to the sequence selected by the tokens w, W and Ww. It also applies to other sequences, for example different languages using the Cyrillic alphabet use different sequences of characters, each starting with the letter #x410 (Cyrillic capital letter A). In such cases, the $language argument specifies which language conventions are to be used. If the argument is specified, the value should be either an empty sequence or a value that would be valid for the xml:lang attribute (see [Extensible Markup Language (XML) 1.0 (Fifth Edition)]). Note that this permits the identification of sublanguages based on country codes (from ISO 3166-1) as well as identification of dialects and regions within a country.

The set of languages for which numbering is supported is ·implementation-defined·. If the $language argument is absent, or is set to an empty sequence, or is invalid, or is not a language supported by the implementation, then the number is formatted using the default language from the dynamic context.

The format modifier must be a string that matches the regular expression ^([co](\(.+\))?)?[at]?$. That is, if it is present it must consist of one or more of the following, in order:

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

• either a or t, to indicate alphabetic or traditional numbering respectively, the default being ·implementation-defined·.

If the o modifier is present, this indicates a request to output ordinal numbers rather than cardinal numbers. For example, in English, when used with the format token 1, this outputs the sequence 1st 2nd 3rd 4th ..., and when used with the format token w outputs the sequence first second third fourth ....

The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences. The interpretation of this string is ·implementation-defined·. No error occurs if the implementation does not define any interpretation for the defined string.

It is ·implementation-defined· what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead.

The use of the a or t modifier disambiguates between numbering sequences that use letters. In many languages there are two commonly used numbering sequences that use letters. One numbering sequence assigns numeric values to letters in alphabetic sequence, and the other assigns numeric values to each letter in some other manner traditional in that language. In English, these would correspond to the numbering sequences specified by the format tokens a and i. In some languages, the first member of each sequence is the same, and so the format token alone would be ambiguous. In the absence of the a or t modifier, the default is ·implementation-defined·.

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 emphasized must or required keyword in the above rules). For example, the error is raised if the primary format token contains a digit but does not match the required regular expression.

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 a digit-pattern is used:

   1. If grouping-separator-signs appear at regular intervals within the format token, then the sequence is extrapolated to the left, so grouping separators will be used in the formatted number at every multiple of N. For example, if the format token is 0'000 then the number one million will be formatted as 1'000'000, while the number fifteen will be formatted as 0'015.

   2. The only purpose of optional-digit-signs is to mark the position of grouping-separator-signs. For example, if the format token is #'##0 then the number one million will be formatted as 1'000'000, while the number fifteen will be formatted as 15. A grouping separator is included in the formatted number only if there is a digit to its left, which will only be the case if either (a) the number is large enough to require that digit, or (b) the number of mandatory-digit-signs in the format token requires insignificant leading zeros to be present.

   3. Grouping separators are not 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 the digit-pattern01, the number three hundred will be output as 300, despite the absence of any optional-digit-sign.

3. The following notes apply when ordinal numbering is selected using the o modifier.

   In some languages, the form of numbers (especially ordinal numbers) varies depending on the grammatical context: they may have different genders and may decline with the noun that they qualify. In such cases the string appearing in parentheses after the letter c or o may be used to indicate the variation of the cardinal or ordinal number required.

   The way in which the variation is indicated will depend on the conventions of the language.

   For inflected languages that vary the ending of the word, the approach recommended in the previous version of this specification was to indicate the required ending, preceded by a hyphen: for example in German, appropriate values might be o(-e), o(-er), o(-es), o(-en).

   Another approach, which might usefully be adopted by an implementation based on the open-source ICU localization library [ICU], or any other library making use of the Unicode Common Locale Data Repository [Unicode CLDR], is to allow the value in parentheses to be the name of a registered numbering rule set for the language in question, conventionally prefixed with a percent sign: for example, o(%spellout-ordinal-masculine), or c(%spellout-cardinal-year).

4. The following notes apply when the primary format token is neither a digit-pattern nor one of the seven other defined format tokens (A, a, i, I, w, W, Ww), but is an arbitrary token representing the number 1:

   Unexpected results may occur for traditional numbering. For example, in an implementation that supports traditional numbering system in Greek, the example format-integer(19, "α;t") might return δπιιιι or ιθ, depending upon whether the ancient acrophonic or late antique alphabetic system is supported.

   Unexpected results may also occur for alphabetic numbering. For example, in an implementation that supports alphabetic numbering system in Greek, someone writing format-integer(19, "α;a") might expect the nineteenth Greek letter, #x3C4 τ, but the implementation might return the eighteenth one, #x3C3 σ, because the latter is the nineteenth item in the sequence of lowercase Greek letters in Unicode (the sequence is interrupted because of the final form of the sigma, #x3C2 ς). Because Greek never had a final capital sigma, Unicode has marked #x3A2, the eighteenth codepoint in the sequence of Greek capital letters, as reserved, to ensure that every Greek uppercase letter is always 32 codepoints less than its lowercase counterpart. Therefore, someone writing format-integer(18, "Α;a") might expect the eighteenth Greek capital letter, #x3A3 Σ, but an implementation might return #x3a2, the eighteenth position in the sequence of Greek capital letters, but unassigned to any character.

Examples

Expression	Result
Expression:	format-integer(123, '0000')	"0123"
Result:	"0123"
Result:	"0123"
format-integer(123, 'w') might return "one hundred and twenty-three"
Ordinal numbering in Italian: The specification "1;o(-º)" with $language equal to it, if supported, should produce the sequence:
1º 2º 3º 4º ...
The specification "Ww;o" with $language equal to it, if supported, should produce the sequence:
Primo Secondo Terzo Quarto Quinto ...
Expression:	format-integer(21, '1;o', 'en')	"21st"
Result:	"21st"
Result:	"21st"
format-integer(14, 'Ww;o(-e)', 'de') might return "Vierzehnte"
Expression:	format-integer(7, 'a')	"g"
Result:	"g"
Result:	"g"
Expression:	format-integer(27, 'a')	"aa"
Result:	"aa"
Result:	"aa"
Expression:	format-integer(57, 'I')	"LVII"
Result:	"LVII"
Result:	"LVII"
Expression:	format-integer(1234, '#;##0;')	"1;234"
Result:	"1;234"
Result:	"1;234"
Expression:	format-integer(1234, '16^xxxx')	"04d2"
Result:	"04d2"
Result:	"04d2"
Expression:	format-integer(1234, '16^X')	"4D2"
Result:	"4D2"
Result:	"4D2"
Expression:	format-integer(12345678, '16^xxxx_xxxx')	"00bc_614e"
Result:	"00bc_614e"
Result:	"00bc_614e"
Expression:	format-integer(12345678, '16^#_xxxx')	"bc_614e"
Result:	"bc_614e"
Result:	"bc_614e"
Expression:	format-integer(255, '2^xxxx xxxx')	"1111 1111"
Result:	"1111 1111"
Result:	"1111 1111"
Expression:	format-integer(1023, '32^XXXX')	"00VV"
Result:	"00VV"
Result:	"00VV"
Expression:	format-integer(1023, '10^XXXX')	"1023"
Result:	"1023"
Result:	"1023"
Expression:	format-integer(1023, '10^00')	"10^23"
Result:	"10^23"
Result:	"10^23"

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] The decimal digit family of a decimal format is the sequence of ten digits with consecutive Unicode ·codepoints· starting with the character that is the value of the zero-digit^XP31 property.

[Definition] The optional digit character is the character that is the value of the digit^XP31 property.

For any named or unnamed decimal format, the properties representing characters used in a ·picture string· must have distinct values. These properties are decimal-separator^XP31 , grouping-separator^XP31, exponent-separator^XP31, percent^XP31, per-mille^XP31, digit^XP31, and pattern-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.

Signature

fn:format-number(
$value	as xs:numeric?,
$picture	as xs:string,
$decimal-format-name	as union(xs:string, xs:QName)?	:= ()
) 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 in 4.7.3 Syntax of the picture string.

The $value argument may be of any numeric data type (xs:double, xs:float, xs:decimal, or their subtypes including xs:integer). Note that if an xs:decimal is supplied, it is not automatically promoted to an xs:double, as such promotion can involve a loss of precision.

If the supplied value of the $value argument is an empty sequence, the function behaves as if the supplied value were the xs:double value NaN.

The value of $decimal-format-name, if present and non-empty, must be either an xs:QName, or a string which after removal of leading and trailing whitespace is in the form of an EQName as defined in the XPath 4.0 grammar, that is one of the following:

• A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).

• A URIQualifiedName using the syntax Q{uri}local, where the URI can be zero-length to indicate a name in no namespace.

The decimal format that is used is the decimal format in the static context whose name matches $decimal-format-name if supplied, or the unnamed decimal format in the static context otherwise.

The evaluation of the fn:format-number function takes place in two phases, an analysis phase described in 4.7.4 Analyzing the picture string and a formatting phase described in 4.7.5 Formatting the number.

The analysis phase takes as its inputs the ·picture string· and the variables derived from the relevant decimal format in the static context, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.

The result of the function is the formatted string representation of the supplied number.

Error Conditions

A dynamic error is raised [err:FODF1280] if the $decimal-format-name argument is supplied as an xs:string that is neither a valid lexical QName nor a valid URIQualifiedName, or if it uses a prefix that is not found in the statically known namespaces, or if the static context does not contain a declaration of a decimal-format with a matching expanded QName. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

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.

The type of the third argument changes in version 4.0 from xs:string to union(xs:string, xs:QName). This introduces a minor incompatibility: for example, it is no longer possible to supply a value of type xs:anyURI.

Examples

Expression	Result
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 %.
format-number(12345.6, '#,###.00') format-number(12345.6, '#,###.00')	"12,345.60" "12,345.60"
format-number(12345678.9, '9,999.99') format-number(12345678.9, '9,999.99')	"12,345,678.90" "12,345,678.90"
format-number(123.9, '9999') format-number(123.9, '9999')	"0124" "0124"
format-number(0.14, '01%') format-number(0.14, '01%')	"14%" "14%"
format-number(-6, '000') format-number(-6, '000')	"-006" "-006"
The following example assumes the existence of a decimal format named ch in which the grouping separator is ʹ and the decimal separator is ·:
format-number( 1234.5678, '#ʹ##0·00', 'ch' )	"1ʹ234·57" "1ʹ234·57"
The following examples assume that the exponent separator in decimal format fortran is E:The following examples assume that the exponent separator is in decimal format fortran is E:The following examples assume that the exponent separator is in decimal format fortran is E:
format-number(1234.5678, '00.000E0', 'fortran') format-number(1234.5678, '00.000E0', 'fortran')	"12.346E2" "12.346E2"
format-number(0.234, '0.0E0', 'fortran') format-number(0.234, '0.0E0', 'fortran')	"2.3E-1" "2.3E-1"
format-number(0.234, '#.00E0', 'fortran') format-number(0.234, '#.00E0', 'fortran')	"0.23E0" "0.23E0"
format-number(0.234, '.00E0', 'fortran') format-number(0.234, '.00E0', 'fortran')	".23E0" ".23E0"

History

Changed in 4.0: The decimal format name can now be supplied as a value of type xs:QName, as an alternative to supplying a lexical QName as an instance of xs:string.The decimal format name can now be supplied as a value of type xs:QName, as an alternative to supplying a lexical QName as an instance of xs:string.Changed in 4.0: The decimal format name can now be supplied as a value of type xs:QName, as an alternative to supplying a lexical QName as an instance of xs:string.

4.7.3 Syntax of the picture string

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

• A sub-picture must not contain more than one instance of the decimal-separator^XP31 character.

• A sub-picture must not contain more than one instance of the percent^XP31 or per-mille^XP31 characters, and it must not contain one of each.

• The mantissa part of a sub-picture (defined below) must contain at least one character that is either an ·optional digit character· or a member of the ·decimal digit family·.

• A sub-picture must not contain a passive character that is preceded by an active character and that is followed by another active character.

• A sub-picture must not contain a grouping-separator^XP31 character that appears adjacent to a decimal-separator^XP31 character, or in the absence of a decimal-separator^XP31 character, at the end of the integer part.

• A sub-picture must not contain two adjacent instances of the grouping-separator^XP31 character.

• The integer part of a sub-picture (defined below) must not contain a member of the ·decimal digit family· that is followed by an instance of the ·optional digit character·. The fractional part of a sub-picture (defined below) must not contain an instance of the ·optional digit character· that is followed by a member of the ·decimal digit family·.

• A character that matches the exponent-separator^XP31 property is treated as an exponent-separator-sign if it is both preceded and followed within the sub-picture by an active character. Otherwise, it is treated as a passive character. A sub-picture must not contain more than one character that is treated as an exponent-separator-sign.

• A sub-picture that contains a percent^XP31 or per-mille^XP31 character must not contain a character treated as an exponent-separator-sign.

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

The mantissa part of the sub-picture is defined as the part that appears to the left of the exponent-separator-sign if there is one, or the entire sub-picture otherwise. The exponent part of the subpicture is defined as the part that appears to the right of the exponent-separator-sign; if there is no exponent-separator-sign then the exponent part is absent.

The integer part of the sub-picture is defined as the part that appears to the left of the decimal-separator^XP31 character if there is one, or the entire mantissa part otherwise.

The fractional part of the sub-picture is defined as that part of the mantissa part that appears to the right of the decimal-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 positive and 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:

• The integer-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the integer part of the sub-picture. For each grouping-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 the grouping-separator^XP31 character.

  The grouping is defined to be regular 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 integer G (the grouping size) such that the position of every grouping-separator in the integer part of the sub-picture is a positive integer multiple of G.

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

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

• The minimum-integer-part-size is an integer indicating the minimum number of digits that will appear to the left of the decimal-separator character. It is initially 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.

• The scaling 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.

• The prefix 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, the prefix for the negative sub-picture is set by concatenating the minus-sign^XP31 character and the prefix for the positive sub-picture (if any), in that order.

• The fractional-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the fractional part of the sub-picture. For each grouping-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 the grouping-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.

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

• The maximum-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 that minimum-integer-part-size and maximum-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 value 0.123 is formatted as 0.1e0

  • Otherwise:

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

    Note:

    This has the effect that with the picture #, the value 0.23 is formatted as 0

• If all the following conditions are true:

  • An exponent separator is present

  • The minimum-integer-part-size is zero

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

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

  Note:

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

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

• The minimum-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 the minimum-exponent-size will always be greater than zero.

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