XML Path Language (XPath) 4.0 WG Review Draft

2.1.3 Values

[Definition: In the data model, a value is always a sequence.]

[Definition: A sequence is an ordered collection of zero or more items.]

[Definition: An item is either an atomic item, a node, or a function item.]

[Definition: An atomic item is a value in the value space of an atomic type, as defined in [XML Schema 1.0] or [XML Schema 1.1].]

[Definition: An XNode is an instance of one of the node kinds defined in Section 7.1 XML Nodes^DM.] Each XNode has a unique node identity, a typed value, and a string value. In addition, some XNodes have a name. The typed value of an XNode is a sequence of zero or more atomic items. The string value of an XNode is a value of type xs:string. The name of an XNode is a value of type xs:QName. [Definition: An XNode is an instance of one of the node kinds defined in [XDM 4.0] section 7.1 XML Nodes.] Each XNode has a unique node identity, a typed value, and a string value. In addition, some XNodes have a name. The typed value of an XNode is a sequence of zero or more atomic items. The string value of an XNode is a value of type xs:string. The name of an XNode is a value of type xs:QName. [Definition: An XNode is an instance of one of the node kinds defined in [XDM 4.0] section Section 7.1 XML NodesDM.] Each XNode has a unique node identity, a typed value, and a string value. In addition, some XNodes have a name. The typed value of an XNode is a sequence of zero or more atomic items. The string value of an XNode is a value of type xs:string. The name of an XNode is a value of type xs:QName.

[Definition: Except where the context indicates otherwise, the term node is used as a synonym for XNode.]

[Definition: A function item is an item that can be called using a dynamic function call.]

Maps (see 4.13.1 Maps) and arrays (see 4.13.2 Arrays) are specific kinds of function items.

[Definition: A sequence containing exactly one item is called a singleton.] An item is identical to a singleton sequence containing that item. Sequences are never nested—for example, combining the values 1, (2, 3), and ( ) into a single sequence results in the sequence (1, 2, 3). [Definition: A sequence containing zero items is called an empty sequence.]

[Definition: The term XDM instance is used, synonymously with the term value, to denote an unconstrained sequence of items.]

2.1.4 Namespaces and QNames

[Definition: A namespace binding is a pair comprising a namespace prefix (which is either an xs:NCName or empty), and a namespace URI.]

Element nodes have a property called in-scope namespaces. [Definition: The in-scope namespaces property of an element node is a set of namespace bindings, each of which associates a namespace prefix with a URI.] For a given element, one namespace binding may have an empty prefix; the URI of this namespace binding is referred to as the default in-scope namespace for the element.

In [XML Path Language (XPath) Version 1.0], the in-scope namespaces of an element node are represented by a collection of namespace nodes arranged on a namespace axis. As of XPath 2.0, the namespace axis is deprecated and need not be supported by a host language. A host language that does not support the namespace axis need not represent namespace bindings in the form of nodes.In [XPath 1.0], the in-scope namespaces of an element node are represented by a collection of namespace nodes arranged on a namespace axis. As of XPath 2.0, the namespace axis is deprecated and need not be supported by a host language. A host language that does not support the namespace axis need not represent namespace bindings in the form of nodes.In [XML Path Language (XPath) Version 1.0][XPath 1.0], the in-scope namespaces of an element node are represented by a collection of namespace nodes arranged on a namespace axis. As of XPath 2.0, the namespace axis is deprecated and need not be supported by a host language. A host language that does not support the namespace axis need not represent namespace bindings in the form of nodes.

[Definition: The default in-scope namespace of an element node] is the namespace URI to which the empty prefix is bound in the element’s in-scope namespaces. In the absence of an explicit binding for the empty prefix, the default in-scope namespace is absent^DM.

[Definition: An expanded QName is a triple: its components are a prefix, a local name, and a namespace URI. In the case of a name in no namespace, the namespace URI and prefix are both absent. In the case of a name in the default namespace, the prefix is absent.] When comparing two expanded QNames, the prefixes are ignored: the local name parts must be equal under the Unicode codepoint collation (Section 5.3.1 Collations^FO), and the namespace URI parts must either both be absent, or must be equal under the Unicode codepoint collation. [Definition: An expanded QName is a triple: its components are a prefix, a local name, and a namespace URI. In the case of a name in no namespace, the namespace URI and prefix are both absent. In the case of a name in the default namespace, the prefix is absent.] When comparing two expanded QNames, the prefixes are ignored: the local name parts must be equal under the Unicode codepoint collation ([Functions and Operators 4.0] section 5.3.1 Collations), and the namespace URI parts must either both be absent, or must be equal under the Unicode codepoint collation. [Definition: An expanded QName is a triple: its components are a prefix, a local name, and a namespace URI. In the case of a name in no namespace, the namespace URI and prefix are both absent. In the case of a name in the default namespace, the prefix is absent.] When comparing two expanded QNames, the prefixes are ignored: the local name parts must be equal under the Unicode codepoint collation ([Functions and Operators 4.0] section Section 5.3.1 CollationsFO), and the namespace URI parts must either both be absent, or must be equal under the Unicode codepoint collation.

In the XPath 4.0 grammar, QNames representing the names of elements, attributes, functions, variables, types, or other such constructs are written as instances of the grammatical production EQName.

The EQName production allows a QName to be written in one of three ways:

• local-name only (for example, invoice).

  A name written in this form has no prefix, and the rules for determining the namespace depend on the context in which the name appears: the various rules used are summarized in 2.1.5 Expanding Lexical QNames. This form is a lexical QName.

• prefix plus local-name (for example, my:invoice).

  In this case the prefix and local name of the QName are as written, and the namespace URI is inferred from the prefix by examining the statically known namespaces in the static context where the QName appears; the context must include a binding for the prefix. This form is a lexical QName.

• URI plus local-name (for example, Q{http://example.com/ns}invoice).

  In this case the local name and namespace URI are as written, and the prefix is absent. This way of writing a QName is context-free, which makes it particularly suitable for use in expressions that are generated by software. This form is a URIQualifiedName. If the BracedURILiteral has no content (for example, Q{}invoice) then the namespace URI of the QName is absent.

[Definition: A lexical QName is a name that conforms to the syntax of the QName production].

The namespace URI value in a URIQualifiedName is whitespace normalized according to the rules for the xs:anyURI type in Section 3.2.17 anyURI ^XS1-2 or Section 3.3.17 anyURI ^XS11-2. It is a static error [err:XQST0070] if the namespace URI for an EQName is http://www.w3.org/2000/xmlns/. The namespace URI value in a URIQualifiedName is whitespace normalized according to the rules for the xs:anyURI type in 3.2.17 anyURI ^XS1-2 or 3.3.17 anyURI ^XS11-2. It is a static error [err:XQST0070] if the namespace URI for an EQName is http://www.w3.org/2000/xmlns/. The namespace URI value in a URIQualifiedName is whitespace normalized according to the rules for the xs:anyURI type in Section 3.2.17 anyURI ^XS1-2 or Section 3.3.17 anyURI ^XS11-2. It is a static error [err:XQST0070] if the namespace URI for an EQName is http://www.w3.org/2000/xmlns/.

Here are some examples of EQNames:

• pi is a lexical QName without a namespace prefix.

• math:pi is a lexical QName with a namespace prefix.

• Q{http://www.w3.org/2005/xpath-functions/math}pi specifies the namespace URI using a BracedURILiteral; it is not a lexical QName.

This document uses the following namespace prefixes to represent the namespace URIs with which they are listed. Although these prefixes are used within this specification to refer to the corresponding namespaces, not all of these bindings will necessarily be present in the static context of every expression, and authors are free to use different prefixes for these namespaces, or to bind these prefixes to different namespaces.

• xs: http://www.w3.org/2001/XMLSchema

• fn: http://www.w3.org/2005/xpath-functions

• array: http://www.w3.org/2005/xpath-functions/array

• map: http://www.w3.org/2005/xpath-functions/map

• math: http://www.w3.org/2005/xpath-functions/math

• err: http://www.w3.org/2005/xqt-errors (see 2.4.2 Identifying and Reporting Errors).

• output: http://www.w3.org/2010/xslt-xquery-serialization

[Definition: Within this specification, the term URI refers to a Universal Resource Identifier as defined in [RFC3986] and extended in [RFC3987] with the new name IRI.] The term URI has been retained in preference to IRI to avoid introducing new names for concepts such as “Base URI” that are defined or referenced across the whole family of XML specifications.

2.2.1 Static Context

[Definition: The static context of an expression is the information that is available during static analysis of the expression, prior to its evaluation.] This information can be used to decide whether the expression contains a static error.

The individual components of the static context are described below.

In XPath 4.0, the static context for an expression is largely defined by the host language, that is, by the calling environment that causes an XPath expression to be evaluated. Most of the static context components are constant throughout an expression; the only exception is in-scope variables. (There are constructs in the language, such as the ForExpr and LetExpr, that add additional variables to the static context of their subexpressions.)

Some components of the static context, but not all, also affect the dynamic semantics of expressions. For example, casting of a string such as "xbrl:xbrl" to an xs:QName might expand the prefix xbrl to the namespace URI http://www.xbrl.org/2003/instance using the statically known namespaces from the static context; since the input string "xbrl:xbrl" is in general not known until execution time (it might be read from a source document), this means that the values of the statically known namespaces must be available at execution time.

• [Definition: XPath 1.0 compatibility mode.This value is true if rules for backward compatibility with XPath Version 1.0 are in effect; otherwise it is false. ]

• [Definition: Statically known namespaces. This is a mapping from prefix to namespace URI that defines all the namespaces that are known during static processing of a given expression.]

  The URI value is whitespace normalized according to the rules for the xs:anyURI type in Section 3.2.17 anyURI ^XS1-2 or Section 3.3.17 anyURI ^XS11-2.The URI value is whitespace normalized according to the rules for the xs:anyURI type in 3.2.17 anyURI ^XS1-2 or 3.3.17 anyURI ^XS11-2.The URI value is whitespace normalized according to the rules for the xs:anyURI type in Section 3.2.17 anyURI ^XS1-2 or Section 3.3.17 anyURI ^XS11-2.

  Note the difference between in-scope namespaces, which is a dynamic property of an element node, and statically known namespaces, which is a static property of an expression.

• [Definition: Default namespace for elements and types. This is either a namespace URI, or the special value "##any", or absent^DM. This indicates how unprefixed QNames are interpreted when they appear in a position where an element name or type name is expected.]

  • If the value is set to a namespace URI, this namespace is used for any such unprefixed QName. The URI value is whitespace-normalized according to the rules for the xs:anyURI type in Section 3.2.17 anyURI ^XS1-2 or Section 3.3.17 anyURI ^XS11-2.If the value is set to a namespace URI, this namespace is used for any such unprefixed QName. The URI value is whitespace-normalized according to the rules for the xs:anyURI type in 3.2.17 anyURI ^XS1-2 or 3.3.17 anyURI ^XS11-2.If the value is set to a namespace URI, this namespace is used for any such unprefixed QName. The URI value is whitespace-normalized according to the rules for the xs:anyURI type in Section 3.2.17 anyURI ^XS1-2 or Section 3.3.17 anyURI ^XS11-2.

  • The special value "##any" indicates that:

    • When an unprefixed QName is used as a name test for selecting named elements in an axis step, the name test will match an element having the specified local name, in any namespace or none.

    • When an unprefixed QName is used in a context where a type name is expected (but not as a function name), the default namespace is the xs namespace, http://www.w3.org/2001/XMLSchema.

    • In any other context, an unprefixed QName represents a name in no namespace.

  • If the value is absent^DM, an unprefixed QName representing an element or type name is interpreted as being in no namespace.

• [Definition: Default function namespace. This is either a namespace URI, or absent^DM. The namespace URI, if present, is used for any unprefixed QName appearing in a position where a function name is expected.] The URI value is whitespace-normalized according to the rules for the xs:anyURI type in Section 3.2.17 anyURI ^XS1-2 or Section 3.3.17 anyURI ^XS11-2 [Definition: Default function namespace. This is either a namespace URI, or absent^DM. The namespace URI, if present, is used for any unprefixed QName appearing in a position where a function name is expected.] The URI value is whitespace-normalized according to the rules for the xs:anyURI type in 3.2.17 anyURI ^XS1-2 or 3.3.17 anyURI ^XS11-2 [Definition: Default function namespace. This is either a namespace URI, or absent^DM. The namespace URI, if present, is used for any unprefixed QName appearing in a position where a function name is expected.] The URI value is whitespace-normalized according to the rules for the xs:anyURI type in Section 3.2.17 anyURI ^XS1-2 or Section 3.3.17 anyURI ^XS11-2

  In its simplest form its value is simply a whitespace-normalized xs:anyURI value (most commonly, the URI http://www.w3.org/2005/xpath-functions) to be used as the default namespace for unprefixed function names. However, the use of a more complex algorithm is not precluded, for example an algorithm which searches multiple namespaces for a matching name.

• [Definition: In-scope schema definitions is a generic term for all the element declarations, attribute declarations, and schema type definitions that are in scope during static analysis of an expression.] It includes the following three parts:

  • [Definition: In-scope schema types. Each schema type definition is identified either by an expanded QName (for a named type) or by an implementation-dependent type identifier (for an anonymous type). The in-scope schema types include the predefined schema types described in 3.5 Schema Types. ]

  • [Definition: In-scope element declarations. Each element declaration is identified either by an expanded QName (for a top-level element declaration) or by an implementation-dependent element identifier (for a local element declaration). ] An element declaration includes information about the element’s substitution group affiliation.

    [Definition: Substitution groups are defined in Section 2.2.2.2 Element Substitution Group ^XS1-1 and Section 2.2.2.2 Element Substitution Group ^XS11-1. Informally, the substitution group headed by a given element (called the head element) consists of the set of elements that can be substituted for the head element without affecting the outcome of schema validation.] [Definition: Substitution groups are defined in 2.2.2.2 Element Substitution Group ^XS1-1 and 2.2.2.2 Element Substitution Group ^XS11-1. Informally, the substitution group headed by a given element (called the head element) consists of the set of elements that can be substituted for the head element without affecting the outcome of schema validation.] [Definition: Substitution groups are defined in Section 2.2.2.2 Element Substitution Group ^XS1-1 and Section 2.2.2.2 Element Substitution Group ^XS11-1. Informally, the substitution group headed by a given element (called the head element) consists of the set of elements that can be substituted for the head element without affecting the outcome of schema validation.]

  • [Definition: In-scope attribute declarations. Each attribute declaration is identified either by an expanded QName (for a top-level attribute declaration) or by an implementation-dependent attribute identifier (for a local attribute declaration). ]

• [Definition: In-scope variables. This is a mapping from expanded QNames to sequence types. It defines the set of variables that are available for reference within an expression. The expanded QName is the name of the variable, and the type is the static type of the variable.]

  An expression that binds a variable extends the in-scope variables, within the scope of the variable, with the variable and its type. Within the body of an inline function expression, the in-scope variables are extended by the names and types of the function parameters.

• [Definition: In-scope named item types. This is a mapping from expanded QNames to named item types.]

  [Definition: A named item type is an ItemType identified by an expanded QName.]

  Named item types serve two purposes:

  • They allow frequently used item types, especially complex item types such as record types, to be given simple names, to avoid repeating the definition every time it is used.

  • They allow the definition of recursive types, which are useful for describing recursive data structures such as lists and trees. For details see 3.2.8.3.1 Recursive Record Types.

  Certain named item types (typically item types used in the signatures of built-in functions) are always available in the static context. These are defined in Section C Built-in named record types^FO.Certain named item types (typically item types used in the signatures of built-in functions) are always available in the static context. These are defined in [Functions and Operators 4.0] section C Built-in named record types.Certain named item types (typically item types used in the signatures of built-in functions) are always available in the static context. These are defined in [Functions and Operators 4.0] section Section C Built-in named record typesFO.

  Note:

  Named item types can be defined in a host language such as XQuery 4.0 and in XSLT 4.0, but not in XPath 4.0 itself. They are available in XPath only if the host language provides the ability to define them.

• [Definition: Statically known function definitions. This is a set of function definitions.]

  Function definitions are described in 2.2.1.1 Function Definitions.

• [Definition: Statically known collations. This is an implementation-defined mapping from URI to collation. It defines the names of the collations that are available for use in processing expressions.] [Definition: A collation is a specification of the manner in which strings and URIs are compared and, by extension, ordered. For a more complete definition of collation, see Section 5.3 Comparison of strings^FO.] [Definition: Statically known collations. This is an implementation-defined mapping from URI to collation. It defines the names of the collations that are available for use in processing expressions.] [Definition: A collation is a specification of the manner in which strings and URIs are compared and, by extension, ordered. For a more complete definition of collation, see [Functions and Operators 4.0] section 5.3 Comparison of strings.] [Definition: Statically known collations. This is an implementation-defined mapping from URI to collation. It defines the names of the collations that are available for use in processing expressions.] [Definition: A collation is a specification of the manner in which strings and URIs are compared and, by extension, ordered. For a more complete definition of collation, see [Functions and Operators 4.0] section Section 5.3 Comparison of stringsFO.]

• [Definition: Static Base URI. This is an absolute URI, used to resolve relative URIs during static analysis. ] For example, it is used to resolve module location URIs in XQuery, and the URIs in xsl:import and xsl:include in XSLT. If E is a subexpression of F then the Static Base URI of E is the same as the Static Base URI of F. There are no constructs in XPath that require resolution of relative URI references during static analysis.

  Relative URI references are resolved as described in 2.5.6 Resolving a Relative URI Reference.

  At execution time, relative URIs supplied to functions such as fn:doc are resolved against the Executable Base URI, which may or may not be the same as the Static Base URI.

• [Definition: Statically known decimal formats. This is a mapping from QNames to decimal formats, with one default format that has no visible name, referred to as the unnamed decimal format. Each format is available for use when formatting numbers using the fn:format-number function.]

  Decimal formats are described in 2.2.1.2 Decimal Formats.

2.2.2 Dynamic Context

[Definition: The dynamic context of an expression is defined as information that is needed for the dynamic evaluation of an expression, beyond any information that is needed from the static context.] If evaluation of an expression relies on some part of the dynamic context that is absent^DM, a type error is raised [err:XPDY0002].

The individual components of the dynamic context are described below.

In general, the dynamic context for the outermost expression is supplied externally, often by some kind of application programming interface (API) allowing XPath 4.0 expressions to be invoked from a host language. Application Programming Interfaces are outside the scope of this specification. The dynamic context for inner subexpressions may be set by their containing expressions: for example in a mapping expression E1!E2, the value of the focus (part of the dynamic context) for evaluation of E₂ is defined by the evaluation of E₁.

Some aspects of the dynamic context are outside the direct control of the query author; they are defined by the implementation, which may or may not allow them to be configured by users. An example is available documents, which is an abstraction for the set of XML documents that can be retrieved by URI from within an expression. In some environments this may be the entire contents of the web; in others it may be constrained to documents that satisfy particular security constraints; and in some environments the set of available documents might even be empty. These components of the dynamic context are generally treated as being constant for the duration of the execution.

Further rules governing the semantics of these components can be found in B.2 Dynamic Context Components.

The components of the dynamic context are listed below.

[Definition: The first three components of the dynamic context (context value, context position, and context size) are called the focus of the expression. ] The focus enables the processor to keep track of which items are being processed by the expression. If any component in the focus is defined, both the context value and context position are known.

[Definition: A fixed focus is a focus for an expression that is evaluated once, rather than being applied to a series of values; in a fixed focus, the context value is set to one specific value, the context position is 1, and the context size is 1.]

[Definition: A singleton focus is a fixed focus in which the context value is a singleton item.]. With a singleton focus, the context value is a single item, the context position is 1, and the context size is 1.

Certain language constructs, notably the path operatorE1/E2, the simple map operatorE1!E2, and the predicateE1[E2], create a new focus for the evaluation of a sub-expression. In these constructs, E₂ is evaluated once for each item in the sequence that results from evaluating E₁. Each time E₂ is evaluated, it is evaluated with a different focus. The focus for evaluating E₂ is referred to below as the inner focus, while the focus for evaluating E₁ is referred to as the outer focus. The inner focus is used only for the evaluation of E₂. Evaluation of E₁ continues with its original focus unchanged.

• [Definition: The context value is the value currently being processed.] In many cases (but not always), the context value will be a single item. [Definition: When the context value is a single item, it can also be referred to as the context item; when it is a single node, it can also be referred to as the context node.] The context value is returned by an expression consisting of a single dot (.). When an expression E1/E2 or E1[E2] is evaluated, each item in the sequence obtained by evaluating E1 becomes the context value in the inner focus for an evaluation of E₂.

• [Definition: The context position is the position of the context value within the series of values currently being processed.] It changes whenever the context value changes. When the focus is defined, the value of the context position is an integer greater than zero. The context position is returned by the expression fn:position(). When an expression E1/E2 or E1[E2] is evaluated, the context position in the inner focus for an evaluation of E2 is the position of the context value in the sequence obtained by evaluating E₁. The position of the first item in a sequence is always 1 (one). The context position is always less than or equal to the context size.

• [Definition: The context size is the number of values in the series of values currently being processed.] Its value is always an integer greater than zero. The context size is returned by the expression fn:last(). When an expression E1/E2 or E1[E2] is evaluated, the context size in the inner focus for an evaluation of E₂ is the number of items in the sequence obtained by evaluating E₁.

• [Definition: Variable values. This is a mapping from expanded QNames to values. It contains the same expanded QNames as the in-scope variables in the static context for the expression. The expanded QName is the name of the variable and the value is the dynamic value of the variable, which includes its dynamic type.]

• [Definition: Dynamically known function definitions. This is a set of function definitions. It includes the statically known function definitions as a subset, but may include other function definitions that are not known statically. ]

  The function definitions in the dynamic context are used primarily by the fn:function-lookup function.

  If two function definitions in the dynamically known function definitions have the same name, then their arity ranges must not overlap.

  Note:

  The reason for allowing named functions to be available dynamically beyond those that are available statically is primarily to allow for cases where the run-time execution environment is significantly different from the compile-time environment. This could happen, for example, if a stylesheet or query is compiled within a web server and then executed in the web browser. The fn:function-lookup function allows dynamic discovery of resources that were not available statically.

• [Definition: Current dateTime. This information represents an implementation-dependent point in time during the processing of an expression, and includes an explicit timezone. It can be retrieved by the fn:current-dateTime function. If called multiple times during the execution of an expression, this function always returns the same result.]

• [Definition: Implicit timezone. This is the timezone to be used when a date, time, or dateTime value that does not have a timezone is used in a comparison or arithmetic operation. The implicit timezone is an implementation-defined value of type xs:dayTimeDuration. See Section 3.2.7.3 Timezones ^XS1-2 or Section 3.3.7 dateTime ^XS11-2 for the range of valid values of a timezone.] [Definition: Implicit timezone. This is the timezone to be used when a date, time, or dateTime value that does not have a timezone is used in a comparison or arithmetic operation. The implicit timezone is an implementation-defined value of type xs:dayTimeDuration. See 3.2.7.3 Timezones ^XS1-2 or 3.3.7 dateTime ^XS11-2 for the range of valid values of a timezone.] [Definition: Implicit timezone. This is the timezone to be used when a date, time, or dateTime value that does not have a timezone is used in a comparison or arithmetic operation. The implicit timezone is an implementation-defined value of type xs:dayTimeDuration. See Section 3.2.7.3 Timezones ^XS1-2 or Section 3.3.7 dateTime ^XS11-2 for the range of valid values of a timezone.]

• [Definition: Executable Base URI. This is an absolute URI used to resolve relative URIs during the evaluation of expressions; it is used, for example, to resolve a relative URI supplied to the fn:doc or fn:unparsed-text functions. ]

  URIs are resolved as described in 2.5.6 Resolving a Relative URI Reference.

  The function fn:static-base-uri, despite its name, returns the value of the Executable Base URI.

  In many straightforward processing scenarios, the Executable Base URI in the dynamic context will be the same as the Static Base URI for the corresponding expression in the static context. There are situations, however, where they may differ:

  • Some processors may allow the static analysis of a query or stylesheet to take place on a development machine, while execution of the query or stylesheet happens on a test or production server. In this situation, resources needed during static analysis (such as other modules of the query or stylesheet) will be located on the development machine, by reference to the Static Base URI, while resources needed during execution (such as reference data files) will be located on the production machine, accessed via the Executable Base URI.

  • When the fn:static-base-uri function is called within the initializing expression of an optional parameter in a function declaration, it returns the executable base URI of the relevant function call. This allows a user-written function to accept two parameters: a required parameter containing a relative URI, and an optional parameter containing a base URI. The optional parameter can be given a default value of fn:static-base-uri(), allowing the code in the function body to resolve the relative URI against the executable base URI of the caller.

• [Definition: Default collation. This identifies one of the collations in statically known collations as the collation to be used by functions and operators for comparing and ordering values of type xs:string and xs:anyURI (and types derived from them) when no explicit collation is specified.]

  Note:

  Although the default collation is defined (in 4.0) as a property of the dynamic context, its value will in nearly all cases be known statically. The reason it is defined in the dynamic context is to allow a call on the fn:default-collation function to be used when defining the default value of an optional parameter to a user-defined function. In this situation, the actual value supplied for the parameter is taken from the dynamic context of the relevant function call.

• [Definition: Default language. This is the natural language used when creating human-readable output (for example, by the functions fn:format-date and fn:format-integer) if no other language is requested. The value is a language code as defined by the type xs:language.]

• [Definition: Default calendar. This is the calendar used when formatting dates in human-readable output (for example, by the functions fn:format-date and fn:format-dateTime) if no other calendar is requested. The value is a string.]

• [Definition: Default place. This is a geographical location used to identify the place where events happened (or will happen) when processing dates and times using functions such as fn:format-date, fn:format-dateTime, and fn:civil-timezone, if no other place is specified. It is used when translating timezone offsets to civil timezone names, and when using calendars where the translation from ISO dates/times to a local representation is dependent on geographical location. Possible representations of this information are an ISO country code or an Olson timezone name, but implementations are free to use other representations from which the above information can be derived. The only requirement is that it should uniquely identify a civil timezone, which means that country codes for countries with multiple timezones, such as the United States, are inadequate.]

• [Definition: Available documents. This is a mapping of strings to document nodes. Each string represents the absolute URI of a resource. The document node is the root of a tree that represents that resource using the data model. The document node is returned by the fn:doc function when applied to that URI.] The set of available documents may be empty.

• [Definition: Available text resources. This is a mapping of strings to text resources. Each string represents the absolute URI of a resource. The resource is returned by the fn:unparsed-text function when applied to that URI.] The set of available text resources may be empty.

• [Definition: Available binary resources. This is a mapping of strings to binary resources. Each string represents the absolute URI of a resource. The resource is returned by the fn:unparsed-binary function when applied to that URI.] The set of available binary resources may be empty.

• [Definition: Available collections. This is a mapping of strings to sequences of items. Each string represents the absolute URI of a resource. The sequence of items represents the result of the fn:collection function when that URI is supplied as the argument. ] The set of available collections may be empty.

  Ideally, for every document node D that is in the target of a mapping in available item collections, or that is the root of a tree containing such a node, the document-uri property of D should either be absent, or should be a URI U such that available documents contains a mapping from U to D.

  Note:

  That is to say, the document-uri property of nodes returned by the fn:collection function should be such that calling fn:doc with that URI returns the relevant node.

  It is not always possible to ensure this, especially in cases where dereferencing of document or collection URIs is configurable using configuration files or user-supplied resolver code.

• [Definition: Default collection. This is the sequence of items that would result from calling the fn:collection function with no arguments.] The value of default collection may be initialized by the implementation.

• [Definition: Available URI collections. This is a mapping of strings to sequences of URIs. The string represents the absolute URI of a resource which can be interpreted as an aggregation of a number of individual resources each of which has its own URI. The sequence of URIs represents the result of the fn:uri-collection function when that URI is supplied as the argument. ] There is no implication that the URIs in this sequence can be successfully dereferenced, or that the resources they refer to have any particular media type.

  Note:

  An implementation may maintain some consistent relationship between the available collections and the available URI collections, for example by ensuring that the result of fn:uri-collection(X)!fn:doc(.) is the same as the result of fn:collection(X). However, this is not required. The fn:uri-collection function is more general than fn:collection in that fn:collection allows access to nodes that might lack individual URIs, for example nodes corresponding to XML fragments stored in the rows of a relational database.

• [Definition: Default URI collection. This is the sequence of URIs that would result from calling the fn:uri-collection function with no arguments.] The value of default URI collection may be initialized by the implementation.

• [Definition: Environment variables. This is a mapping from names to values. Both the names and the values are strings. The names are compared using an implementation-defined collation, and are unique under this collation. The set of environment variables is implementation-defined and may be empty.]

  Note:

  A possible implementation is to provide the set of POSIX environment variables (or their equivalent on other operating systems) appropriate to the process in which the expression is evaluated.

2.3.1 Data Model Generation

The input data for an expression must be represented as one or more XDM instances. This process occurs outside the domain of XPath 4.0, which is why Figure 1 represents it in the external processing domain.

In many cases the input data might originate as XML. Here are some steps by which an XML document might be converted to an XDM instance:

1. A document may be parsed using an XML parser that generates an XML Information Set (see [XML Infoset]). The parsed document may then be validated against one or more schemas. This process, which is described in [XML Schema 1.0 Part 1] or [XML Schema 1.1 Part 1], results in an abstract information structure called the Post-Schema Validation Infoset (PSVI). If a document has no associated schema, its Information Set is preserved. (See DM1 in Figure 1)

2. The Information Set or PSVI may be transformed into an XDM instance by a process described in [XQuery and XPath Data Model (XDM) 4.0][XDM 4.0]. (See DM2 in Figure 1)

The above steps provide an example of how an XDM instance might be constructed. An XDM instance might also be constructed in some other way (see DM3 in Figure 1), for example it might be synthesized directly from a relational database, or derived by parsing a JSON text or a CSV file. Whatever the origin, XPath 4.0 is defined in terms of the data model, but it does not place any constraints on how XDM instances are constructed.

The remainder of this section is concerned with the common case where XML data is being processed.

[Definition: Each element node and attribute node in an XDM instance has a type annotation (described in Section 4.1 Schema Information^DM). The type annotation of a node is a reference to a schema type. ] The type-name of a node is the name of the type referenced by its type annotation (but note that the type annotation can be a reference to an anonymous type). If the XDM instance was derived from a validated XML document as described in Section 7.3.3 Construction from a PSVI^DM, the type annotations of the element and attribute nodes are derived from schema validation. XPath 4.0 does not provide a way to directly access the type annotation of an element or attribute node. [Definition: Each element node and attribute node in an XDM instance has a type annotation (described in [XDM 4.0] section 4.1 Schema Information). The type annotation of a node is a reference to a schema type. ] The type-name of a node is the name of the type referenced by its type annotation (but note that the type annotation can be a reference to an anonymous type). If the XDM instance was derived from a validated XML document as described in [XDM 4.0] section 7.3.3 Construction from a PSVI, the type annotations of the element and attribute nodes are derived from schema validation. XPath 4.0 does not provide a way to directly access the type annotation of an element or attribute node. [Definition: Each element node and attribute node in an XDM instance has a type annotation (described in [XDM 4.0] section Section 4.1 Schema InformationDM). The type annotation of a node is a reference to a schema type. ] The type-name of a node is the name of the type referenced by its type annotation (but note that the type annotation can be a reference to an anonymous type). If the XDM instance was derived from a validated XML document as described in [XDM 4.0] section Section 7.3.3 Construction from a PSVIDM, the type annotations of the element and attribute nodes are derived from schema validation. XPath 4.0 does not provide a way to directly access the type annotation of an element or attribute node.

The value of an attribute is represented directly within the attribute node. An attribute node whose type is unknown (such as might occur in a schemaless document) is given the type annotationxs:untypedAtomic.

The value of an element is represented by the children of the element node, which may include text nodes and other element nodes. The type annotation of an element node indicates how the values in its child text nodes are to be interpreted. An element that has not been validated (such as might occur in a schemaless document) is annotated with the schema typexs:untyped. An element that has been validated and found to be partially valid is annotated with the schema type xs:anyType. If an element node is annotated as xs:untyped, all its descendant element nodes are also annotated as xs:untyped. However, if an element node is annotated as xs:anyType, some of its descendant element nodes may have a more specific type annotation.

2.3.4 Input Sources

XPath 4.0 has a set of functions that provide access to XML documents (fn:doc, fn:doc-available), collections (fn:collection, fn:uri-collection), text files (fn:unparsed-text, fn:unparsed-text-lines, fn:unparsed-text-available), and environment variables (fn:environment-variable, fn:available-environment-variables). These functions are defined in Section 14.6 Functions giving access to external information^FO.XPath 4.0 has a set of functions that provide access to XML documents (fn:doc, fn:doc-available), collections (fn:collection, fn:uri-collection), text files (fn:unparsed-text, fn:unparsed-text-lines, fn:unparsed-text-available), and environment variables (fn:environment-variable, fn:available-environment-variables). These functions are defined in [Functions and Operators 4.0] section 14.6 Functions giving access to external information.XPath 4.0 has a set of functions that provide access to XML documents (fn:doc, fn:doc-available), collections (fn:collection, fn:uri-collection), text files (fn:unparsed-text, fn:unparsed-text-lines, fn:unparsed-text-available), and environment variables (fn:environment-variable, fn:available-environment-variables). These functions are defined in [Functions and Operators 4.0] section Section 14.6 Functions giving access to external informationFO.

An expression can access input data either by calling one of these input functions or by referencing some part of the dynamic context that is initialized by the external environment, such as a variable or context value.

2.3.5 Serialization

[Definition: Serialization is the process of converting an XDM instance to a sequence of octets (step DM4 in Figure 1.), as described in [XSLT and XQuery Serialization 4.0].] [Definition: Serialization is the process of converting an XDM instance to a sequence of octets (step DM4 in Figure 1.), as described in [Serialization 4.0].] [Definition: Serialization is the process of converting an XDM instance to a sequence of octets (step DM4 in Figure 1.), as described in [XSLT and XQuery Serialization 4.0].]

Serialization is outside the scope of the XPath specification, except to the extent that there is a function fn:serialize that enables serialization to be invoked.

2.4.3 Handling Dynamic Errors

Except as noted in this document, if any operand of an expression raises a dynamic error, the expression also raises a dynamic error. If an expression can validly return a value or raise a dynamic error, the implementation may choose to return the value or raise the dynamic error (see 2.4.4 Errors and Optimization). For example, the logical expression expr1 and expr2 may return the value false if either operand returns false, or may raise a dynamic error if either operand raises a dynamic error.

If more than one operand of an expression raises an error, the implementation may choose which error is raised by the expression. For example, in this expression:

($x div $y) + xs:decimal($z)

both the sub-expressions ($x div $y) and xs:decimal($z) may raise an error. The implementation may choose which error is raised by the + expression. Once one operand raises an error, the implementation is not required, but is permitted, to evaluate any other operands.

[Definition: In addition to its identifying QName, a dynamic error may also carry a descriptive string and one or more additional values called error values.] An implementation may provide a mechanism whereby an application-defined error handler can process error values and produce diagnostic messages. The host language may also provide error handling mechanisms.

A dynamic error may be raised by a system function or operator. For example, the div operator raises an error if its operands are xs:decimal values and its second operand is equal to zero. Errors raised by system functions and operators are defined in [XQuery and XPath Functions and Operators 4.0] or the host language.A dynamic error may be raised by a system function or operator. For example, the div operator raises an error if its operands are xs:decimal values and its second operand is equal to zero. Errors raised by system functions and operators are defined in [Functions and Operators 4.0] or the host language.A dynamic error may be raised by a system function or operator. For example, the div operator raises an error if its operands are xs:decimal values and its second operand is equal to zero. Errors raised by system functions and operators are defined in [XQuery and XPath Functions and Operators 4.0] or the host language.

A dynamic error can also be raised explicitly by calling the fn:error function, which always raises a dynamic error and never returns a value. This function is defined in Section 3.1.1 fn:error^FO. For example, the following function call raises a dynamic error, providing a QName that identifies the error, a descriptive string, and a diagnostic value (assuming that the prefix app is bound to a namespace containing application-defined error codes):A dynamic error can also be raised explicitly by calling the fn:error function, which always raises a dynamic error and never returns a value. This function is defined in [Functions and Operators 4.0] section 3.1.1 fn:error. For example, the following function call raises a dynamic error, providing a QName that identifies the error, a descriptive string, and a diagnostic value (assuming that the prefix app is bound to a namespace containing application-defined error codes):A dynamic error can also be raised explicitly by calling the fn:error function, which always raises a dynamic error and never returns a value. This function is defined in [Functions and Operators 4.0] section Section 3.1.1 fn:errorFO. For example, the following function call raises a dynamic error, providing a QName that identifies the error, a descriptive string, and a diagnostic value (assuming that the prefix app is bound to a namespace containing application-defined error codes):

error( #app:err057, "Unexpected value", string($v) )

2.5.1 Document Order

An ordering called document order is defined among all the nodes accessible during processing of a given expression, which may consist of one or more trees (documents or fragments).

Document order applies both to XNodes (typically corresponding to nodes in an XML document, and generally referred to simply as nodes), and also to JNodes^DM, often corresponding to the contents of a JSON source text. These are known collectively as GNodes^DM (for "generalized node").

Document order is defined in Section 6.2 Document Order^DM, and its definition is repeated here for convenience. Document order is a total ordering, although the relative order of some nodes is implementation-dependent. [Definition: Informally, document order is the order in which nodes appear in the XML serialization of a document.] [Definition: Document order is stable, which means that the relative order of two nodes will not change during the processing of a given expression, even if this order is implementation-dependent.] [Definition: The node ordering that is the reverse of document order is called reverse document order.] Document order is defined in [XDM 4.0] section 6.2 Document Order, and its definition is repeated here for convenience. Document order is a total ordering, although the relative order of some nodes is implementation-dependent. [Definition: Informally, document order is the order in which nodes appear in the XML serialization of a document.] [Definition: Document order is stable, which means that the relative order of two nodes will not change during the processing of a given expression, even if this order is implementation-dependent.] [Definition: The node ordering that is the reverse of document order is called reverse document order.] Document order is defined in [XDM 4.0] section Section 6.2 Document OrderDM, and its definition is repeated here for convenience. Document order is a total ordering, although the relative order of some nodes is implementation-dependent. [Definition: Informally, document order is the order in which nodes appear in the XML serialization of a document.] [Definition: Document order is stable, which means that the relative order of two nodes will not change during the processing of a given expression, even if this order is implementation-dependent.] [Definition: The node ordering that is the reverse of document order is called reverse document order.]

Within an XTree^DM, (that is, a tree consisting of XNodes), document order satisfies the following constraints:

1. The root node precedes all other nodes.

2. A parent node precedes its children (and therefore its descendants).

3. The children of a node N precede the following siblings of N.

4. Namespace nodes immediately follow the element node with which they are associated. The relative order of namespace nodes is stable but implementation-dependent.

5. Attribute nodes immediately follow the namespace nodes of the element node with which they are associated. The relative order of attribute nodes is stable but implementation-dependent.

6. The relative order of siblings is the order in which they occur in the children property of their parent node.

Similarly, within an JTree^DM, (that is, a tree consisting of JNodes), document order satisfies the following constraints:

1. The root JNode precedes all other JNodes.

2. A parent JNode precedes its children (and therefore its descendants).

3. The children of a JNode N precede the following siblings of N.

4. The children of a JNode that wraps an array follow the ordering of the members of the array.

5. The children of a JNode that wraps a map follow the ordering of the entries in the map.

The relative order of nodes in distinct trees is stable but implementation-dependent, subject to the following constraint: If any node in a given tree T1 is before any node in a different tree T2, then all nodes in tree T1 are before all nodes in tree T2.

2.5.2 Typed Value and String Value

Every node (that is, every XNode^DM) has a typed value and a string value, except for nodes whose value is absent^DM. [Definition: The typed value of a node is a sequence of atomic items and can be extracted by applying the Section 2.1.4 fn:data^FO function to the node.] [Definition: The string value of a node is a string and can be extracted by applying the Section 2.1.3 fn:string^FO function to the node.] Every node (that is, every XNode^DM) has a typed value and a string value, except for nodes whose value is absent^DM. [Definition: The typed value of a node is a sequence of atomic items and can be extracted by applying the data function to the node.] [Definition: The string value of a node is a string and can be extracted by applying the string function to the node.] Every node (that is, every XNode^DM) has a typed value and a string value, except for nodes whose value is absent^DM. [Definition: The typed value of a node is a sequence of atomic items and can be extracted by applying the Section 2.1.4 fn:dataFOdata function to the node.] [Definition: The string value of a node is a string and can be extracted by applying the Section 2.1.3 fn:stringFOstring function to the node.]

An implementation may store both the typed value and the string value of a node, or it may store only one of these and derive the other as needed. The string value of a node must be a valid lexical representation of the typed value of the node, but the node is not required to preserve the string representation from the original source document. For example, if the typed value of a node is the xs:integer value 30, its string value might be "30" or "0030".

The typed value, string value, and type annotation of a node are closely related. If the node was created by mapping from an Infoset or PSVI, the relationships among these properties are defined by rules in Section 4.1 Schema Information^DM.The typed value, string value, and type annotation of a node are closely related. If the node was created by mapping from an Infoset or PSVI, the relationships among these properties are defined by rules in [XDM 4.0] section 4.1 Schema Information.The typed value, string value, and type annotation of a node are closely related. If the node was created by mapping from an Infoset or PSVI, the relationships among these properties are defined by rules in [XDM 4.0] section Section 4.1 Schema InformationDM.

The relationship between typed value and string value for various kinds of nodes is summarized and illustrated by examples below.

1. For text and document nodes, the typed value of the node is the same as its string value, as an instance of the type xs:untypedAtomic. The string value of a document node is formed by concatenating the string values of all its descendant text nodes, in document order.

2. The typed value of a comment, namespace, or processing instruction node is the same as its string value. It is an instance of the type xs:string.

3. The typed value of an attribute node with the type annotationxs:anySimpleType or xs:untypedAtomic is the same as its string value, as an instance of xs:untypedAtomic. The typed value of an attribute node with any other type annotation is derived from its string value and type annotation using the lexical-to-value-space mapping defined in [XML Schema 1.0] or [XML Schema 1.1] Part 2 for the relevant type.

   Example: A1 is an attribute having string value "3.14E-2" and type annotation xs:double. The typed value of A1 is the xs:double value whose lexical representation is 3.14E-2.

   Example: A2 is an attribute with type annotation xs:IDREFS, which is a list datatype whose item type is the atomic datatype xs:IDREF. Its string value is "bar baz faz". The typed value of A2 is a sequence of three atomic items ("bar", "baz"", "faz""), each of type xs:IDREF. The typed value of a node is never treated as an instance of a named list type. Instead, if the type annotation of a node is a list type (such as xs:IDREFS), its typed value is treated as a sequence of the generalized atomic type from which it is derived (such as xs:IDREF).

4. For an element node, the relationship between typed value and string value depends on the node’s type annotation, as follows:

   1. If the type annotation is xs:untyped or xs:anySimpleType or denotes a complex type with mixed content (including xs:anyType), then the typed value of the node is equal to its string value, as an instance of xs:untypedAtomic. However, if the nilled property of the node is true, then its typed value is the empty sequence.

      Example: E1 is an element node having type annotation xs:untyped and string value "1999-05-31". The typed value of E1 is "1999-05-31", as an instance of xs:untypedAtomic.

      Example: E2 is an element node with the type annotation formula, which is a complex type with mixed content. The content of E2 consists of the character H, a child element named subscript with string value "2", and the character O. The typed value of E2 is "H2O" as an instance of xs:untypedAtomic.

   2. If the type annotation denotes a simple type or a complex type with simple content, then the typed value of the node is derived from its string value and its type annotation in a way that is consistent with schema validation. However, if the nilled property of the node is true, then its typed value is the empty sequence.

      Example: E3 is an element node with the type annotation cost, which is a complex type that has several attributes and a simple content type of xs:decimal. The string value of E3 is "74.95". The typed value of E3 is 74.95, as an instance of xs:decimal.

      Example: E4 is an element node with the type annotation hatsizelist, which is a simple type derived from the atomic typehatsize, which in turn is derived from xs:integer. The string value of E4 is "7 8 9". The typed value of E4 is a sequence of three values (7, 8, 9), each of type hatsize.

      Example: E5 is an element node with the type annotation my:integer-or-string which is a union type with member types xs:integer and xs:string. The string value of E5 is "47". The typed value of E5 is 47 as a xs:integer, since xs:integer is the member type that validated the content of E5. In general, when the type annotation of a node is a union type, the typed value of the node will be an instance of one of the member types of the union.

      Note:

      If an implementation stores only the string value of a node, and the type annotation of the node is a union type, the implementation must be able to deliver the typed value of the node as an instance of the appropriate member type.

   3. If the type annotation denotes a complex type with empty content, then the typed value of the node is the empty sequence and its string value is the zero-length string.

   4. If the type annotation denotes a complex type with element-only content, then the typed value of the node is absent^DM. The fn:data function raises a type error [err:FOTY0012]^FO40 when applied to such a node. The string value of such a node is equal to the concatenated string values of all its text node descendants, in document order.

      Example: E6 is an element node with the type annotation weather, which is a complex type whose content type specifies element-only. E6 has two child elements named temperature and precipitation. The typed value of E6 is absent^DM, and the fn:data function applied to E6 raises an error.

2.5.3 Atomization

The semantics of some XPath 4.0 operators depend on a process called atomization. Atomization is applied to a value when the value is used in a context in which a sequence of atomic items is required. The result of atomization is either a sequence of atomic items or a type error [err:FOTY0012]^FO40. [Definition: Atomization of a sequence is defined as the result of invoking the fn:data function, as defined in Section 2.1.4 fn:data^FO.] The semantics of some XPath 4.0 operators depend on a process called atomization. Atomization is applied to a value when the value is used in a context in which a sequence of atomic items is required. The result of atomization is either a sequence of atomic items or a type error [err:FOTY0012]^FO40. [Definition: Atomization of a sequence is defined as the result of invoking the fn:data function, as defined in [Functions and Operators 4.0] section 2.1.4 fn:data.] The semantics of some XPath 4.0 operators depend on a process called atomization. Atomization is applied to a value when the value is used in a context in which a sequence of atomic items is required. The result of atomization is either a sequence of atomic items or a type error [err:FOTY0012]^FO40. [Definition: Atomization of a sequence is defined as the result of invoking the fn:data function, as defined in [Functions and Operators 4.0] section Section 2.1.4 fn:dataFO.]

The semantics of fn:data are repeated here for convenience. The result of fn:data is the sequence of atomic items produced by applying the following rules to each item in the input sequence:

• If the item is an atomic item, it is returned.

• If the item is a node (specifically, an XNode), its typed value is returned (a type error [err:FOTY0012]^FO40 is raised if the node has no typed value.)

• If the item is a JNode^DM, its ·content· property is atomized and the result is returned.

• If the item is a function item (other than an array) or map a type error [err:FOTY0013]^FO40 is raised.

• If the item is an array $a, atomization is defined as $a?* ! fn:data(.), which is equivalent to atomizing the members of the array.

  Note:

  This definition recursively atomizes members that are arrays. Hence, the result of atomizing the array [ [ 1, 2, 3 ], [ 4, 5, 6 ] ] is the sequence (1, 2, 3, 4, 5, 6).

Atomization is used in processing many expressions that are designed to operate on atomic items, including:

• Arithmetic expressions

• Comparison expressions

• Function calls and returns

• Cast expressions

Atomization plays an important role in the coercion rules used when converting a supplied argument in a function call to the type declared in the function signature.

2.5.4 Effective Boolean Value

Under certain circumstances (some of which are listed below), it is necessary to find the effective boolean value of a value. [Definition: The effective boolean value of a value is defined as the result of applying the fn:boolean function to the value, as defined in Section 8.3.1 fn:boolean^FO.] Under certain circumstances (some of which are listed below), it is necessary to find the effective boolean value of a value. [Definition: The effective boolean value of a value is defined as the result of applying the fn:boolean function to the value.] Under certain circumstances (some of which are listed below), it is necessary to find the effective boolean value of a value. [Definition: The effective boolean value of a value is defined as the result of applying the fn:boolean function to the value, as defined in Section 8.3.1 fn:booleanFO.]

The dynamic semantics of fn:boolean are repeated here for convenience:

1. If its operand is an empty sequence, fn:boolean returns false.

2. If its operand is a sequence whose first item is a GNode^DM, fn:boolean returns true.

3. If its operand is a singleton value of type xs:boolean or derived from xs:boolean, fn:boolean returns the value of its operand unchanged.

4. If its operand is a singleton value of type xs:string, xs:anyURI, xs:untypedAtomic, or a type derived from one of these, fn:boolean returns false if the operand value has zero length; otherwise it returns true.

5. If its operand is a singleton value of any numeric type or derived from a numeric type, fn:boolean returns false if the operand value is NaN or is numerically equal to zero; otherwise it returns true.

6. In all other cases, fn:boolean raises a type error [err:FORG0006]^FO40.

   Note:

   For instance, fn:boolean raises a type error if the operand is a function, a map, or an array.

The effective boolean value of a sequence is computed implicitly during processing of the following types of expressions:

• Logical expressions (and, or)

• The fn:not function

• Certain types of predicates, such as a[b]

• Conditional expressions (if)

• Quantified expressions (some, every)

• General comparisons, in XPath 1.0 compatibility mode.

3.2.8 Function, Map, and Array Types

The following sections describe the syntax for item types for functions, including arrays and maps.

The subtype relation among these types is described in the various subsections of 3.3.2 Subtypes of Item Types.

3.4.4 Function Coercion

Function coercion is a transformation applied to function items during application of the coercion rules. [Definition: Function coercion wraps a function item in a new function whose signature is the same as the expected type. This effectively delays the checking of the argument and return types until the function is called.]

Given a function F, and an expected function type T, function coercion proceeds as follows:

1. If F has higher arity than T, a type error is raised [err:XPTY0004]

2. If F has lower arity than T, then F is wrapped in a new function that declares and ignores the additional argument; the following steps are then applied to this new function.

   For example, if T is function(node(), xs:boolean) as xs:string, and the supplied function is fn:name#1, then the supplied function is effectively replaced by function($n as node(), $b as xs:boolean) as xs:string { fn:name($n) }

   Note:

   This mechanism makes it easier to design versatile and extensible higher-order functions. For example, in previous versions of this specification, the second argument of the fn:filter function expected an argument of type function(item()) as xs:boolean. This has now been extended to function(item(), xs:integer) as xs:boolean, but existing code continues to work, because callback functions that are not interested in the value of the second argument simply ignore it.

3. A type error is raised [err:XPTY0004] if, for any parameter type, or for the result type, the relevant type in the signature of the supplied function and the relevant type in the expected function type are substantively disjoint.

   For example, the types xs:integer and xs:string are substantively disjoint, so a function with signature function(xs:integer) as xs:boolean cannot be supplied where the expected type is function(xs:string) as xs:boolean.

4. Function coercion then returns a new function item with the following properties (as defined in Section 8.1 Function Items^DM): Function coercion then returns a new function item with the following properties (as defined in [XDM 4.0] section 8.1 Function Items): Function coercion then returns a new function item with the following properties (as defined in [XDM 4.0] section Section 8.1 Function ItemsDM):

   • name: The name of F(if not absent).

   • identity: A new function identity distinct from the identity of any other function item.

     Note:

     See also 4.5.7 Function Identity.

   • signature: Annotations is set to the annotations of F. TypedFunctionType is set to the expected type.

   • implementation: In effect, a FunctionBody that calls F, passing it the parameters of this new function, in order.

   • nonlocal variable bindings: An empty mapping.

These rules have the following consequences:

• SequenceType matching of the function’s arguments and result are delayed until that function is called.

• When the coerced function is called, the supplied arguments must match the parameter typed defined in T; it is not sufficient to match the parameter types defined in F.

• The coercion rules rules applied to the function’s arguments and result are defined by the SequenceType it has most recently been coerced to. Additional coercion rules could apply when the wrapped function is called.

• If an implementation has static type information about a function, that can be used to type check the function’s argument and return types during static analysis.

• When function coercion is applied to a map or an array, the resulting function is not a map or array, and cannot be used as such. For example, the expression

  let $f as function(xs:integer) as xs:boolean := { 0: false(), 1: true() }
  return $f?0

  raises a type error, because a lookup expression requires the left hand operand to be a map or array, and $f is neither.

• When function types are used as alternatives in a choice item type, the supplied function is coerced to the first alternative for which coercion does not raise a type error. In this situation it is important to write the alternatives in order, with the most specific first.

Since maps and arrays are also functions in XPath 4.0, function coercion applies to them as well. For instance, consider the following expression:

let $m := {
  "Monday" : true(),
  "Wednesday" : false(),
  "Friday" : true()
}
let $days := ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday")
return filter($days, $m)

The map $m is an instance of function(xs:anyAtomicType?) as item()*. When the fn:filter() function is called, the following occurs to the map:

1. The map $m is treated as a function equivalent to map:get($m, ?).

2. The coercion rules result in applying function coercion to this function, wrapping it in a new function (M′) with the signature function(item(), xs:integer) as xs:boolean.

3. When M′ is called by fn:filter(), coercion and SequenceType matching rules are applied to the argument, resulting in an item() value ($a) or a type error.

4. The function map:get($m, ?) is called with $a as the argument; this returns either an xs:boolean or the empty sequence (call the result R).

5. The wrapper function $p applies the coercion rules to R. If R is an xs:boolean the matching succeeds. When it is an empty sequence (in particular, $m does not contain a key for "Tuesday"), a type error is raised [err:XPTY0004], since the expected type is xs:boolean and the actual type is an empty sequence.

Consider the following expression:

let $m := {
   "Monday" : true(),
   "Wednesday" : false(),
   "Friday" : true(),
}
let $days := ("Monday", "Wednesday", "Friday")
return filter($days, $m)

In this case the result of the expression is the sequence ("Monday", "Friday"). But if the input sequence included the string "Tuesday", the filter operation would fail with a type error.

declare function local:filter(
  $s as item()*, 
  $p as function(xs:string) as xs:boolean
) as item()* {
  $s[$p(.)]
};

let $f := function($a) { $a mod 2 = 0 }
return local:filter(1 to 10, $f)

4.2.1 Literals

[Definition: A literal is a direct syntactic representation of an atomic item.] XPath 4.0 supports three kinds of literals: numeric literals, string literals, and QName literals.

4.5.1 Static Function Calls

The static context for an expression includes a set of statically known function definitions. Every function definition in the static context has a name (which is an expanded QName) and an arity range, which is a range of permitted arities for calls on that function. Two function definitions having the same name must not have overlapping arity ranges. This means that for a given static function call, it is possible to identify the target function definition in the static context unambiguously from knowledge of the function name and the number of supplied arguments.

A static function call is bound to a function definition in the static context by matching the name and arity. If the function call has P positional arguments followed by K keyword arguments, then the required arity is P+K, and the static context must include a function definition whose name matches the expanded QName in the function call, and whose arity range includes this required arity. This is the function chosen to be called. The result of the function is obtained by evaluating the expression that forms its implementation, with a dynamic context that provides values for all the declared parameters, initialized as described in 4.5.1.2 Evaluating Static Function Calls below.

Similarly, a function reference of the form f#N binds to a function definition in the static context whose name matches f where MinP ≤ N and MaxP ≥ N. The result of evaluating a function reference is a function item which can be called using a dynamic function call. Function items are never variadic and their arguments are always supplied positionally. For example, the function reference fn:concat#3 returns a function item with arity 3, which is always called by supplying three positional arguments, and whose effect is the same as a static call on fn:concat with three positional arguments.

The detailed rules for evaluating static function calls and function references are defined in subsequent sections.

4.5.2 Function Items

A function item is an XDM value that can be bound to a variable, or manipulated in various ways by XPath 4.0 expressions. The most significant such expression is a dynamic function call, which supplies values of arguments and evaluates the function to produce a result.

The syntax of dynamic function calls is defined in 4.5.3 Dynamic Function Calls.

A number of constructs can be used to produce a function item, notably:

• A named function reference (see 4.5.5 Named Function References) constructs a function item by reference to function definitions in the static context. For example, fn:node-name#1 returns a function item whose effect is to call the static fn:node-name function with one argument.

• An inline function (see 4.5.6 Inline Function Expressions ) constructs a function item whose body is defined locally. For example, the construct fn($x) { $x + 1 } returns a function item whose effect is to increment the value of the supplied argument.

• A partial function application (see 4.5.4 Partial Function Application) derives one function item from another by supplying the values of some of its arguments. For example, fn:ends-with(?, ".txt") returns a function item with one argument that tests whether the supplied string ends with the substring ".txt".

• Maps and arrays are also function items. See 4.13.1.1 Map Constructors and 4.13.2.1 Array Constructors.

• The fn:function-lookup function can be called to discover functions that are present in the dynamic context.

• The fn:load-xquery-module function can be called to load functions dynamically from an external XQuery library module.

• Some system functions such as fn:random-number-generator and fn:op return a function item as their result.

These constructs are described in detail in the following sections, or in [XQuery and XPath Functions and Operators 4.0].

4.5.4 Partial Function Application

[Definition: A static or dynamic function call is a partial function application if one or more arguments is an ArgumentPlaceholder.]

The rules for partial function application in static function calls and dynamic function calls have a great deal in common, but they are stated separately below for clarity.

Partial function application delivers function items, whose arity is equal to the number of placeholders in the call.

A static partial function application always delivers one function item. A dynamic partial function application delivers one function item for each function item in the input.

More specifically, each function item in the result of the partial function application is a partially applied function. [Definition: A partially applied function is a function created by partial function application.]

For static function calls, the result is obtained as follows:

1. The function definitionFD to be partially applied is determined in the same way as for a static function call without placeholders, as described in 4.5.1.1 Static Function Call Syntax. For this purpose an ArgumentPlaceholder contributes to the count of arguments.

2. The parameters of FD are classified into three categories:

   • Parameters that map to a placeholder, referred to as placeholder parameters.

   • Parameters for which an explicit value is given in the function call (either positionally or by keyword), referred to as explicitly supplied parameters.

   • Parameters (which are necessarily optional parameters) for which no corresponding argument is supplied, either as a placeholder or with an explicit value. These are referred to as defaulted parameters.

   Note:

   A partial function application need not have any explicitly supplied parameters. For example, the partial function application fn:string(?) is allowed; it has exactly the same effect as the named function referencefn:string#1.

3. Explicitly supplied parameters and defaulted parameters are evaluated and converted to the required type using the rules for a static function call. This may result in an error being raised.

   A type error is raised if any of the explicitly supplied or defaulted parameters, after applying the coercion rules, does not match the required type of the corresponding parameter.

   In addition, a dynamic error may be raised if any of the explicitly supplied or defaulted parameters does not match other constraints on the value of that parameter (for example, if the value supplied for a parameter expecting a regular expression is not a valid regular expression); or if the processor is able to establish that evaluation of the resulting function will fail for any other reason (for example, if an error is raised while evaluating a subexpression in the function body that depends only on explicitly supplied and defaulted parameters).

   In all cases the error code is the same as for a static function call supplying the same invalid value(s).

   In the particular case where all the supplied arguments are placeholders, the error behavior should be the same as for an equivalent named function reference: for example, fn:id#1 fails if there is no context node, and fn:id(?)should fail likewise.

4. The result is a partially applied function having the following properties (which are defined in Section 8.1 Function Items^DM): The result is a partially applied function having the following properties (which are defined in [XDM 4.0] section 8.1 Function Items): The result is a partially applied function having the following properties (which are defined in [XDM 4.0] section Section 8.1 Function ItemsDM):

   • name: The name of FD if all parameters map to placeholders, that is, if the partial function application is equivalent to the corresponding named function reference. Otherwise, the name is absent.

   • identity: A new function identity distinct from the identity of any other function item.

     Note:

     See also 4.5.7 Function Identity.

   • arity: The number of placeholders in the function call.

   • signature: The parameters in the returned function are the parameters of FD that have been identified as placeholder parameters, retaining the order in which the placeholders appear in the function call. The result type of the returned function is the same as the result type of FD.

     An implementation which can determine a more specific signature (for example, through use of type analysis) is permitted to do so.

   • annotations: The annotations of FD.

   • body: The body of FD.

   • captured context: The static and dynamic context of the function call, augmented, for each explicitly supplied parameter and each defaulted parameter, with a binding of the converted argument value to the corresponding parameter name.

   Note:

   A partial function application can be used to change the order of parameters, for example fn:contains(substring := ?, value := ?) returns a function item that is equivalent to fn:contains#2, but with the order of arguments reversed.

   Example: Partial Application of a System Function

   The following partial function application creates a function item that computes the sum of squares of a sequence.

   let $sum-of-squares := fold-right(?, 0, function($a, $b) { $a*$a + $b })
   return $sum-of-squares(1 to 3)

   $sum-of-squares is an anonymous function. It has one parameter, named $seq, which is taken from the corresponding parameter in fn:fold-right (the other two parameters are fixed). The implementation is the implementation of fn:fold-right, which is a context-independent system function. The nonlocal bindings contain the fixed bindings for the second and third parameters of fn:fold-right.

For dynamic function calls, the result is obtained as follows:

1. The base expression of the function call is evaluated. If this is not of type function(*)* (a sequence of zero or more function items) then a type error is raised.

2. The result of the dynamic function call is the sequence concatenation of the results of partial applying each function item, retaining order. That is, the result of F(X, Y, ...) is for $FI in F return $FI(X, Y, ...). The result of a dynamic function call applied to a single function item FI is defined by the rules that follow.

3. An ArgumentPlaceholder contributes to the count of arguments.

4. The parameters of FI are classified into two categories:

   • Parameters that map to a placeholder, referred to as placeholder parameters.

   • Parameters for which an explicit value is given in the function call, referred to as supplied parameters.

   Note:

   A partial function application need not have any explicitly supplied parameters. For example, if $f is a function with arity 2, then the partial function application $f(?, ?) returns a function that has exactly the same effect as $f.

5. Arguments corresponding to supplied parameters are evaluated and converted to the required type of the parameter, using the rules for dynamic function calls.

   A type error is raised if any of the supplied parameters, after applying the coercion rules, does not match the required type.

   In addition, a dynamic error may be raised if any of the supplied parameters does not match other constraints on the value of that parameter (for example, if the value supplied for a parameter expecting a regular expression is not a valid regular expression); or if the processor is able to establish that evaluation of the resulting function will fail for any other reason (for example, if an error is raised while evaluating a subexpression in the function body that depends only on explicitly supplied parameters).

   In both cases the error code is the same as for a dynamic function call supplying the same invalid value.

6. The result of the partial function application is a partially applied function with the following properties (which are defined in Section 8.1 Function Items^DM): The result of the partial function application is a partially applied function with the following properties (which are defined in [XDM 4.0] section 8.1 Function Items): The result of the partial function application is a partially applied function with the following properties (which are defined in [XDM 4.0] section Section 8.1 Function ItemsDM):

   • name: Absent.

   • arity: The number of placeholders in the function call.

   • signature: The signature of FI, removing the types of supplied parameters. An implementation which can determine a more specific signature (for example, through use of type analysis) is permitted to do so.

   • annotations: The annotations of FI.

   • body: The body of FI.

   • captured context: the captured context of FI, augmented, for each supplied parameter, with a binding of the converted argument value to the corresponding parameter name.

   Note:

   In a dynamic partial function application, argument keywords are not available, so it is not possible to change the order of parameters.

   Example: Partial Application of an Anonymous Function

   In the following example, $f is an anonymous function, and $paf is a partially applied function created from $f.

   let $f := function($seq, $delim) { fold-left($seq, "", concat(?, $delim, ?)) }
   let $paf := $f(?, ".")
   return $paf(1 to 5)

   $paf is also an anonymous function. It has one parameter, named $delim, which is taken from the corresponding parameter in $f (the other parameter is fixed). The implementation of $paf is the implementation of $f, which is fn:fold-left($seq, "", fn:concat(?, $delim, ?)). This implementation is associated with the SC and DC of the original expression in $f. The nonlocal bindings associate the value "." with the parameter $delim.

Partial function application never returns a map or an array. If $f is a map or an array, then $f(?) is a partial function application that returns a function, but the function it returns is neither a map nor an array.

let $a := { "A": 1, "B": 2 }(?)
return $a("A")

4.5.5 Named Function References

[Definition: A named function reference is an instance of the production NamedFunctionRef: it is an expression (written name#arity) which evaluates to a function item, the details of the function item being based on the properties of a function definition in the static context.]

The name and arity of the required function are known statically.

The EQName is expanded using the default function namespace rule.

The expanded QName and arity must correspond to a function definition present in the static context. More specifically, for a named function reference F#N, there must be a function definition in the statically known function definitions whose name matches F, and whose arity range includes N. Call this function definitionFD.

If FD is context dependent for the given arity, then the returned function item has a captured context comprising the static and dynamic context of the named function reference.

let $f := <foo/>/fn:name#0 return <bar/>/$f()

An error is raised if the identified function depends on components of the static or dynamic context that are not present, or that have unsuitable values. For example [err:XPDY0002] is raised for the expression fn:name#0 if the context item is absent, and [err:FODC0001]^FO is raised for the call fn:id#1 if the context item is not a node in a tree that is rooted at a document node. The error that is raised is the same as the error that would be raised by the corresponding function if called with the same static and dynamic context.

If the expanded QName and arity in a named function reference do not match the name and arity range of a function definition in the static context, a static error is raised [err:XPST0017].

The value of a NamedFunctionRef is a function itemFI obtained from FD as follows:

• name: The name of FD.

• identity:

  • If FD is context dependent for the given arity, then a new function identity distinct from the identity of any other function item.

    Note:

    In the general case, a function reference to a context-dependent function will produce different results every time it is evaluated, because the resulting function item has a captured context (see Section 8.1 Function Items^DM) that includes the dynamic context of the particular evaluation. Optimizers, however, are allowed to detect cases where the captured context happens to be the same, or where any variations are immaterial, and where it is therefore safe to return the same function item each time. This might be the case, for example, where the only context dependency of a function is on the default collation, and the default collation for both evaluations is known to be the same.In the general case, a function reference to a context-dependent function will produce different results every time it is evaluated, because the resulting function item has a captured context (see [XDM 4.0] section 8.1 Function Items) that includes the dynamic context of the particular evaluation. Optimizers, however, are allowed to detect cases where the captured context happens to be the same, or where any variations are immaterial, and where it is therefore safe to return the same function item each time. This might be the case, for example, where the only context dependency of a function is on the default collation, and the default collation for both evaluations is known to be the same.In the general case, a function reference to a context-dependent function will produce different results every time it is evaluated, because the resulting function item has a captured context (see [XDM 4.0] section Section 8.1 Function ItemsDM) that includes the dynamic context of the particular evaluation. Optimizers, however, are allowed to detect cases where the captured context happens to be the same, or where any variations are immaterial, and where it is therefore safe to return the same function item each time. This might be the case, for example, where the only context dependency of a function is on the default collation, and the default collation for both evaluations is known to be the same.

  • Otherwise, a function identity that is the same as that produced by the evaluation of any other named function reference with the same function name and arity.

    This rule applies even across different execution scopes^FO: for example if a parameter to a call to fn:transform is set to the result of the expression fn:abs#1, then the function item passed as the parameter value will be identical to that obtained by evaluating the expression fn:abs#1 within the target XSLT stylesheet.

    This rule also applies when the target function definition is nondeterministic^FO. For example all evaluations of the named function reference map:keys#2 return identical function items, even though two evaluations of map:keys with the same arguments may produce different results.

  Note:

  See also 4.5.7 Function Identity.

• arity: As specified in the named function reference.

• signature: Formed from the required types of the first A parameters of FD, and the function result type of FD.

• annotations: The annotations of FD.

• body: The body of FD.

• captured context: Comprises the static and dynamic context of the named function reference, augmented with bindings of the names of parameters of FD beyond the A’th parameter, to their respective default values.

  Note:

  In practice, it is necessary to retain only the parts of the context that the function actually depends on (if any).

The following are examples of named function references:

• fn:abs#1 references the fn:abs function which takes a single argument.

• fn:concat#5 references the fn:concat function which takes 5 arguments.

• local:myfunc#2 references a function named local:myfunc which takes 2 arguments.

4.5.6 Inline Function Expressions

[Definition: An inline function expression is an instance of the construct InlineFunctionExpr. When evaluated, an inline function expression creates an anonymous function whose properties are defined directly in the inline function expression.] An inline function expression defines the names and types of the parameters to the function, the type of the result, and the body of the function.

An inline function expression whose FunctionSignature is omitted is known as a focus function. Focus functions are described in 4.5.6.1 Focus Functions.

[Definition: An anonymous function is a function item with no name. Anonymous functions may be created, for example, by evaluating an inline function expression or by partial function application.]

The keywords function and fn are synonymous.

The syntax allows the names and types of the function argument to be declared, along with the type of the result:

function($x as xs:integer, $y as xs:integer) as xs:integer { $x + $y }

The types can be omitted, and the keyword can be abbreviated:

fn($x, $y) { $x + $y }

A zero-arity function can be written as, for example, fn() { current-date() }.

If a function parameter is declared using a name but no type, its default type is item()*. If the result type is omitted, its default result type is item()*.

The parameters of an inline function expression are considered to be variables whose scope is the function body. It is a static error [err:XQST0039] for an inline function expression to have more than one parameter with the same name.

The static context for the function body is inherited from the location of the inline function expression.

The variables in scope for the function body include all variables representing the function parameters, as well as all variables that are in scope for the inline function expression.

The result of an inline function expression is a single function item with the following properties (as defined in Section 8.1 Function Items^DM):The result of an inline function expression is a single function item with the following properties (as defined in [XDM 4.0] section 8.1 Function Items):The result of an inline function expression is a single function item with the following properties (as defined in [XDM 4.0] section Section 8.1 Function ItemsDM):

• name: Absent.

• identity: A new function identity distinct from the identity of any other function item.

  Note:

  See also 4.5.7 Function Identity.

• signature: A FunctionType constructed from the SequenceTypes in the InlineFunctionExpr. An implementation which can determine a more specific signature (for example, through use of type analysis of the function’s body) is permitted to do so.

• annotations:

• body: The FunctionBody of the InlineFunctionExpr.

• captured context: the static context is the static context of the inline function expression. The dynamic context has an absent focus, and a set of variable bindings comprising the variable values component of the dynamic context of the InlineFunctionExpr.

The following are examples of some inline function expressions:

• This example creates a function that takes no arguments and returns a sequence of the first 6 primes:

  function() as xs:integer+ { 2, 3, 5, 7, 11, 13 }

• This example creates a function that takes two xs:double arguments and returns their product:

  fn($a as xs:double, $b as xs:double) as xs:double { $a * $b }

• This example creates and invokes a function that captures the value of a local variable in its scope:

  let $incrementors := (
    for $x in 1 to 10
    return function($y) as xs:integer { $x + $y }
  )
  return $incrementors[2](4)

  The result of this expression is 6

4.6.4 Axis Steps

[Definition: An axis step is an instance of the production AxisStep: it is an expression that returns a sequence of GNodes that are reachable from a starting GNode via a specified axis. An axis step has three parts: an axis, which defines the direction of movement for the step, a node test, which selects GNodes based on their properties, and zero or more predicates which are used to filter the results.]

If the context value for an axis step includes a map or array, this is implicitly converted to a JNode as if by applying the fn:jnode function. If, after this conversion, the sequence contains a value that is not a GNode, a type error is raised [err:XPTY0020]. The result of evaluating the axis step is a sequence of zero or more GNodes.

The axis stepS is equivalent to ./S. Thus, if the context value is a sequence containing multiple GNodes, the semantics of a axis step are equivalent to a path expression in which the step is always applied to a single GNode. The following description therefore explains the semantics for the case where the context value is a single GNode, called the origin.

In the abbreviated syntax for a step, the axis can be omitted and other shorthand notations can be used as described in 4.6.7 Abbreviated Syntax.

The unabbreviated syntax for an axis step consists of the axis name and node test separated by a double colon. The result of the step consists of the GNodes reachable from the origin via the specified axis that match the node test. For example, the step child::para selects the para element children of the origin XNode: child is the name of the axis, and para is the name of the element nodes to be selected on this axis. The available axes are described in 4.6.4.1 Axes. The available node tests are described in 4.6.4.2 Node Tests. Examples of steps are provided in 4.6.6 Unabbreviated Syntax and 4.6.7 Abbreviated Syntax.

4.7.2 Range Expressions

[Definition: A range expression is a non-trivial instance of the production RangeExpr. A range expression is used to construct a sequence of integers.] Each of the operands is converted as though it was an argument of a function with the expected parameter type xs:integer?. If either operand is an empty sequence, or if the integer derived from the first operand is greater than the integer derived from the second operand, the result of the range expression is an empty sequence. If the two operands convert to the same integer, the result of the range expression is that integer. Otherwise, the result is a sequence containing the two integer operands and every integer between the two operands, in increasing order.

The following examples illustrate the semantics:

• 1 to 4 returns the sequence 1, 2, 3, 4

• 10 to 10 returns the singleton sequence 10

• 10 to 1 returns the empty sequence

• -13 to -10 returns the sequence -13, -12, -11, -10

More formally, a range expression is evaluated as follows:

1. Each of the operands of the to operator is converted as though it was an argument of a function with the expected parameter type xs:integer?.

2. If either operand is an empty sequence, or if the integer derived from the first operand is greater than the integer derived from the second operand, the result of the range expression is an empty sequence.

3. If the two operands convert to the same integer, the result of the range expression is that integer.

4. Otherwise, the result is a sequence containing the two integer operands and every integer between the two operands, in increasing order.

The following examples illustrate the use of range expressions.

(10, 1 to 4)

$input[1 to 4]

$x = (1 to 5) ! . * 0.1

10 to 10

15 to 10

reverse(10 to 15)

4.7.3 Combining GNode Sequences

XPath 4.0 provides the following operators for combining sequences of GNodes:

• The union and | operators are equivalent. They take two node sequences as operands and return a sequence containing all the GNodes that occur in either of the operands.

• The intersect operator takes two GNodes sequences as operands and returns a sequence containing all the GNodes that occur in both operands.

• The except operator takes two node sequences as operands and returns a sequence containing all the GNodes that occur in the first operand but not in the second operand.

All these operators eliminate duplicate GNodes from their result sequences based on GNodes identity. The resulting sequence is returned in document order.

If an operand of union, intersect, or except contains an item that is not a GNode, a type error is raised [err:XPTY0004].

If an IntersectExceptExpr contains more than two InstanceofExpr operands, they are evaluated from left to right. With a UnionExpr, it makes no difference how operands are grouped, the results are the same.

The following example demonstrates the use of the except operator with JNodes:

let $m := jtree($map)
for $e in $m/child::* except $m/child::xx 
return ...

In addition to the sequence operators described here, see Section 14 Processing sequences^FO for functions defined on sequences. In addition to the sequence operators described here, see [Functions and Operators 4.0] section 14 Processing sequences for functions defined on sequences. In addition to the sequence operators described here, see [Functions and Operators 4.0] section Section 14 Processing sequencesFO for functions defined on sequences.

4.10.1 Value Comparisons

The value comparison operators are eq, ne, lt, le, gt, and ge. Value comparisons are used for comparing single values.

The first step in evaluating a value comparison is to evaluate its operands. The order in which the operands are evaluated is implementation-dependent. Each operand is evaluated by applying the following steps, in order:

1. Atomization is applied to each operand. The result of this operation is called the atomized operand.

2. If an atomized operand is an empty sequence, the result of the value comparison is an empty sequence, and the implementation need not evaluate the other operand or apply the operator. However, an implementation may choose to evaluate the other operand in order to determine whether it raises an error.

3. If an atomized operand is a sequence of length greater than one, a type error is raised [err:XPTY0004].

4. If an atomized operand is of type xs:untypedAtomic, it is cast to xs:string.

   Note:

   The purpose of this rule is to make value comparisons transitive. Users should be aware that the general comparison operators have a different rule for casting of xs:untypedAtomic operands. Users should also be aware that transitivity of value comparisons may be compromised by loss of precision during type conversion (for example, two xs:integer values that differ slightly may both be considered equal to the same xs:float value because xs:float has less precision than xs:integer).

5. If the two operands are instances of different primitive types (meaning the 19 primitive types defined in Section 3.2 Primitive datatypes^XS2), then: If the two operands are instances of different primitive types (meaning the 19 primitive types defined in 3.2 Primitive datatypes^XS2), then: If the two operands are instances of different primitive types (meaning the 19 primitive types defined in Section 3.2 Primitive datatypes^XS2), then:

   1. If each operand is an instance of one of the types xs:string or xs:anyURI, then both operands are cast to type xs:string.

   2. If each operand is an instance of one of the types xs:decimal or xs:float, then both operands are cast to type xs:float.

   3. If each operand is an instance of one of the types xs:decimal, xs:float, or xs:double, then both operands are cast to type xs:double.

   4. Otherwise, a type error is raised [err:XPTY0004].

      Note:

      The primitive type of an xs:integer value for this purpose is xs:decimal.

6. Expressions using operators other than eq and lt are rewritten as follows:

   A ne B becomes not(A eq B)
A le B becomes A lt B or A eq B
A gt B becomes B lt A
A ge B becomes B lt A or B eq A

7. Finally, if the types of the operands are a valid combination for the given operator, the operator is applied to the operands by applying the appropriate function from the table below.

The definitions of the operator functions are found in [XQuery and XPath Functions and Operators 4.0].

If the table contains no entry corresponding to the types of the operands, after evaluation, then a type error is raised [err:XPTY0004].

Here are some examples of value comparisons:

• The following comparison atomizes the node(s) that are returned by the expression $book/author. The comparison is true only if the result of atomization is the value "Kennedy" as an instance of xs:string or xs:untypedAtomic. If the result of atomization is an empty sequence, the result of the comparison is an empty sequence. If the result of atomization is a sequence containing more than one value, a type error is raised [err:XPTY0004].

  $book1/author eq "Kennedy"

• The following comparison is true because atomization converts an array to its member sequence:

  [ "Kennedy" ] eq "Kennedy"

• The following path expression contains a predicate that selects products whose weight is greater than 100. For any product that does not have a weight subelement, the value of the predicate is the empty sequence, and the product is not selected. This example assumes that weight is a validated element with a numeric type.

  //product[weight gt 100]

• The following comparison is true if my:hatsize and my:shoesize are both user-defined types that are derived by restriction from a primitive numeric type:

  my:hatsize(5) eq my:shoesize(5)

• The following comparison is true. The eq operator compares two QNames by performing codepoint-comparisons of their namespace URIs and their local names, ignoring their namespace prefixes.

  QName("http://example.com/ns1", "this:color") eq
  QName("http://example.com/ns1", "that:color")

4.10.3 GNode Comparisons

GNode comparisons are used to compare two GNodes^DM (that is, XNodes or JNodes^DM), by their identity or by their document order. The result of a GNode comparison is defined by the following rules:

1. The operands of a GNode comparison are evaluated in implementation-dependent order.

2. If either operand is an empty sequence, the result of the comparison is an empty sequence, and the implementation need not evaluate the other operand or apply the operator. However, an implementation may choose to evaluate the other operand in order to determine whether it raises an error.

3. Each operand must be either a single GNode or an empty sequence; otherwise a type error is raised [err:XPTY0004].

4. A comparison with the is operator is true if the values of two operands are the same GNode; otherwise it is false. See [XQuery and XPath Data Model (XDM) 4.0] for the definition of GNode identity.A comparison with the is operator is true if the values of two operands are the same GNode; otherwise it is false. See [XDM 4.0] for the definition of GNode identity.A comparison with the is operator is true if the values of two operands are the same GNode; otherwise it is false. See [XQuery and XPath Data Model (XDM) 4.0][XDM 4.0] for the definition of GNode identity.

5. A comparison with the is-not operator is false if the values of two operands are the same GNode; otherwise it is true. See [XQuery and XPath Data Model (XDM) 4.0] for the definition of GNode identity.A comparison with the is-not operator is false if the values of two operands are the same GNode; otherwise it is true. See [XDM 4.0] for the definition of GNode identity.A comparison with the is-not operator is false if the values of two operands are the same GNode; otherwise it is true. See [XQuery and XPath Data Model (XDM) 4.0][XDM 4.0] for the definition of GNode identity.

6. A comparison with the << or precedes operator returns true if the left operand GNode precedes the right operand GNode in document order; otherwise it returns false.

7. A comparison with the >> or follows operator returns true if the left operand GNode follows the right operand GNode in document order; otherwise it returns false.

Here are some examples of GNode comparisons:

• The following comparison is true only if the left and right sides each evaluate to exactly the same single node:

  /books/book[isbn = "1558604820"] is /books/book[call = "QA76.9 C3845"]

• The following comparison is true only if the node identified by the left side occurs before the node identified by the right side in document order:

  /transactions/purchase[parcel = "28-451"] << /transactions/sale[parcel = "33-870"]

• The following comparison is true only if the first integer among the members of an array precedes the first string. This expression compares two JNodes:

  let $A := ["Q", 3, "E", "R", "T", 5, "Y"]
  return $A ? child::~[xs:integer][1] precedes $A ? child::~[xs:string][1]