XML Path Language (XPath) 4.0 WG Review Draft

2.1.2 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: A node is an instance of one of the node kinds defined in [TITLE OF DM40 SPEC, TITLE OF Node SECTION]^DM40.] Each node has a unique node identity, a typed value, and a string value. In addition, some nodes have a name. The typed value of a node is a sequence of zero or more atomic items. The string value of a node is a value of type xs:string. The name of a node is a value of type xs:QName. [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. [DefinitionDefinition: AAn nodeXNode is an instance of one of the node kinds defined in [TITLE OF DM40 SPEC, TITLE OF Node SECTION]Section 7.1 XML Nodes^DM40DM.] Each nodeXNode has a unique node identity, a typed value, and a string value. In addition, some nodesXNodes have a name. The typed value of a nodean XNode is a sequence of zero or more atomic items. The string value of a nodean XNode is a value of type xs:string. The name of a nodean 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.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]. (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 6.5.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 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 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 6.5.37.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.

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

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 is defined in Section 6.3 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 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.] 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 is defined in Section 6.36.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.]

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

1. The root node is the first nodeprecedes all other nodes.

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

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

4. Every node occurs before all of its children and descendants.

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

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

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

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

8. Children and descendants occur before following siblings.

9. Children and descendants occur before following siblings.

Similarly, within a 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 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 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 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.]

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 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 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, 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 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 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 ¶value property is atomized and the result is returned.

• If the item is a JNode^DM, its ¶value 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 the following types of expressionsmany 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 (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, 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, as defined in Section 8.3.1 fn:boolean^FO.]

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 node, fn:boolean returns true.If its operand is a sequence whose first item is a GNode^DM, fn:boolean returns true.If its operand is a sequence whose first item is a GNode^nodeDM, 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.2.9 Generalized Node Types

A GNodeType matches a generalized node (GNode): that is, it matches any XNode or JNode^DM.

A JNodeType matches a JNode^DM.

The form JNode() matches any JNode. The form JNode(T) matches a JNode whose ¶value is an instance of the sequence type T.

3.2.93.2.10 The type xs:error

The item type xs:error has an empty value space; it never appears as a dynamic type or as the content type of a dynamic element or attribute type. It was defined in XML Schema in the interests of making the type system complete and closed, and it is also available in XPath 4.0 for similar reasons.

3.3.2 Subtypes of Item Types

We use the notation A ⊆ B, or itemtype-subtype(A, B) to indicate that an item typeA is a subtype of an item type B. This section defines the rules for deciding whether any two item types have this relationship.

The rules in this section apply to item types, not to item type designators. For example, if the name STR has been defined in the static context as a named item type referring to the type xs:string, then anything said here about the type xs:string applies equally whether it is designated as xs:string or as STR, or indeed as the parenthesized forms (xs:string) or (STR).

References to named item types are handled as described in 3.3.2.9 Subtyping of Named Item Types.

The relationship A ⊆ B is true if and only if at least one of the conditions listed in the following subsections applies:

3.4.2 Item Coercion Rules

The rules in this section are used to process each item J in a supplied sequence, given a required item typeR.

1. If R is a generalized atomic type (for example, if it is an atomic type, a pure union type, or an enumeration type), and J is not an atomic item, then:

   1. J is atomized to produce a sequence of atomic items JJ.

   2. Each atomic item in JJ is coerced to the required type R by recursive application of the item coercion rules (the rules in this section) to produce a value V.

   3. The result is the sequence-concatenation of the V values.

   Note:

   For example, if J is an element with type annotation xs:integer, and R is the union type xs:numeric, then the effect is to atomize the element to an xs:integer, and then to coerce the resulting xs:integer to xs:numeric (which leaves the integer unchanged). This is not the same as attempting to coerce the element to each of the alternatives of the union type in turn, which would deliver an instance of xs:double.

2. Otherwise, if R is a choice item type or a pure union type (which includes the case where it is an enumeration type), then:

   1. If J matches (is an instance of) one of the alternatives in R, then J is coerced to the first alternative in R that J matches.

      Note:

      There are two situations where coercing an item to a type that it already matches does not simply return the item unchanged:

      • When the required type is a typed function type (see 3.2.8.1 Function Types), then function coercion is applied to coerce J to that function type, as described in 3.4.4 Function Coercion.

      • When the required type is a record type and the supplied value is a map, then coercion may change the entry order^DM of the entries in the map.

   2. Otherwise, the item coercion rules (the rules in this section) are applied to J recursively with R set to each of the alternatives in the choice or union item type, in order, until an alternative is found that does not result in a type error; a type error is raised only if all alternatives fail.

      The error code used in the event of failure should be the error code arising from the first unsuccessful matching attempt. (The diagnostic information associated with the error may also describe how further attempts failed.)

   Note:

   Suppose the required type is (xs:integer | element(e))* and the supplied value is the sequence (<e>22</e>, 23, <f>24</f>). Item coercion is applied independently to each of the three items in this sequence. The first item matches one of the alternatives, namely element(e), so it is returned unchanged as an element node. The second item (the integer 23) also matches one of the alternatives, and is returned unchanged as an integer. The third item does not match any of the alternatives, so coercion is attempted to each one in turn. Coercion to type xs:integer succeeds (by virtue of atomization and untyped atomic conversion), so the final result is the sequence (<e>22</e>, 23, 24)

   Note:

   Suppose the required type is enum("red", "green", "blue") and the supplied value is "green". The enumeration type is defined as a choice item type whose alternatives are singleton enumerations, so the rules are applied first to the type enum("red") (which fails), and then to the type enum("green") (which succeeds). The strings in an enumeration type are required to be distinct so the order of checking is in this case immaterial. The supplied value will be accepted, and will be relabeled as an instance of enum("green"), which is treated as a schema type equivalent to a type derived from xs:string by restriction.

   Note:

   Schema-defined union types behave in exactly the same way as choice item types.

3. If R is an atomic type and J is an atomic item, then:

   1. If J is an instance of R then it is used unchanged.

   2. If J is an instance of type xs:untypedAtomic then:

      1. If R is namespace-sensitive then a type error [err:XPTY0117] is raised.

      2. Otherwise, J is cast to type R.

4. If there is an entry (from, to) in the following table such that J is an instance of from, and to is R, then J is cast to type R.

   Implicit Casting

   from	to
   xs:decimal	xs:double
   xs:double	xs:decimal
   xs:decimal	xs:float
   xs:float	xs:decimal
   xs:float	xs:double
   xs:double	xs:float
   xs:string	xs:anyURI
   xs:anyURI	xs:string
   xs:hexBinary	xs:base64Binary
   xs:base64Binary	xs:hexBinary

   Note:

   The item type in the to column must match R exactly; however, J may belong to a subtype of the type in the from column.

   For example, an xs:NCName will be cast to type xs:anyURI, but an xs:anyURI will not be cast to type xs:NCName.

   Similarly, an xs:integer will be cast to type xs:double, but an xs:double will not be cast to type xs:integer.

5. If R is derived from some primitive atomic type P, then J is relabeled as an instance of R if it satisfies all the following conditions:

   • J is an instance of P.

   • J is not an instance of R.

   • The datum^DM of J is within the value space of R.

   Relabeling an atomic item changes the type annotation but not the datum^DM. For example, the xs:integer value 3 can be relabeled as an instance of xs:unsignedByte, because the datum is within the value space of xs:unsignedByte.

   Note:

   Relabeling is not the same as casting. For example, the xs:decimal value 10.1 can be cast to xs:integer, but it cannot be relabeled as xs:integer, because its datum not within the value space of xs:integer.

   Note:

   The effect of this rule is that if, for example, a function parameter is declared with an expected type of xs:positiveInteger, then a call that supplies the literal value 3 will succeed, whereas a call that supplies -3 will fail.

   This differs from previous versions of this specification, where both these calls would fail.

   This change allows the arguments of existing functions to be defined with a more precise type. For example, the $position argument of array:get could be defined as xs:positiveInteger rather than xs:integer.

   Note:

   If T is a union type with members xs:negativeInteger and xs:positiveInteger and the supplied value is the sequence (20, -20), then the effect of these rules is that the first item 20 is relabeled as type xs:positiveInteger and the second item -20is relabeled as type xs:negativeInteger.

   Note:

   Promotion (for example of xs:float to xs:double) occurs only when T is a primitive type. Relabeling occurs only when T is a derived type. Promotion and relabeling are therefore never combined.

   Note:

   A singleton enumeration type such as enum("green") is treated as an atomic type derived by restriction from xs:string; so if the xs:string value "green" is supplied in a context where the required type is enum("red", "green", "blue"), the value will be accepted and will be relabeled as an instance of enum("green").

6. If J is a JNode^DM and does not match R, then each item in the ¶value of J is coerced to type R by applying the coercion rules recursively.

   Note:

   For example, if $A is an array and the members of the array are maps, then $A?child::* returns a sequence of JNodes that encapsulate maps, and the average size of these maps can be obtained using the expression avg($A?child::* ! map:size(.)). The first argument of map:size does not accept a JNode directly, but it does (in effect) accept a JNode that encapsulates a map.

7. If J is a JNode^DM and does not match R, then each item in the ¶value of J is coerced to type R by applying the coercion rules recursively.

   Note:

   For example, if $A is an array and the members of the array are maps, then $A?child::* returns a sequence of JNodes that encapsulate maps, and the average size of these maps can be obtained using the expression avg($A?child::* ! map:size(.)). The first argument of map:size does not accept a JNode directly, but it does (in effect) accept a JNode that encapsulates a map.

8. If R is an ArrayType other than array(*) and J is an array, then J is converted to a new array by converting each member to the required member type by applying the coercion rules recursively.

   Note:

   For example, if the required type is array(xs:double) and the supplied value is [ 1, 2 ], the array is converted to [ 1e0, 2e0 ].

9. If R is a MapType other than map(*) and J is a map, then J is converted to a new map as follows:

   1. Each key in the supplied map is converted to the required map key type by applying the coercion rules. If the resulting map would contain duplicate keys, a type error is raised [err:XPTY0004].

   2. The corresponding value is converted to the required map value type by applying the coercion rules recursively.

   3. The order of entries in the map remains unchanged.

   Note:

   For example, if the required type is map(xs:string, xs:double) and the supplied value is { "x": 1, "y": 2 }, the map is converted to { "x": 1e0, "y": 2e0 }.

   Note:

   Duplicate keys can occur if the value space of the target type is more restrictive than the original type. For example, an error is raised if the map { 1.2: 0, 1.2000001: 0 }, which contains two keys of type xs:decimal, is coerced to the type map(xs:float, xs:integer).

10. If R is a RecordType and J is a map, then J is converted to a new map as follows:

    1. The keys in the supplied map are unchanged.

    2. In any map entry whose key is equal to the name of one of the field declarations in R (under the rules of the atomic-equal function), the corresponding value is converted to the required type defined by that field declaration, by applying the coercion rules recursively (but with XPath 1.0 compatibility mode treated as false).

    3. The order of entries in the map is changed: entries whose keys correspond to the names of field declarations in R appear first, in the order of the corresponding field declarations, and (if the record type is extensible) other entries then follow retaining their relative order in J.

    Note:

    For example, if the required type is record(longitude as xs:double, latitude as xs:double) and the supplied value is { "latitude": 53.2, "longitude": 0 }, then the map is converted to { "longitude": 0.0e0, "latitude": 53.2e0 }.

11. If R is a TypedFunctionType and J is a function item, then function coercion is applied to J.

    Note:

    Function coercion applies even if J is already an instance of R.

    Maps and arrays are functions, so function coercion applies to them as well.

12. If, after the above conversions, the resulting item does not match the expected item type R according to the rules for SequenceType Matching, a type error is raised [err:XPTY0004].

    Note:

    Under the general rules for type errors (see 2.4.1 Kinds of Errors), a processor may report a type error during static analysis if it will necessarily occur when the expression is evaluated. For example, the function call fn:abs("beer") will necessarily fail when evaluated, because the function requires a numeric value as its argument; this may be detected and reported as a static error.

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 7.1 Function Items^DM): 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 Section 7.18.1 Function Items^DM):

   • 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.3 Dynamic Function Calls

[Definition: A dynamic function call consists of a base expression that returns the function and a parenthesized list of zero or more arguments (argument expressions or ArgumentPlaceholders).]

A dynamic function call is evaluated as described in 4.5.3.1 Evaluating Dynamic Function Calls.

The following are examples of some dynamic function calls:

• This example calls the function contained in $f, passing the arguments 2 and 3:

  $f(2, 3)

• This example fetches the second item from sequence $f, treats it as a function and calls it, passing an xs:string argument:

  $f[2]("Hi there")

• This example calls the function $f passing no arguments, and filters the result with a positional predicate:

  $f()[2]

let $incr := 1
let $f := function($i as xs:decimal) as xs:decimal { $i + $incr }
return $f(5)

let $vat := function() { @vat + @price }
return doc('wares.xml')/shop/article/$vat()

let $vat := function($art) { $art/@vat + $art/@price }
return doc('wares.xml')/shop/article/$vat(.)

let $ctx := doc('wares.xml')/shop/article
let $vat := function() { for $a in $ctx return $a/@vat + $a/@price }
return $vat()

let $vat := function { @vat + @price }
return $vat(doc('wares.xml')/shop/article)

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 reference fn: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 7.1 Function Items^DM): 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 Section 7.18.1 Function Items^DM):

   • 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 7.1 Function Items^DM): 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 Section 7.18.1 Function Items^DM):

   • 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 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 7.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 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 Section 7.18.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.

  • 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, when evaluated, creates an anonymous function defined directly in the inline function expression.] An inline function expression specifies the names and SequenceTypes of the parameters to the function, the SequenceType 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.2 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 annotation keyword %method is described in 4.5.6.1 Methods.

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 7.1 Function Items^DM):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 Section 7.18.1 Function Items^DM):

• 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: If the keyword %method is present, then a list containing a single annotation whose name is a QName with local name "method" and namespace "http://www.w3.org/2012/xquery" and whose value is an empty sequence; otherwise an empty set..

• 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 Steps

[Definition: A step is a part of a path expression that generates a sequence of items and then filters the sequence by zero or more predicates. The value of the step consists of those items that satisfy the predicates, working from left to right. A step may be either an axis step or a postfix expression.] Postfix expressions are described in 4.3 Postfix Expressions.

[Definition: An axis step returns a sequence of nodes that are reachable from a starting node via a specified axis. Such a step has two parts: an axis, which defines the "direction of movement" for the step, and a node test, which selects nodes based on their kind, name, and/or type annotation .]

If the context value is a sequence of zero or more nodes, an axis step returns a sequence of zero or more nodes; otherwise, a type error is raised [err:XPTY0020].

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

An axis step may be either a forward step or a reverse step, followed by zero or more predicates.

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 nodes reachable from the starting node via the specified axis that have the node kind, name, and/or type annotation specified by the node test. For example, the step child::para selects the para element children of the context node: 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.3 Combining NodeGNode Sequences

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

• The union and | operators are equivalent. They take two node sequences as operands and return a sequence containing all the nodes that occur in either of the operands.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 union and | operators are equivalent. They take two node sequences as operands and return a sequence containing all the nodesGNodes that occur in either of the operands.

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

• The except operator takes two node sequences as operands and returns a sequence containing all the nodes that occur in the first operand but not in the second operand.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.The except operator takes two node sequences as operands and returns a sequence containing all the nodesGNodes that occur in the first operand but not in the second operand.

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

If an operand of union, intersect, or except contains an item that is not a node, a type error is raised [err:XPTY0004].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 operand of union, intersect, or except contains an item that is not a nodeGNode, a type error is raised [err:XPTY0004].

If an IntersectExceptExpr contains more than two InstanceofExprs, they are grouped from left to right. With a UnionExpr, it makes no difference how operands are grouped, the results are the same. If an IntersectExceptExpr contains more than two InstanceofExprs, they are grouped from left to right. With a UnionExpr, it makes no difference how operands are grouped, the results are the same. If an IntersectExceptExpr contains more than two InstanceofExprsInstanceofExprs, they are grouped 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 := JNode($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.

4.10.3 NodeGNode Comparisons

Node comparisons are used to compare two nodes, by their identity or by their document order. The result of a node comparison is defined by the following rules: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:NodeGNode comparisons are used to compare two GNodes^nodesDM (that is, XNodes or JNodes^DM), by their identity or by their document order. The result of a nodeGNode comparison is defined by the following rules:

1. The operands of a nodeGNode 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 nodeGNode or an empty sequence; otherwise a type error is raised [err:XPTY0004].

4. A comparison with the is operator is true if the two operand nodes are the same node; otherwise it is false. See [XQuery and XPath Data Model (XDM) 4.0] for the definition of node 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] for the definition of GNode identity.A comparison with the is operator is true if the two operand nodesvalues of two operands are the same nodeGNode; otherwise it is false. See [XQuery and XPath Data Model (XDM) 4.0] for the definition of nodeGNode identity.

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

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

Here are some examples of nodeGNode 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] << $A ? child::~[xs:string][1]

• 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] << $A ? child::~[xs:string][1]

4.13.1 Maps

[Definition: A map is a function that associates a set of keys with values, resulting in a collection of key / value pairs.] [Definition: Each key / value pair in a map is called an entry.] [Definition: The value associated with a given key is called the associated value of the key.]

Maps and their properties are defined in the data model: see Section 7.2 Map Items^DM. For an overview of the functions available for processing maps, see Section 18 Processing maps^FO.Maps and their properties are defined in the data model: see Section 8.2 Map Items^DM. For an overview of the functions available for processing maps, see Section 18 Processing maps^FO.Maps and their properties are defined in the data model: see Section 7.28.2 Map Items^DM. For an overview of the functions available for processing maps, see Section 18 Processing maps^FO.

4.13.3 Lookup Expressions

XPath 4.0 provides two lookup operators ? and ?? for maps and arrays. These provide a terse syntax for accessing the entries in a map or the members of an array.

The operator "?", known as the shallow lookup operator, returns values found immediately in the operand map or array. The operator "??", known as the deep lookup operator, also searches nested maps and arrays. The effect of the deep lookup operator "??" is explained in 4.13.3.3 Deep Lookup.

("a", "b", "c", "d", "e", "f", 42)

({ "key": 1, "value": ("a", "b") }, 
 { "key": 2, "value": ("c", "d") }, 
 { "key": 3, "value": ("e", "f") },
 { "key": 4, "value": 42 })

([ "a", "b" ], [ "c", "d" ], [ "e", "f" ], [42])

(1, 2, 3, 4)

("c", "d")

({ "key": 2, "value":("c", "d") })

([ "c", "d" ])

(2)

("e", "f", "a", "b")

({ "key": 3, "value": ("e", "f") }, 
 { "key": 1, "value": ("a", "b") })

([ "e", "f" ][ "a", "b" ])

(3, 1)

42

4

(1, 2, 3)

("a", "b", "c", "d", "e", "f", 42)

({ "key": "X", "value": ("a", "b") }, 
 { "key": "Y", "value": ("c", "d") }, 
 { "key": "Z", "value": ("e", "f") },
 { "key": "N", "value": 42 })

([ "a", "b" ], [ "c", "d" ], [ "e", "f" ], [42])

("X", "Y", "Z", "N")

("c", "d")

({ "key": "Y", "value":("c", "d") })

([ "c", "d" ])

("Y")

("e", "f", "a", "b")

({ "key": "Z", "value": ("e", "f") }, 
 { "key": "X", "value": ("a", "b") })

([ "e", "f" ][ "a", "b" ])

("Z", "X")

42

"N"

("X", "Y", "Z")

[ { "John": 3, "Jill": 5}, {"Peter": 8, "Mary": 6} ]