View source for XPath Expressions Module

__NUMBEREDHEADINGS__
{{TR|title=XForms 2.0: XPath expression module}}
<div id='editors'>
; Editor:
: Nick Van den Bleeken, Inventive Designers
: John M. Boyer, IBM
</div>

<div style="font-weight:bold;">Abstract</div>
<div id='abstract'>This module defines how XPath is used for addressing instance data nodes in binding expressions, to express constraints, and to specify calculations in XForms. This module is based on XPath 2.0, but an XPath 1.0 backwards compatibility mode is provided to ensure that nearly all XPath 1.0 expressions continue to produce the same result with XPath 2.0.

This module also defines the XForms Function Library which contains additional functions that are useful for creating forms.

</div>

<div style="font-weight:bold;">Status of this Document</div>
<div>{{status|xforms-xpath}}</div>

[http://www.w3.org/Consortium/Legal/ipr-notice#Copyright Copyright] &copy; 2010 [http://www.w3.org/ W3C]<sup>&reg;</sup> ([http://www.csail.mit.edu/ MIT], [http://www.ercim.org/ ERCIM], [http://www.keio.ac.jp/ Keio]), All Rights Reserved. W3C [http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer liability], [http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks trademark] and [http://www.w3.org/Consortium/Legal/copyright-documents document use] rules apply.

<div id='docbody'>
<div class="body"><div class="div1">

== About the XForms 2.0: XPath expression module ==

<div class="div2">

=== Introduction ===

This document is a module designed to add support for XPath as an expression language in XForms. XPath 2.0 is an expression language to address the nodes of [[#ref-xml-1.0| [XML 1.0]]] or [[#ref-xml-1.1| [XML 1.1]]] trees defined by W3C. It includes over 100 built-in functions, including operations on node-sets, strings, numbers, booleans, dates, and durations.

Besides defining how XPath can be used as an expression language in XForms this document also defines the XForms Function Library. The XForms Function Library contains additional functions that are useful for creating forms.

</div><div class="div2">

=== <span id="intro-reading">Reading the Specification</span> ===

This specification has been written with various types of readers in mind—in particular XForms authors and XForms implementors. Implementors, however, should find all they need to add XPath 2.0 support to their XForms Processors. The specification begins with a general presentation of how XPath 2.0 expressions will be used in XForms before specifying the technical details of how to integrate XPath 2.0 in XForms. Finally it defines the XForms Function Library.

The specification has been written with various modes of presentation in mind. In case of a discrepancy, the online electronic version is considered the authoritative version of the document.

With regard to implementing behaviors defined for XForms content herein, this document uses the terms '''must''', '''must not''', '''required''', '''shall''', '''shall not''', '''recommended''', '''should''', '''should not''', '''may''', and '''optional''' in accord with [[#ref-rfc-2119| [RFC 2119]]]. Generally, the elements, attributes, functions and behaviors of XForms content defined in this specification are required to implement unless explicitly specified otherwise. The term '''author-optional''', when applied to a content item such as an element, attribute, or function parameter, indicates to form authors that they may omit the content item and obtain the default behavior. The term author-optional is orthogonal to the conformance status (required, recommended, or optional) of the content item.

</div><div class="div2">

=== How the Specification is Organized ===

The specification is organized into the following chapters:

; Chapters 1
: An introduction to XPath as an expression language in XForms. The introduction and example usages of XPath expressions in XForms.
; Chapter 2
: Definition of the '''xpath-version''' attribute.
; Chapter 3
: Contains all the information on how XPath is integrated into XForms. This section is mostly targeted at XForms implementors.
; Chapter 4
: Defines the XForms Function library which defines additional functions that are useful for creating forms.

</div><div class="div2">

=== Documentation Conventions ===

Throughout this document, the following namespace prefixes and corresponding namespace identifiers are used:

<blockquote>

'''xforms:''' The XForms namespace, e.g. <code>http://www.w3.org/2002/xforms</code> (see [[XForms_2.0#structure-namespace|Namespace for XForms]]<sup><small>XF</small></sup>)<br />'''xf:''' The XForms namespace, e.g. <code>http://www.w3.org/2002/xforms</code> (see [[XForms_2.0#structure-namespace|Namespace for XForms]]<sup><small>XF</small></sup>)<br />'''html:''' An XHTML namespace, e.g. <code>http://www.w3.org/1999/xhtml</code> (see [[#ref-xhtml-1.0| [XHTML 1.0]]])<br />'''xs:''' The XML Schema namespace <code>http://www.w3.org/2001/XMLSchema</code> (see [[#ref-xschema-1| [XML Schema part 1]]])<br />'''xsd:''' The XML Schema namespace <code>http://www.w3.org/2001/XMLSchema</code> (see [[#ref-xschema-2| [XML Schema part 2]]])<br />'''xsi:''' The XML Schema for instances namespace <code>http://www.w3.org/2001/XMLSchema-instance</code> (see [[#ref-xschema-1| [XML Schema part 1]]])<br />'''ev:''' The XML Events namespace <code>http://www.w3.org/2001/xml-events</code> (see [[#ref-xml-events| [XML Events]]])<br />'''fn:''' The XPath function namespace <code>http://www.w3.org/2005/xpath-functions</code> (see [[#ref-xpath-functions| [Functions and Operators]]])<br />'''my:''' Any user defined namespace

</blockquote>

This is only a convention; any namespace prefix may be used in practice.

The following typographical conventions are used to present technical material in this document.

Official terms are defined in the following manner: [Definition<nowiki>: You can find most </nowiki>'''terms''' in chapter [[#terms| '''6 Glossary Of Terms''']]]. Links to '''term'''s may be specially highlighted where necessary.

The XML representations of various elements within XForms are presented using the syntax for Abstract Modules in XHTML Modularization [[#ref-xhtml-mod| [XHTML Modularization]]].

Examples are set off typographically:

<div class="exampleOuter"><div class="exampleHead">Example item</div><div class="exampleInner">

 Example Item

</div></div>

References to external documents appear as follows: [[#ref-example| [Sample Reference]]] with links to the references section of this document.

; Sample Reference
: <cite id="ref-example">Reference</cite> - linked to from above.

The following typesetting convention is used for additional commentary:

<div class="note">

'''Note:'''

A gentle explanation to readers.

</div>

{| summary="Editorial note: Editorial Note Name" border="1"
| width="50%" align="left" valign="top" | '''Editorial note: Editorial Note Name'''
| width="50%" align="right" valign="top" |
|-
| colspan="2" align="left" valign="top" | Editorial commentary, not intended for final publication.
|}

<div class="issue">

'''Issue (sample-implementation-issue):'''

'''Issue-Name'''

A specific issue for which input from implementors is requested, for example as part of the Candidate Recommendation phase.

'''Resolution:'''

None recorded.

</div></div><div class="div2">

=== Examples ===

The following example binds an input control to an instance data node:

<div class="exampleOuter"><div class="exampleHead">Input control bound to an instance data node</div><div class="exampleInner">

 <input ref="order/shipTo/street" class="streetAddress">
   <label>Street</label>
   <hint>Please enter the number and street name</hint>
 </input>

</div></div>

The following example outputs the total value of an order by calculating the sum of the price of all line totals in the order. The line total is calculated by multiplying the item price with number of items ordered:

<div class="exampleOuter"><div class="exampleHead">XPath expression in output control</div><div class="exampleInner">

 I charged you <output value="sum(for $i in order/order-item return $i/@price * $i/@qty)"/>

</div></div></div></div><div class="div1">

== <span id="xpath-version-attribute">The <code>xpath-version</code> attribute</span> ==

This module adds the <code>xpath-version</code> attribute to the XForms <code>model</code> element. The <code>xpath-version</code> attribute is used to switch on or off XPath 1.0 backwards compatibility mode. XPath 1.0 backwards compatibility mode ensures that nearly all XPath 1.0 expressions continue to deliver the same result with XPath 2.0.

; xpath-version
: Author-optional attribute used by the XForms processor to determine the XPath version that will be used to evaluate XPath expressions. The supported values are 1.0 and 2.0. For the default model the default value is :
:* 1.0 if the XForms conformance level is 1.0 or 1.1 (see [[XForms_2.0#The_model_Element|The model element]]<sup><small>XF</small></sup> for more information about the XForms conformance level)
:* 2.0 for all other XForms conformance levels.
:
: For all non-default models the default value is the xpath-version of the default model. When an XForms processor doesn't supports the requested XPath version or any non-default model has a version setting that is incompatible with the XPath version selected by the XForms Processor, the XForms Processor must terminate processing after dispatching the event [[#evt-xpathVersionException| xforms-xpath-version-exception]] to the default <code>model</code>.

If XPath 1.0 compatibility mode is requested, an XForms processor may use either an XPath 1.0 implementation [[#ref-xpath-1.0| [XPath 1.0]]] or an XPath 2.0 implementation in XPath 1.0 compatibility mode [[#ref-xpath-2.0| [XPath 2.0]]]. If the XPath 1.0 engine can't evaluate an expression (as there are XPath 2.0 expressions which can't be executed with an XPath 1.0 engine, and some functions defined in [[#ref-xpath-functions| [Functions and Operators]]] may be unavailable to an XPath 1.0 engine) an [[XForms_2.0#evt-expressionError|xforms-expression-error Event]]<sup><small>XF</small></sup>, [[XForms_2.0#evt-bindingError|xforms-binding-error Event]]<sup><small>XF</small></sup>, or [[XForms_2.0#evt-actionError|xforms-action-error Event]]<sup><small>XF</small></sup> is dispatched.

<div class="note">

'''Note:'''

XPath 1.0 only supports atomic values and node sets, and does not support sequences.

If an XPath 1.0 engine is used, the function signature components that accept or return:

* A sequences atomic values are to be interpreted as accepting or returning a single atomic value
* A sequence of items, nodes or elements are to be interpreted as accepting or returning a node-set

</div></div><div class="div1">

== XPath Expressions in XForms ==

This module uses XPath to address [[XForms_2.0#def-instance-data-node|instance data node]]<sup><small>XF</small></sup>s in binding expressions, to express constraints, and to specify calculations. XPath expressions in XForms are based on [[#ref-xpath-2.0| [XPath 2.0]]]. At the time of evaluation, an XPath expression must be syntactically correct. In addition, the namespaces the expression references must be in scope and the functions and variables it references must be defined.

If any of these conditions is not satisfied, an error is raised depending on the location of the expression: [[XForms_2.0#evt-expressionError|xforms-expression-error Event]]<sup><small>XF</small></sup>, [[XForms_2.0#evt-bindingError|xforms-binding-error Event]]<sup><small>XF</small></sup>, or [[XForms_2.0#evt-actionError|xforms-action-error Event]]<sup><small>XF</small></sup>. The following extra context information is made available to any of these events:

{| summary="Additional event context information for xforms-expression-error, xforms-binding-error and xforms-action-error" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Type
! rowspan="1" colspan="1" | Value
|-
| rowspan="1" colspan="1" | xpath-error
| rowspan="1" colspan="1" | xs:QName?
| rowspan="1" colspan="1" | [[#ref-xpath-2.0| [XPath 2.0]]] error identifier if available, otherwise the empty sequence.
|-
| rowspan="1" colspan="1" | xpath-error-items
| rowspan="1" colspan="1" | item()*
| rowspan="1" colspan="1" | XPath diagnostic values if available, otherwise the empty sequence.
|}

<div class="div2">

=== Evaluation Context ===

This module extends the [[XForms_2.0#Evaluation_Context|evaluation context]]<sup><small>XF</small></sup>, with all the additional properties that are defined in the XPath [http://www.w3.org/TR/xpath20/#dt-expression-context expression context]<sup><small>XP</small></sup>. The expression context has two parts, the [http://www.w3.org/TR/xpath20/#dt-static-context static context]<sup><small>XF</small></sup>, and the [http://www.w3.org/TR/xpath20/#dt-dynamic-context dynamic context]<sup><small>XF</small></sup>. The components that make up the expression context are defined in the XPath specification (see [http://www.w3.org/TR/xpath20/#context Section 2.1 Expression Context]<sup><small>XF</small></sup>). This section describes the way in which these components are initialized when an XPath expression is contained within a Form. The term containing element means in these sections the element within the form that is the parent of the attribute whose value contains the XPath expression in question.

The following two sections describe:

* [[#expr-static-context|Initializing the Static Context]]
* [[#expr-dynamic-context|Initializing the Dynamic Context]]

<div class="div3">

==== <span id="expr-static-context">Initializing the Static Context</span> ====

The [http://www.w3.org/TR/xpath20/#dt-static-context static context]<sup><small>XP</small></sup> of an XPath expression appearing in a form is initialized as follows.

* [http://www.w3.org/TR/xpath20/#dt-xpath-compat-mode XPath 1.0 compatibility mode]<sup><small>XP</small></sup> is set to true if and only if the indicated XPath version on the model is 1.0 or the XForms conformance level is 1.0 or 1.1.
* The [http://www.w3.org/TR/xpath20/#dt-static-namespaces statically known namespaces]<sup><small>XP</small></sup> are the namespace declarations that are in scope for the containing element.
* The [http://www.w3.org/TR/xpath20/#dt-def-elemtype-ns default element/type namespace]<sup><small>XP</small></sup> is the null namespace.
* The [http://www.w3.org/TR/xpath20/#dt-def-fn-ns default function namespace]<sup><small>XP</small></sup> is the standard function namespace, defined in [[#ref-xpath-functions| [Functions and Operators]]]. This means that it is not necessary to declare this namespace in the form, nor is it necessary to use the prefix fn (or any other prefix) in calls to the core XPath functions.
* The [http://www.w3.org/TR/xpath20/#dt-issd in-scope schema definitions]<sup><small>XP</small></sup> for the XPath expression are as specified in [[XForms_2.0#Datatypes|Datatypes]]<sup><small>XF</small></sup>.
* The [http://www.w3.org/TR/xpath20/#dt-in-scope-variables in-scope variables]<sup><small>XP</small></sup>  are defined by the variable binding elements that are in scope for the containing element (see [[XForms_2.0#structure-var-element|The var element]]).
* The [http://www.w3.org/TR/xpath20/#dt-function-signature function signatures]<sup><small>XP</small></sup> are the core functions defined in [[#ref-xpath-functions| [Functions and Operators]]], the constructor functions for all the atomic types in the [http://www.w3.org/TR/xpath20/#dt-issd in-scope schema definitions]<sup><small>XP</small></sup>, the additional functions defined in this specification, the custom functions defined in the Form, plus any extension functions bound using implementation-defined mechanisms.
* The [http://www.w3.org/TR/xpath20/#dt-static-collations statically known collations]<sup><small>XP</small></sup> are implementation-defined. However, the set of in-scope collations must always include the Unicode codepoint collation, defined in [http://www.w3.org/TR/xpath-functions/#string-compare 7.3 Equality and Comparison of Strings]<sup><small>FO</small></sup>.
* The [http://www.w3.org/TR/xpath20/#dt-def-collation default collation]<sup><small>XP</small></sup> is the Unicode code point collation.
* The [http://www.w3.org/TR/xpath20/#dt-base-uri base URI]<sup><small>XP</small></sup> is the base URI of the containing element. The concept of the base URI of a node is defined in [http://www.w3.org/TR/xpath-datamodel/#dm-base-uri Section 5.2 base-uri Accessor]<sup><small>DM</small></sup>

</div><div class="div3">

==== <span id="expr-dynamic-context">Initializing the Dynamic Context</span> ====

For convenience, the dynamic context is described in two parts: the focus, which represents the place in the instance document that is currently being referenced, and a collection of additional context variables.

A number of functions specified in [[#ref-xpath-functions| [Functions and Operators]]] are defined to be [http://www.w3.org/TR/xpath-functions/#stable stable]<sup><small>FO</small></sup>, meaning that if they are called twice during the same [http://www.w3.org/TR/xpath-functions/#execution-scope execution scope]<sup><small>FO</small></sup>, with the same arguments, then they return the same results (see [http://www.w3.org/TR/xpath-functions/#terminology "Section 1.7 Terminology]<sup><small>FO</small></sup>). XForms currently does not rigorously define what the same execution scope means, and leave it up to the implementor to choose when a new execution scope starts. This means, for example, that if the function [http://www.w3.org/TR/xpath-functions/#func-current-dateTime current-dateTime]<sup><small>FO</small></sup> is called repeatedly in a form, the interval for which it produces the same result is implementation defined. The focus is not stable.

{{SpecNote|We are waiting for further implementation experience and user feedback to define what the same execution scope means for XForms.}}

<div class="div4">

===== Other components of the XPath Dynamic Context =====

The Core XForms specification explained how the focus for an XPath expression appearing in a Form is initialized. This section explains how the other components of the [http://www.w3.org/TR/xpath20/#dt-dynamic-context dynamic context]<sup><small>XP</small></sup> of an XPath expression are initialized.

* The [http://www.w3.org/TR/xpath20/#dt-variable-values dynamic variables]<sup><small>XP</small></sup> are the current values of the in-scope variable binding elements.
* The current date and time represents an implementation-dependent point in time during processing of an expression.
* The implicit [http://www.w3.org/TR/xpath20/#dt-timezone timezone]<sup><small>XP</small></sup> is implementation-defined.
* The [http://www.w3.org/TR/xpath20/#dt-known-docs available documents]<sup><small>XP</small></sup>, and the available [http://www.w3.org/TR/xpath20/#dt-known-collections collections]<sup><small>XP</small></sup> are implementation-defined.
* The [http://www.w3.org/TR/xpath20/#dt-default-collection default collection]<sup><small>XP</small></sup> is implementation-defined. This allows options such as setting the default collection to be an empty sequence, or to be undefined.

</div></div></div><div class="div2">

=== Item type conversions ===

When the result of an expression needs to be converted to a built-in atomic type we will use the XPath constructor functions to do the conversion:

* If the expected type is <code>xs:string</code> or <code>xs:string?</code>, then the argument is converted to a string as if by a call to the <code>fn:string</code> function
* If the expected type is <code>xs:boolean</code> or <code>xs:boolean?</code>, then the argument is converted to a boolean as if by a call to the <code>fn:boolean</code> function

</div></div><div class="div1">

== <span id="expr-lib">The XForms Function Library</span> ==

In addition to the standard XPath functions defined by [[#ref-xpath-functions| [Functions and Operators]]], XForms defines a library of XPath functions called the XForms Function Library.

Functions which are part of the XForms Function Library are available in one more more namespaces, according to the following table:

{| summary="Namespace of functions in the XForms Function Library" border="1"
|rowspan="2"|
!colspan="2"| Selected XPath version
|-
! XPath 1.0
! XPath 2.0
|-
| [[XForms_2.0#structure-namespace|XForms namespace]]<sup><small>XF</small></sup>
| must be available
| must be available
|-
| [http://www.w3.org/TR/xpath20/#dt-def-fn-ns default function namespace]<sup><small>XP</small></sup>
| must be available
| may be available for backward compatibility
|}

{{SpecNote|Future XForms versions may deprecate exposing functions from the XForms Function Library in the [http://www.w3.org/TR/xpath20/#dt-def-fn-ns default function namespace]<sup><small>XP</small></sup>.}}

The function library provided by an XForms processor may also contain other extension functions as described in [[XForms_2.0#Extension_Functions|Extension Functions]]<sup><small>XF</small></sup>.

<div class="div2">

=== <span id="expr-lib-error-handling">Error Handling</span> ===

If an error occurs in an XPath function, then an [[XForms_2.0#evt-expressionError|xforms-expression-error Event]]<sup><small>XF</small></sup>, [[XForms_2.0#evt-bindingError|xforms-binding-error Event]]<sup><small>XF</small></sup>, or [[XForms_2.0#evt-actionError|xforms-action-error Event]]<sup><small>XF</small></sup> is dispatched.

</div>

<div class="div2">

=== <span id="expr-lib-bool">Boolean Functions</span> ===

<div class="div3">

==== <span id="fn-boolean-from-string">The boolean-from-string() Function</span> ====

<code class="function">xf:boolean-from-string</code>(<code class="arg">$value</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:boolean</code>

Function <code>boolean-from-string</code> returns <code>true</code> if the required parameter matches "true" or "1" using case-insensitive comparison. Otherwise <code>false</code> is returned. This function is useful when referencing a Schema <code>xsd:boolean</code> datatype in an XPath expression.

</div>

<div class="div3">

==== <span id="fn-is-card-number">The is-card-number() Function</span> ====

<code class="function">xf:is-card-number</code>(<code class="arg">$card-nr</code><code class="as"> as </code><code class="type">xs:string?</code>)<code class="as"> as </code><code class="return-type">xs:boolean</code>

If the string parameter conforms to the pattern restriction of the [[XForms_2.0#dt-card-number|xforms:card-number]]<sup><small>XF</small></sup> datatype, then this function applies the <code>Luhn</code> algorithm described in [[#ref-luhn| [Luhn Patent]]] and returns true if the number satisfies the formula. Otherwise, false is returned. If the parameter is omitted, it defaults to the string-value of the current context item.

Examples (see also [[XForms_2.0#dt-card-number|xforms:card-number]]<sup><small>XF</small></sup>):

<div class="exampleOuter"><div class="exampleInner">

 xf:is-card-number(.)

</div>

returns <code>true</code> if and only if the string-value of the context item is a string of zero or more digits and satisfies the formula.

<div class="exampleInner">

 xf:is-card-number('4111111111111111')

</div>

returns <code>true</code>. Other examples of string constants that will return <code>true</code> are : <code>5431111111111111</code>, <code>341111111111111</code> and <code>6011601160116611</code>.

<div class="exampleInner">

 xf:is-card-number('123')

</div>

returns <code>false</code>.

</div>

</div>

<div class="div3">

==== <span id="fn-valid">The valid() Function</span> ====

<code class="function">xf:valid() as xs:boolean</code>

<code class="function">xf:valid($items as item()*) as xs:boolean</code>

<code class="function">xf:valid($items as item()*, $relevant as xs:boolean) as xs:boolean</code>

<code class="function">xf:valid($items as item()*, $relevant as xs:boolean, $recurse as xs:boolean) as xs:boolean</code>

The <code>valid()</code> function returns the validity of XPath items, including instance data nodes.

The function acts as if first selecting items in this sequence:

# Selected items initially consist of each item referred to by the <code>$items</code> parameter, if present, or the expression's context item, if absent.
# If the <code>$recurse</code> attribute is omitted or set to <code>true()</code>, all nodes (including attribute nodes) for which a selected item is an ancestor node are also selected.
# If the <code>$relevant</code> attribute is omitted or set to <code>true()</code>, selected items which are non-relevant are deselected. The relevance information of an individual node is obtained by looking at the node's relevant property computed as per [[XForms_2.0#evt-recalculate|The xforms-recalculate Event]]<sup><small>XF</small></sup>. The relevance information of an XPath atomic value is always <code>true()</code>.

If there are no resulting selected items, the function returns <code>true()</code>.

Otherwise the function computes the logical AND of the validity of all the selected items. The validity information of an individual node is obtained by looking at the node validity computed as per [[XForms_2.0#evt-revalidate|The xforms-revalidate Event]]<sup><small>XF</small></sup>. The validity information of an XPath atomic value is always <code>true()</code>.

If the function is used in a [[XForms_2.0#def-model-binding-expression|model binding expression]]<sup><small>XF</small></sup> the XForms Processor should dispatch the event [[XForms_2.0#evt-bindingError|xforms-binding-error Event]]<sup><small>XF</small></sup> to the model. If the function is used in a [[XForms_2.0#def-computed-expression|computed expression]]<sup><small>XF</small></sup> the XForms Processor should dispatch the event [[XForms_2.0#evt-expressionError|xforms-expression-error Event]]<sup><small>XF</small></sup> to the model.

<div class="note">

'''Note:'''

The validity of a node might appear to be out of date by the time the <code>valid()</code> function is used if changes have been made to instance data between the time <code>xforms-recalculate</code> and/or <code>xforms-revalidate</code> processing occur and the time the function is called. This function must therefore be used with caution. Examples of safe use include:

* In binding expressions, value expressions, and itemset expressions on form controls.
* In action handlers responding to events dispatched to form controls, provided instance data has not changed since the time the default action for <code>xforms-refresh</code> has started.

Similarly, the reason for discouraging the use of the <code>valid()</code> function within binds is that it can easily return unexpected results. For example <code>relevant="valid(../value)"</code> will usually fail to produce the expected result as the <code>relevant</code> property is computed before revalidation happens.

</div>

<div class="exampleOuter">

<div class="exampleInner">

<pre><nowiki>
<model>
  <instance>
    <data xmlns="">
      <node1/>
      <node2/>
    </data>
  </instance>
  <bind ref="*" type="xs:integer"/>
</model>
<repeat ref="*[not(valid())]">
  <output value=".">
    <label>Invalid value:</label>
  </output>
</repeat>
</nowiki></pre>

</div>

The <code>repeat</code> above generates an <code>output</code> to show the value of each data node that is not valid according to XForms model validation processing.

</div>

</div>

<div class="div3">

==== <span id="fn-relevant">The relevant() Function</span> ====

<code class="function">xf:relevant() as xs:boolean</code>

<code class="function">xf:relevant($items as item()*) as xs:boolean</code>

The <code>relevant()</code> function returns the relevance of XPath items, including instance data nodes.

Selected items consist of each item referred to by the <code>$items</code> parameter, if present, or the expression's context item, if absent.

If there are no resulting selected items, the function returns <code>true()</code>.

Otherwise the function computes the logical AND of the relevance of all the selected items.

The relevance information of an individual node is obtained by looking at the node's relevant property computed as per
[[XForms_2.0#evt-recalculate|The xforms-recalculate Event]]<sup><small>XF</small></sup>, including inheritance. The relevance information of an XPath atomic value is always <code>true()</code>.

If the function is used in a [[XForms_2.0#def-model-binding-expression|model binding expression]]<sup><small>XF</small></sup> the XForms Processor should dispatch the event [[XForms_2.0#evt-bindingError|xforms-binding-error Event]]<sup><small>XF</small></sup> to the model. If the function is used in a [[XForms_2.0#def-computed-expression|computed expression]]<sup><small>XF</small></sup> the XForms Processor should dispatch the event [[XForms_2.0#evt-expressionError|xforms-expression-error Event]]<sup><small>XF</small></sup> to the model.

<div class="note">

'''Note:'''

Similarly to the <code>valid()</code> function, the relevance of a node might appear to be out of date by the time the <code>relevant()</code> function is used if
changes have been made to instance data between the time <code>xforms-recalculate</code> and/or <code>xforms-revalidate</code>
processing occur and the time the function is called. This function must therefore be used with caution.

</div>

</div>

<div class="div3">

==== <span id="fn-readonly">The readonly() Function</span> ====

<code class="function">xf:readonly() as xs:boolean</code>

<code class="function">xf:readonly($items as item()*) as xs:boolean</code>

The <code>readonly()</code> function returns the readonly property of XPath items, including instance data nodes.

Selected items consist of each item referred to by the <code>$items</code> parameter, if present, or the expression's context item, if absent.

If there are no resulting selected items, the function returns <code>false()</code>.

Otherwise the function computes the logical OR of the readonly property of all the selected items.

The readonly property information of an individual node is obtained by looking at the node's readonly property computed as per
[[XForms_2.0#evt-recalculate|The xforms-recalculate Event]]<sup><small>XF</small></sup>, including inheritance. The readonly information of an XPath atomic value is always <code>true()</code>.

If the function is used in a [[XForms_2.0#def-model-binding-expression|model binding expression]]<sup><small>XF</small></sup> the XForms Processor should dispatch the event [[XForms_2.0#evt-bindingError|xforms-binding-error Event]]<sup><small>XF</small></sup> to the model. If the function is used in a [[XForms_2.0#def-computed-expression|computed expression]]<sup><small>XF</small></sup> the XForms Processor should dispatch the event [[XForms_2.0#evt-expressionError|xforms-expression-error Event]]<sup><small>XF</small></sup> to the model.

<div class="note">

'''Note:'''

Similarly to the <code>valid()</code> function, the readonly property of a node might appear to be out of date by the time the <code>readonly()</code> function is used if
changes have been made to instance data between the time <code>xforms-recalculate</code> and/or <code>xforms-revalidate</code>
processing occur and the time the function is called. This function must therefore be used with caution.

</div>

</div>

<div class="div3">

==== <span id="fn-required">The required() Function</span> ====

<code class="function">xf:required() as xs:boolean</code>

<code class="function">xf:required($items as item()*) as xs:boolean</code>

The <code>required()</code> function returns the required property of XPath items, including instance data nodes.

Selected items consist of each item referred to by the <code>$items</code> parameter, if present, or the expression's context item, if absent.

If there are no resulting selected items, the function returns <code>false()</code>.

Otherwise the function computes the logical OR of the required property of all the selected items.

The required property information of an individual node is obtained by looking at the node's required property computed as per
[[XForms_2.0#evt-recalculate|The xforms-recalculate Event]]<sup><small>XF</small></sup>. The required information of an XPath atomic value is always <code>false()</code>.

If the function is used in a [[XForms_2.0#def-model-binding-expression|model binding expression]]<sup><small>XF</small></sup> the XForms Processor should dispatch the event [[XForms_2.0#evt-bindingError|xforms-binding-error Event]]<sup><small>XF</small></sup> to the model. If the function is used in a [[XForms_2.0#def-computed-expression|computed expression]]<sup><small>XF</small></sup> the XForms Processor should dispatch the event [[XForms_2.0#evt-expressionError|xforms-expression-error Event]]<sup><small>XF</small></sup> to the model.

<div class="note">

'''Note:'''

Similarly to the <code>valid()</code> function, the required property of a node might appear to be out of date by the time the <code>required()</code> function is used if
changes have been made to instance data between the time <code>xforms-recalculate</code> and/or <code>xforms-revalidate</code>
processing occur and the time the function is called. This function must therefore be used with caution.

</div>

</div>

<div class="div3">

==== <span id="fn-matches">The matches() Function</span> ====

<code class="function">xf:matches</code>(<code class="arg">$input</code><code class="as"> as </code><code class="type">xs:string?</code>, <code class="arg">$pattern</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:boolean</code>

<code class="function">xf:matches</code>(<code class="arg">$input</code><code class="as"> as </code><code class="type">xs:string?</code>, <code class="arg">$pattern</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$flags</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:boolean</code>

The function returns <code>true</code> if $input matches the regular expression supplied as $pattern as influenced by the value of $flags. The function behavioral details, regular expression pattern syntax and flags are defined by XPath 2.0. This function from XPath 2.0 is included in the XForms function library for authoring ease and for XPath 1.0 expression compatibility.

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:matches("abracadabra", "bra")

</div>

returns <code>true</code>.

<div class="exampleInner">

 xf:matches('(123) 456-7890', '^\(?(\d{3})\)? [-. ]?(\d{3}) [-. ]?(\d{4})$')

</div>

returns <code>true</code>.

<div class="exampleInner">

<pre><nowiki>
<model>
  <xf:instance xmlns="">
    <data>
      <phone>abc</phone>
    </data>
  </xf:instance>
  <bind ref="phone" constraint="xf:matches(., '^\(?(\d{3})\)? [-. ]?(\d{3}) [-. ]?(\d{4})$')"/>
</model>
</nowiki></pre>

</div>

The function returns <code>false</code> to the <code>constraint</code>.

</div>

</div>

</div>

<div class="div2">

=== <span id="expr-lib-num">Number Functions</span>===

<div class="div3">

==== <span id="fn-avg">The avg() Function</span> ====

The following function has two definitions:

# In XPath 2.0 mode, the standard XPath 2.0 <code>avg</code> function is used.
# In XPath 1.0 backwards compatibility mode, the following definition of the <code>avg</code> is made available and the standard XPath 2.0 <code>avg</code> function is not available.

<code class="function">xf:avg</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">node()*</code>)<code class="as"> as </code><code class="return-type">xs:double</code>

Function <code>avg</code> returns the arithmetic average of the result of converting the string-values of each node in the argument node-set to a number. The sum is computed with <code>sum()</code>, and divided with <code>div</code> by the value computed with <code>count()</code>. If the parameter is an empty node-set, or if any of the nodes evaluate to <code>NaN</code>, the return value is <code>NaN</code>.

</div>

<div class="div3">

==== <span id="fn-min">The min() Function</span> ====

The following function has two definitions:

# In XPath 2.0 mode, the standard XPath 2.0 <code>min</code> function is used.
# In XPath 1.0 backwards compatibility mode, the following definition of the <code>min</code> is made available and the standard XPath 2.0 <code>min</code> function is not available.

<code class="function">xf:min</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">node()*</code>)<code class="as"> as </code><code class="return-type">xs:double</code>

Function <code>min</code> returns the minimum value of the result of converting the string-values of each node in argument node-set to a number. "Minimum" is determined with the <code><</code> operator. If the parameter is an empty sequence, or if any of the nodes evaluate to <code>NaN</code>, the return value is <code>NaN</code>.

</div>

<div class="div3">

==== <span id="fn-max">The max() Function</span> ====

The following function has two definitions:

# In XPath 2.0 mode, the standard XPath 2.0 <code>max</code> function is used.
# In XPath 1.0 backwards compatibility mode, the following definition of the <code>max</code> is made available and the standard XPath 2.0 <code>max</code> function is not available.

<code class="function">xf:max</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">node()*</code>)<code class="as"> as </code><code class="return-type">xs:double</code>

Function <code>max</code> returns the maximum value of the result of converting the string-values of each node in argument node-set to a number. "Maximum" is determined with the <code><</code> operator. If the parameter is an empty sequence, or if any of the nodes evaluate to <code>NaN</code>, the return value is <code>NaN</code>.

</div>

<div class="div3">

==== <span id="fn-count-non-empty">The count-non-empty() Function</span> ====

<code class="function">xf:count-non-empty</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">node()*</code>)<code class="as"> as </code><code class="return-type">xs:integer</code>

Function <code>count-non-empty</code> returns the number of non-empty nodes in the first argument. A node is considered non-empty if it is convertible into a string with a greater-than zero length.

</div>

<div class="div3">

==== <span id="fn-index">The index() Function</span> ====

<code class="function">xf:index</code>(<code class="arg">$repeat-id</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">numeric</code>

Function <code>index</code> takes a string argument that is the <code>IDREF</code> of a <code>repeat</code> and returns the current 1-based position of the repeat index for the identified <code>repeat</code> as an integer value —see [[XForms_2.0#ui-repeat|The repeat Element]]<sup><small>XF</small></sup> for details on <code>repeat</code> and its associated repeat index. If the specified argument does not identify a <code>repeat</code>, the function returns the double value <code>NaN</code>.

<div class="note">

'''Note:'''

The IDREF obtained from the function parameter may not uniquely identify the desired <code>repeat</code> if the <code>repeat</code> element bearing the matching ID resides in a repeating construct such as element <code>repeat</code>. The general method described in [[XForms_2.0#idref-resolve|Resolving ID References in XForms]]<sup><small>XF</small></sup> is used to determine the desired run-time repeat object.

</div>

The function <code>index</code> introduces additional dependencies for the computational dependency data structure, see [[#additional-references| Additional dependencies for the computational dependency data structure]] for details.

<div class="exampleOuter"><div class="exampleHead">index</div>

<div class="exampleInner">

 <trigger>
   <label>Add to Shopping Cart</label>
   <insert ev:event="DOMActivate" position="after"
           nodeset="items/item" at="xf:index('cartUI')"/>
 </trigger>

</div>

When activated, this trigger inserts a new <code>item</code> element as the successor of the <code>item</code> element indicated by the <code>index()</code> function.

</div>

</div>

<div class="div3">

==== <span id="fn-power">The power() Function</span> ====

<code class="function">xf:power</code>(<code class="arg">$base</code><code class="as"> as </code><code class="type">numeric</code>, <code class="arg">$exponent</code><code class="as"> as </code><code class="type">numeric</code>)<code class="as"> as </code><code class="return-type">numeric</code>

Raises the first argument to the power of the second argument, returning the result. If the calculation does not result in a real number, then the double value <code>NaN</code> is returned.

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:power(2, 3)

</div>

returns <code>8</code>

<div class="exampleInner">

 xf:power(-1, 0.5)

</div>

returns <code>NaN</code>.

<div class="exampleInner">

 if (prin>0 and dur>0 and rate>0) then prin*rate/(1-xf:power(1+rate, -dur)) else 0

</div>

returns a compounded interest payment value given a non-zero principal (<code>prin</code>), duration (<code>dur</code>) and periodic interest rate (<code>rate</code>).

</div>

</div>

<div class="div3">

==== <span id="fn-random">The random() Function</span> ====

<code class="function">xf:random</code>(<code class="arg">$seed</code><code class="as"> as </code><code class="type">xs:boolean?</code>)<code class="as"> as </code><code class="return-type">xs:double</code>

This function generates and returns a uniformly distributed random or pseudorandom number in the range from 0.0 up to but excluding 1.0. This function accepts an author-optional boolean parameter that is <code>false</code> by default. If <code>true</code>, the random number generator for this function is first seeded with a source of randomness before generating the return value. A typical implementation may seed the random number generator with the current system time in milliseconds when <code>random(true)</code> is invoked, and it may apply a linear congruential formula to generate return values on successive invocations of the function.

Example:

<div class="exampleOuter">

<div class="exampleInner">

 xf:random()

</div>

could return <code>0.14159265358979</code>

</div>

</div>

<div class="div3">

==== <span id="fn-compare">The compare() Function</span> ====

<code class="function">xf:compare</code>(<code class="arg">$arg1</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$arg2</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:integer</code>

This function returns -1, 0, or 1, depending on whether the value of the first argument is respectively less than, equal to, or greater than the value of second argument based on lexicographic comparison using Unicode code point values [[#ref-unicode-collation| [Unicode Collation Algorithm]]].

Example:

<div class="exampleOuter">

<div class="exampleInner">

 xf:compare('apple', 'orange')

</div>

returns <code>-1</code>

</div>

</div>

</div>

<div class="div2">

=== <span id="expr-lib-string">String Functions</span> ===

<div class="div3">

==== <span id="fn-case">The case() Function</span> ====

<code class="function">xf:case</code>(<code class="arg">$switch-id</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:string?</code>

Function <code>case</code> takes a string argument that is the <code>IDREF</code> of a switch and returns the <code>ID</code> of the selected case for the identified <code>switch</code>—see [[XForms_2.0#ui-switch|The switch Element]]<sup><small>XF</small></sup> for details on <code>switch</code>.

The empty sequence is returned, if the specified argument does not identify a <code>switch</code>.

<div class="note">

'''Note:'''

The IDREF obtained from the function parameter may not uniquely identify the desired <code>switch</code> if the <code>switch</code> element bearing the matching ID resides in a repeating construct such as element <code>repeat</code>. The general method described in [[XForms_2.0#idref-resolve|Resolving ID References in XForms]]<sup><small>XF</small></sup> is used to determine the desired run-time repeat object.

</div>

The function <code>case</code> introduces additional dependencies for the computational dependency data structure, see [[#additional-references|Additional dependencies for the computational dependency data structure]] for details.

</div>

<div class="div3">

==== <span id="fn-property">The property() Function</span> ====

<code class="function">xf:property</code>(<code class="arg">$property-name</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:string?</code>

This function accepts a string identifying a property name. If the property name is not recognized, the empty sequence is returned. The property definitions for this function are as follows:

{| summary="Property function parameters and return values" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Return Value
|-
| rowspan="1" colspan="1" | <code>version</code>
| rowspan="1" colspan="1" | <code>1.1</code> or <code>2.0</code>
|-
| rowspan="1" colspan="1" | <code>conformance-level</code>
| rowspan="1" colspan="1" | <code>full</code>, <code>basic</code> or a string beginning with <code>full</code> or <code>basic</code>
|-
| rowspan="1" colspan="1" |
Any other [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]
| rowspan="1" colspan="1" |
Reserved. Their use results in an exception (see [[#expr-lib| '''4 The XForms Function Library''']] for the exception type)
|-
| rowspan="1" colspan="1" |
[[#def-QNameButNotNCName| QNameButNotNCName]]
| rowspan="1" colspan="1" | An implementation-specific property value, such as a locale or timezone for the user agent. If the implementation does not support the property, then empty string is returned.
|}

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:property('version')

</div>

returns <code>2.0</code>

<div class="exampleInner">

 xf:property('conformance-level')

</div>

may return <code>full</code>

</div>

</div>

<div class="div3">

==== <span id="fn-digest">The digest() Function</span> ====

<code class="function">xf:digest</code>(<code class="arg">$data</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$algo</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$encoding</code><code class="as"> as </code><code class="type">xs:string?</code>)<code class="as"> as </code><code class="return-type">xs:string</code>

This function accepts a string of data, a string indicating a cryptographic hashing algorithm, and an author-optional string indicating an encoding method. The data string is serialized as UTF-8, the hash value is then computed using the indicated hash algorithm, and the hash value is then encoded by the indicated method, and the result is returned by the function. The following table presents the keywords for the second string parameter and the corresponding hash algorithms:

{| summary="Hash algorithms for the digest() function" border="1"
! rowspan="1" colspan="1" | Keywords
! rowspan="1" colspan="1" | Hash Algorithm
! rowspan="1" colspan="1" | Status
|-
| rowspan="1" colspan="1" | <code>MD5</code>
| rowspan="1" colspan="1" |
The MD5 hash algorithm defined in [[#ref-md5| [MD5]]]
| rowspan="1" colspan="1" |
[[#intro-reading| Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-1</code>
| rowspan="1" colspan="1" |
The SHA-1 hash algorithm defined in [[#ref-sha2| [SHA2]]]
| rowspan="1" colspan="1" |
[[#intro-reading| Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-256</code>
| rowspan="1" colspan="1" |
The SHA-256 hash algorithm defined in [[#ref-sha2| [SHA2]]]
| rowspan="1" colspan="1" |
[[#intro-reading| Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-384</code>
| rowspan="1" colspan="1" |
The SHA-384 hash algorithm defined in [[#ref-sha2| [SHA2]]]
| rowspan="1" colspan="1" |
[[#intro-reading| Optional]]
|-
| rowspan="1" colspan="1" | <code>SHA-512</code>
| rowspan="1" colspan="1" |
The SHA-512 hash algorithm defined in [[#ref-sha2| [SHA2]]]
| rowspan="1" colspan="1" |
[[#intro-reading| Optional]]
|-
| rowspan="1" colspan="1" |
Any other [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]
| rowspan="1" colspan="1" |
Reserved. Their use results in an exception (see [[#expr-lib| '''4 The XForms Function Library''']] for the exception type)
| rowspan="1" colspan="1" |
[[#intro-reading| Required]]
|-
| rowspan="1" colspan="1" |
[[#def-QNameButNotNCName| QNameButNotNCName]]
| rowspan="1" colspan="1" |
An implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an exception occurs (see [[#expr-lib| '''4 The XForms Function Library''']] for the exception type).
| rowspan="1" colspan="1" |
[[#intro-reading| Required]]
|}

This recommendation defines the values <code>hex</code> and <code>base64</code> for the third string parameter that indicates the encoding method. If the parameter is missing, then the default is <code>base64</code>. The <code>hex</code> and <code>base64</code> encoding methods of this function correspond to the encodings defined in [[#ref-xschema-2| [XML Schema part 2]]] for the datatypes <code>hexBinary</code> and <code>base64Binary</code>, respectively. For the hexadecimal encoding, the digits 'a' through 'f' are encoded with lower case letters. Any other string value given for the encoding method results in an exception (see [[#expr-lib| '''4 The XForms Function Library''']] for the exception type).

<div class="exampleOuter">

<div class="exampleInner">

 xf:digest('abc', 'SHA-1', 'hex')

</div>

returns <code>a9993e364706816aba3e25717850c26c9cd0d89d</code>.

<div class="exampleInner">

 xf:digest('abc', 'MD5', 'hex')

</div>

returns <code>900150983cd24fb0d6963f7d28e17f72</code>.

<div class="exampleInner">

 xf:digest('abc', 'SHA-256', 'hex')

</div>

returns <code>ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad</code>

</div>

</div>

<div class="div3">

==== <span id="fn-hmac">The hmac() Function</span> ====

<code class="function">xf:hmac</code>(<code class="arg">$secret</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$data</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$algo</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$encoding</code><code class="as"> as </code><code class="type">xs:string?</code>)<code class="as"> as </code><code class="return-type">xs:string</code>

This function accepts a string for a key or shared secret, a string of data, a string indicating a cryptographic hashing algorithm, and an author-optional string indicating an encoding method. The key and data strings are serialized as UTF-8, and they are subjected to the HMAC algorithm defined in [[#ref-hmac| [HMAC]]] and parameterized by the the hash algorithm indicated by the third parameter. The result is encoded with the method indicated by the fourth parameter, and the result is returned by the function.

The following table presents the keywords for the third string parameter and the corresponding hash algorithms:

{| summary="Hash algorithms for the hmac() function" border="1"
! rowspan="1" colspan="1" | Keywords
! rowspan="1" colspan="1" | Hash Algorithm
! rowspan="1" colspan="1" | Status
|-
| rowspan="1" colspan="1" | <code>MD5</code>
| rowspan="1" colspan="1" |
The MD5 hash algorithm defined in [[#ref-md5| [MD5]]]
| rowspan="1" colspan="1" |
[[#intro-reading| Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-1</code>
| rowspan="1" colspan="1" |
The SHA-1 hash algorithm defined in [[#ref-sha2| [SHA2]]]
| rowspan="1" colspan="1" |
[[#intro-reading| Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-256</code>
| rowspan="1" colspan="1" |
The SHA-256 hash algorithm defined in [[#ref-sha2| [SHA2]]]
| rowspan="1" colspan="1" |
[[#intro-reading| Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-384</code>
| rowspan="1" colspan="1" |
The SHA-384 hash algorithm defined in [[#ref-sha2| [SHA2]]]
| rowspan="1" colspan="1" |
[[#intro-reading| Optional]]
|-
| rowspan="1" colspan="1" | <code>SHA-512</code>
| rowspan="1" colspan="1" |
The SHA-512 hash algorithm defined in [[#ref-sha2| [SHA2]]]
| rowspan="1" colspan="1" |
[[#intro-reading| Optional]]
|-
| rowspan="1" colspan="1" |
Any other [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]
| rowspan="1" colspan="1" |
Reserved. Their use results in an exception (see [[#expr-lib| '''4 The XForms Function Library''']] for the exception type)
| rowspan="1" colspan="1" |
[[#intro-reading| Required]]
|-
| rowspan="1" colspan="1" |
[[#def-QNameButNotNCName| QNameButNotNCName]]
| rowspan="1" colspan="1" |
An implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an exception occurs (see [[#expr-lib| '''4 The XForms Function Library''']] for the exception type).
| rowspan="1" colspan="1" |
[[#intro-reading| Required]]
|}

This recommendation defines the values <code>hex</code> and <code>base64</code> for the fourth string parameter that indicates the encoding method. If the parameter is missing, then the default is <code>base64</code>. The <code>hex</code> and <code>base64</code> encoding methods of this function correspond to the encodings defined in [[#ref-xschema-2| [XML Schema part 2]]] for the datatypes <code>hexBinary</code> and <code>base64Binary</code>, respectively. For the hexadecimal encoding, the digits 'a' through 'f' are encoded with lower case letters. Any other string value given for the encoding method results in an exception (see [[#expr-lib| '''4 The XForms Function Library''']] for the exception type).

<div class="exampleOuter">

<div class="exampleInner">

 xf:hmac('Jefe', 'what do ya want for nothing?', 'SHA-1', 'hex')

</div>

returns <code>effcdf6ae5eb2fa2d27416d5f184df9c259a7c79</code>

<div class="exampleInner">

 xf:hmac('Jefe', 'what do ya want for nothing?', 'MD5', 'hex')

</div>

returns <code>750c783e6ab0b503eaa86e310a5db738</code>

<div class="exampleInner">

 xf:hmac('Jefe', 'what do ya want for nothing?', 'SHA-256', 'hex')

</div>

returns <code>5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843</code>

</div>

</div>

<div class="div3">

==== <span id="fn-replace">The replace() Function</span> ====

<code class="function">xf:replace</code>(<code class="arg">$input</code><code class="as"> as </code><code class="type">xs:string?</code>, <code class="arg">$pattern</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$replacement</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:string</code>

<code class="function">xf:replace</code>(<code class="arg">$input</code><code class="as"> as </code><code class="type">xs:string?</code>, <code class="arg">$pattern</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$replacement</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$flags</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:string</code>

The function returns the <code>xs:string</code> that is obtained by replacing each non-overlapping substring of $input that matches the given $pattern (as influenced by the value of $flags) with an occurrence of the $replacement string.  The function behavioral details, regular expression pattern syntax, replacement string syntax and flags are defined by XPath 2.0. This function from XPath 2.0 is included in the XForms function library for authoring ease and for XPath 1.0 expression compatibility.

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:replace("abcd", "(ab)|(a)", "[1=$1][2=$2]")

</div>

 returns <code>[1=ab][2=]cd</code>.

<div class="exampleInner">

 xf:replace('1234567890', '^\(?(\d{3})\)? [-. ]?(\d{3}) [-. ]?(\d{4})$', '($1) $2-$3')

</div>

returns <code>(123) 456-7890</code>.

<div class="exampleInner">

<pre><nowiki>
<model>
  <xf:instance xmlns="">
    <data>
      <phone></phone>
    </data>
  </xf:instance>
  <bind ref="phone" constraint="xf:matches(., '^\(?(\d{3})\)? [-. ]?(\d{3}) [-. ]?(\d{4})$')"/>
</model>
<input ref="phone">
   <label>Enter phone number:</label>
   <setvalue ev:event="xforms-value-changed" ref="."
             value="xf:replace(., '^\(?(\d{3})\)? [-. ]?(\d{3}) [-. ]?(\d{4})$', '($1) $2-$3')"/>
</input>
</nowiki></pre>

</div>

If the user enters an input of <code>1234567890</code>, the <code>setvalue</code> uses the function to change the content of the <code>phone</code> element to <code>(123) 456-7890</code>.

</div>

</div>

<div class="div3">

==== <span id="fn-serialize">The serialize() Function</span> ====

<code class="function">xf:serialize</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">item()*</code>)<code class="as"> as </code><code class="return-type">xs:string</code>

<code class="function">xf:serialize</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">item()*</code>, <code class="arg">$params</code><code class="as"> as </code><code class="type">element(output:serialization-parameters)?</code>)<code class="as"> as </code><code class="return-type">xs:string</code>

This function serializes the supplied input sequence <code>$arg</code> as described in [[#ref-xslt-xquery-serialization-30 | [XSLT and XQuery Serialization 3.0]]], returning the serialized representation of the sequence as a string. The function must behave as the XPath 3.0 functions of the same name as specified in [[#ref-xpath-xquery-functions-operators-30 | [XPath and XQuery Functions and Operators 3.0]]].

As allowed by [[#ref-xslt-xquery-serialization-30 | [XSLT and XQuery Serialization 3.0]]] XForms specifies two additional output methods:

* <code>xforms:json</code>. When this method is specified, JSON serialization is performed following section [[XForms_2.0#External JSON values|External JSON values]]<sup><small>XF</small></sup>.
* <code>xforms:csv</code>. When this method is specified, CSV serialization is performed following section [[XForms_2.0#External CSV values|External CSV values]]<sup><small>XF</small></sup>.

If the <code>xforms:json</code> or <code>xforms:csv</code> method is specified and serialization fails, a dynamic error is raised.

XForms also specifies the following additional serialization parameter:

{| summary="The $format specifiers of the xf:serialize() function" border="1"
! rowspan="1" colspan="1" | Serialization parameter name
! rowspan="1" colspan="1" | Permitted values for parameter and meaning
|-
| rowspan="1" colspan="1" | <code>xforms:relevant</code>
| rowspan="1" colspan="1" | One of the enumerated values <code>yes</code> or <code>no</code>. When <code>yes</code>, non-relevant nodes in the input sequence specified by <code>$arg</code> are pruned. The default value is <code>yes</code> by consistency with <code>xforms:submission</code>.
|}

Example:

<div class="exampleOuter">

<div class="exampleInner">

<pre><nowiki>
 <model>
    <xf:instance xmlns="">
       <data>
          <node>abc</node>
          <text>&amp;lt;node&amp;gt;abc&amp;lt;/node&amp;gt;</text>
       </data>
    </xf:instance>
    <bind ref="text" calculate="xf:serialize(../node, instance('serialization'))"/>
 </model>
</nowiki></pre>

</div>

The function returns a string containing the serialization of element <code>node</code> following the serialization parameters held in the <code>serialization</code> instance. The result is placed into the content of the element <code>text</code> by the <code>calculate</code> attribute.

</div>


</div>

</div>

<div class="div2">

=== <span id="expr-lib-date">Date and Time Functions</span> ===

<div class="note">

'''Note:'''

The following XML Schema datatypes do not have specific functions for manipulation within XForms expressions: <code>xsd:gYearMonth</code>, <code>xsd:gYear</code>, <code>xsd:gMonthDay</code>, <code>xsd:gDay</code>, <code>xsd:gMonth</code>. Extension functions ([[XForms_2.0#Extension_Functions|Extension Functions]]<sup><small>XF</small></sup>) may be used to perform needed operations on these datatypes.

</div>

<div class="div3">

==== <span id="fn-local-date">The local-date() Function</span> ====

<code class="function">xf:local-date</code>()<code class="as"> as </code><code class="return-type">xs:date</code>

This function returns a lexical <code>xsd:date</code> obtained as if by the following rules: the result of <code>now()</code> is converted to a local date based on the user agent time zone information. If no time zone information is available, then the date portion of the result of <code>now()</code> is returned.

Example:

<div class="exampleOuter">

<div class="exampleInner">

 xf:local-date()

</div>

could return <code>2006-10-13-07:00</code>

<div class="exampleInner">

 xf:substring(local-date(), 1, 10)

</div>

could return <code>2006-10-13</code>

<div class="exampleInner">

 xf:days-to-date(days-from-date(local-date()) + 31)

</div>

returns a date that is 31 days from today. For example, if <code>local-date()</code> returns <code>2006-10-13-07:00</code>, then the result is <code>2006-11-13</code>.

</div>

</div>

<div class="div3">

==== <span id="fn-local-dateTime">The local-dateTime() Function</span> ====

<code class="function">xf:local-dateTime</code>()<code class="as"> as </code><code class="return-type">xs:dateTime</code>

This function returns a lexical <code>xsd:dateTime</code> obtained as if by the following rules: the result of <code>now()</code> is converted to a local dateTime based on the user agent time zone information. If no time zone information is available, then the result of <code>now()</code> is returned.

Example:

<div class="exampleOuter">

<div class="exampleInner">

 xf:local-dateTime()

</div>

could return <code>2006-10-13T16:04:17-07:00</code>

<div class="exampleInner">

 xf:adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(local-dateTime()) + 7200))

</div>

Adds two hours (7200 seconds) to the local date and time, returning the result in the local time zone. For example, if <code>local-dateTime()</code> returns <code>2007-10-02T14:26:43-07:00</code>, then the above expression returns <code>2007-10-02T16:26:43-07:00</code>

</div>

</div>

<div class="div3">

==== <span id="fn-now">The now() Function</span> ====

<code class="function">xf:now</code>()<code class="as"> as </code><code class="return-type">xs:string</code>

The <code>now</code> function returns the current UTC date and time as a string value in the canonical XML Schema <code>xsd:dateTime</code> format. If time zone information is available, it is used to convert the date and time to UTC. If no time zone information is available, then the date and time are assumed to be in UTC.

<div class="note">

'''Note:'''

Attaching a calculation of "<code>now()</code>" to an instance data node would not result in a stream of continuous recalculations of the XForms Model.

</div>

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:now()

</div>

returns <code>2006-10-14T01:04:17Z</code> if <code>local-dateTime()</code> returns <code>2006-10-13T18:04:17-07:00</code>

<div class="exampleInner">

 xf:seconds-to-dateTime(seconds-from-dateTime(now()) + 7200)

</div>

Computes two hours from now, returning the result in UTC time. For example, if <code>now()</code> returns <code>2007-10-02T21:26:43Z</code>, then the above expression returns <code>2007-10-02T23:26:43Z</code>

</div>

</div>

<div class="div3">

==== <span id="fn-days-from-date">The days-from-date() Function</span> ====

<code class="function">xf:days-from-date</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">numeric</code>

This function returns a whole number of days, according to the following rules:

If the string parameter represents a legal lexical <code>xsd:date</code> or <code>xsd:dateTime</code>, the return is an integer value which is equal to the number of days difference between the specified date or dateTime (normalized to UTC) and <code>1970-01-01</code>. Hour, minute, and second components are ignored after normalization. Any other input parameter causes a return of the double value <code>NaN</code>.

<div class="note">

'''Note:'''

If an <code>xsd:date</code> is given as the parameter, the timezone is ignored if provided because there is no way to normalize to the date in the UTC timezone without both the time and timezone.

</div>

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:days-from-date("2002-01-01")

</div>

returns <code>11688</code>

<div class="exampleInner">

 xf:days-from-date("2002-01-01-07:00")

</div>

returns <code>11688</code>

<div class="exampleInner">

 xf:days-from-date("1969-12-31")

</div>

returns <code>-1</code>

</div>

</div>

<div class="div3">

==== <span id="fn-days-to-date">The days-to-date() Function</span> ====

<code class="function">xf:days-to-date</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">xs:double</code>)<code class="as"> as </code><code class="return-type">xs:string</code>

This function returns a string containing a lexical <code>xsd:date</code> that corresponds to the number of days passed as the parameter according to the following rules:

The parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired date and <code>1970-01-01</code>. An input parameter value of <code>NaN</code> results in output of the empty string.

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:days-to-date(11688)

</div>

returns <code>2002-01-01</code>

<div class="exampleInner">

 xf:days-to-date(-1)

</div>

returns <code>1969-12-31</code>

</div>

</div>

<div class="div3">

==== <span id="fn-seconds-from-dateTime">The seconds-from-dateTime() Function</span> ====

<code class="function">xf:seconds-from-dateTime</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">numeric</code>

This function returns a possibly fractional number of seconds, according to the following rules:

If the string parameter represents a legal lexical <code>xsd:dateTime</code>, the return is a decimal value which is equal to the number of seconds difference between the specified dateTime (normalized to UTC) and <code>1970-01-01T00:00:00Z</code>. If no time zone is specified, UTC is used. Any other input string parameter causes a return of the double value <code>NaN</code>. This function does not support leap seconds.

Example:

<div class="exampleOuter">

<div class="exampleInner">

 xf:seconds-from-dateTime('1970-01-01T00:00:00Z')

</div>

returns <code>0</code>

<div class="exampleInner">

 xf:seconds-from-dateTime('1970-01-01T00:00:00-08:00')

</div>

returns <code>28800</code>

</div>

</div>

<div class="div3">

==== <span id="fn-seconds-to-dateTime">The seconds-to-dateTime() Function</span> ====

<code class="function">xf:seconds-to-dateTime</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">xs:double</code>)<code class="as"> as </code><code class="return-type">xs:string</code>

This function returns a string containing a lexical <code>xsd:dateTime</code> that corresponds to the number of seconds passed as the parameter according to the following rules:

The parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired UTC dateTime and <code>1970-01-01T00:00:00Z</code>. An input parameter value of <code>NaN</code> results in output of the empty string. This function does not support leap seconds.

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:seconds-to-dateTime(0)

</div>

returns <code>1970-01-01T00:00:00Z</code>

<div class="exampleInner">

 xf:seconds-from-dateTime(28800)

</div>

returns <code>1970-01-01T08:00:00Z</code>

<div class="exampleInner">

 xf:seconds-to-dateTime(seconds-from-dateTime(now()) + 7200)

</div>

Computes two hours from now, returning the result in UTC time. For example, if <code>now()</code> returns <code>2007-10-02T21:26:43Z</code>, then the above expression returns <code>2007-10-02T23:26:43Z</code>

<div class="exampleInner">

 xf:adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(now()) + 7200))

</div>

Computes two hours from now, returning the result in the local time zone. For example, if <code>now()</code> returns <code>2007-10-02T21:26:43Z</code> and the local date and time is <code>2007-10-02T14:26:43-07:00</code>, then the above expression returns <code>2007-10-02T16:26:43-07:00</code>

</div>

</div>

<div class="div3">

==== <span id="fn-adjust-dateTime-to-timezone">The adjust-dateTime-to-timezone() Function</span> ====

<code class="function">xf:adjust-dateTime-to-timezone</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:dateTime</code>

This function adjusts a legal lexical <code>xsd:dateTime</code> received as the parameter to the local time zone for the user of the implementation, and returns the result. The application of daylight savings time is dependent on whether daylight savings time is in effect for the local time zone at the given date and time. "Local" or untimezoned times are presumed to be the time in the local time zone. If the implementation does not have access to time zone information, UTC is used. The result is empty string if the string argument is the empty sequence or not a legal lexical <code>xsd:dateTime</code>.

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:adjust-dateTime-to-timezone('2007-10-07T02:22:00')

</div>

returns <code>2007-10-07T02:22:00-07:00</code> in the Pacific time zone since daylight savings time applies to the date <code>2007-10-02</code> in the Pacific time zone.

<div class="exampleInner">

 xf:adjust-dateTime-to-timezone('2007-10-02T21:26:43Z')

</div>

returns <code>2007-10-02T14:26:43-07:00</code> in the Pacific time zone since daylight savings time applies to the date <code>2007-10-02</code> in the Pacific time zone.

<div class="exampleInner">

 xf:adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(now()) + 7200))

</div>

Computes two hours from now, returning the result in the local time zone. For example, if <code>now()</code> returns <code>2007-10-02T21:26:43Z</code> and the local date and time is <code>2007-10-02T14:26:43-07:00</code> in the Pacific time zone, then the above expression returns <code>2007-10-02T16:26:43-07:00</code>

<div class="exampleInner">

 xf:adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime('2007-10-02T14:26:43-07:00') + 61*86400))

</div>

Returns <code>2007-12-02T13:26:43-08:00</code>, which is the date and time two months (61 days) from the date <code>2007-10-02T14:26:43-07:00</code> in the Pacific timezone, adjusting the result for the fact that daylight savings time no longer applies to the resultant date in the Pacific timezone. Note that the hour component is <code>13</code>, not <code>14</code> and the timezone offset is <code>-08:00</code>, not <code>-07:00</code>.

</div>

</div>

<div class="div3">

==== <span id="fn-seconds">The seconds() Function</span> ====

<code class="function">xf:seconds</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">numeric</code>

This function returns a possibly fractional number of seconds, according to the following rules:

If the string parameter represents a legal lexical <code>xsd:duration</code>, the return is a decimal value which is equal to the number specified in the seconds component plus 60 * the number specified in the minutes component, plus 60 * 60 * the number specified in the hours component, plus 60 * 60 * 24 * the number specified in the days component. The sign of the result will match the sign of the duration. Year and month components, if present, are ignored. Any other input parameter causes a return of the double value <code>NaN</code>.

<div class="note">

'''Note:'''

Even though this function is defined based on a lexical <code>xsd:duration</code>, it is intended for use only with derived-from-<code>xsd:duration</code> datatypes, specifically <code>xforms:dayTimeDuration</code>.

</div>

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:seconds("P3DT10H30M1.5S")

</div>

returns <code>297001.5</code> (3 days, 10 hours, 30 minutes, and 1.5 seconds)

<div class="exampleInner">

 xf:seconds("P1Y2M")

</div>

returns <code>0</code> because the year and month parts of the duration are ignored and the remaining portions are unspecified and default to 0

<div class="exampleInner">

 xf:seconds("3")

</div>

returns <code>NaN</code> because the parameter is not a lexically valid duration

</div>

</div>

<div class="div3">

==== <span id="fn-months">The months() Function</span> ====

<code class="function">xf:months</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">numeric</code>

This function returns a whole number of months, according to the following rules:

If the string parameter represents a legal lexical <code>xsd:duration</code>, the return is an integer value which is equal to the number specified in the months component plus 12 * the number specified in the years component. The sign of the result will match the sign of the duration. Day, hour, minute, and second components, if present, are ignored. Any other input parameter causes a return of the double value <code>NaN</code>.

<div class="note">

'''Note:'''

Even though this function is defined based on a lexical <code>xsd:duration</code>, it is intended for use only with derived-from-<code>xsd:duration</code> datatypes, specifically <code>xforms:yearMonthDuration</code>.

</div>

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:months("P1Y2M")

</div>

returns <code>14</code> (1 year and 2 months)

<div class="exampleInner">

 xf:months("-P19M")

</div>

returns <code>-19</code> because the duration is negative and expresses 0 years and 19 months

</div>

</div>

</div>

<div class="div2">

=== <span id="expr-lib-nodeset">Node-set Functions</span> ===

<div class="div3">

==== <span id="fn-instance">The instance() Function</span> ====

<code class="function">xf:instance</code>(<code class="arg">$id</code><code class="as"> as </code><code class="type">xs:string?</code>)<code class="as"> as </code><code class="return-type">element()?</code>

An XForms Model can contain more than one instance. This function allows access to instance data, within the same XForms Model, but outside the instance data containing the context node if any.

If the argument is omitted or is equal to the empty string, then the root element node (also called the document element node) is returned for the default instance of the current model. The current model, is the model that contains the node of the nearest inscope evaluation context that is a node (starting from the evaluation context of the the node containing the XPath expression that invokes this function).

Otherwise, the argument is converted to a string as if by a call to the <code>string</code> function. This string is treated as an IDREF, which is matched against <code>instance</code> elements in the containing document. If a match is located, and the matching instance data is associated with the same XForms Model as the current model, this function returns the root element node (also called the document element node) of the referenced instance data. In all other cases, an empty sequence is returned.

Example:

For instance data corresponding to this XML:

<div class="exampleOuter">

<div class="exampleInner">

 <xforms:instance xmlns="" id="orderform">
   <orderForm>
     <shipTo>
       <firstName>John</firstName>
     </shipTo>
   </orderForm>
 </xforms:instance>

</div>

</div>

The following expression selects the <code>firstName</code> node. Note that the <code>instance</code> function returns an element node, effectively replacing the leftmost location step from the path:

<div class="exampleOuter">

<div class="exampleInner">

 ref="xf:instance('orderform')/shipTo/firstName"

</div>

</div>

</div>

<div class="div3">

==== <span id="fn-current">The current() Function</span> ====

<code class="function">xf:current</code>()<code class="as"> as </code><code class="return-type">item()</code>

Returns the [http://www.w3.org/TR/xpath20/#dt-context-item context item]<sup><small>XP</small></sup> used to initialize the evaluation of the containing XPath expression.

Examples:

<div class="exampleOuter">

For the following instance data:

<div class="exampleInner">

 <xforms:instance xmlns="">
    <converter>
       <amount>100</amount>
       <currency>jpy</currency>
       <convertedAmount></convertedAmount>
    </converter>
 </xforms:instance>

 <xforms:instance xmlns="" id="convTable">
    <convTable date="20040212" currency="cdn">
       <rate currency="eur">0.59376</rate>
       <rate currency="mxn">8.37597</rate>
       <rate currency="jpy">80.23451</rate>
       <rate currency="usd">0.76138</rate>
    </convTable>
 </xforms:instance>

</div>

and the following value calculation bind:

<div class="exampleInner">

 <bind nodeset="convertedAmount"
       calculate="../amount *
                  xf:instance('convTable')/rate[@currency=xf:current()/../currency]"/>

</div>

the content value of <code>/converter/convertedAmount</code> is the product of <code>/converter/amount</code> and the conversion table rate given by the <code>rate</code> element whose <code>currency</code> attribute value matches the content of <code>/converter/currency</code>.

</div>

<div class="exampleOuter">

For the following instance data:

<div class="exampleInner">

 <xforms:instance xmlns="" id="i1">
    <months>
       <mon>01</mon>
       <mon>02</mon>
       <mon>03</mon>
    </months>
 </xforms:instance>
 <xforms:instance xmlns="" id="i2">
    <months>
       <month code="01">Jan</month>
       <month code="02">Feb</month>
       <month code="03">Mar</month>
    </months>
 </xforms:instance>

</div>

and the following repeat structure:

<div class="exampleInner">

 <repeat nodeset="mon">
    <output value="xf:instance('i2')/month[@code = xf:current()]/>
 </repeat>


</div>

the output should contain <code>Jan Feb Mar</code>.

</div>

</div>

<div class="div3">

==== <span id="fn-id">The id() Function</span> ====

<code class="function">xf:id</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">xs:string*</code>, <code class="arg">$node</code><code class="as"> as </code><code class="type">node()*?</code>)<code class="as"> as </code><code class="return-type">element()*</code>

<code class="function">xf:id</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">node()*</code>, <code class="arg">$node</code><code class="as"> as </code><code class="type">node()*?</code>)<code class="as"> as </code><code class="return-type">element()*</code>

The first parameter provides one or more IDREFs. This may be in the form of a string containing a space-separated list of IDREFs or a sequence of nodes, each node of which contains an IDREF. The second parameter provides nodes in one or more instance data documents to be searched. If the second parameter is not given or is empty, then the instance data document to be searched is the one containing the context node of the function call (if the context item isn't a node and second parameter isn't provided or is the empty sequence an error is raised). For each node in the second parameter (or its default), the set of element nodes are collected with IDs that match the IDREFs from the first parameter. The result of this function is a sequence of elements, in document order with duplicates eliminated, containing the union of the collected element nodes from each string. An element node can be assigned an ID by means of an <code>xml:id</code> attribute or an attribute that is assigned the type ID by a DTD or xsd:ID or any type derived from xsd:ID by an XML schema, or the <code>type</code> model item property.

Example:

<div class="exampleOuter">

<div class="exampleInner">

 xf:id('X Y', instance('Z'))

</div>

Returns nodes identified by X or Y from the instance data document associated with the root element of the <code>instance</code> identified by Z.

</div>

<div class="note">

'''Note:'''

This function is deprecated because it behaves the same as the fn:id() function defined in [[#ref-xpath-functions| [Functions and Operators]]] and we recomend using fn:id().

</div>

<div class="note">

'''Note:'''

When an ID is assigned to a attribute by asigning any type derived from xsd:ID by an XML schema, or the <code>type</code> model item property that inform the ID type information is provided to the XPath data model. And consequently the is-id accessor will return <code>true</code>.

</div>

</div>

<div class="div3">

==== <span id="fn-context">The context() Function</span> ====

<code class="function">xf:context</code>(<code class="arg">$id</code><code class="as"> as </code><code class="type">xs:string?</code>)<code class="as"> as </code><code class="return-type">item()</code>

This function returns the in-scope evaluation context item of an ancestor element of the node containing the XPath expression that invokes this function. The ancestor element is determined using the <code>id</code> parameter, taking into account [[XForms_2.0#idref-resolve|Resolving ID References in XForms]]<sup><small>XF</small></sup>. When the <code>id</code> parameter is omitted, the nearest ancestor element is used for determining the in-scopre evaluation context item to return. The ancestor element may have been created dynamically as part of the run-time expansion of repeated content as described in Section [[XForms_2.0#idref-resolve|Resolving ID References in XForms]]<sup><small>XF</small></sup>.

It is an error to specify a non existing id or an id of an element that isn't an ancestor.

{{SpecNote|If the resolved element isn't a binding element, see [[XForms_2.0#Evaluation_Context|Evaluation Context]]<sup><small>XF</small></sup> for obtaining the evaluation context for non binding elements.}}

Example:

<div class="exampleOuter">

<div class="exampleInner">

 <setvalue ref="x" value="xf:context()/y"/>

</div>

This action sets node <code>x</code> to the value of node <code>y</code>, where both nodes are children of the in-scope evaluation context node for the <code>setvalue</code> element.

</div>

{{SpecNote|An intended use of this function is in conjunction with the <code>repeat</code> element (Section [[XForms_2.0#ui-repeat|The repeat Element]]<sup><small>XF</small></sup> and the <code>setvalue</code> action element (Section [[XForms_2.0#action-setvalue|The setvalue Element]]<sup><small>XF</small></sup>). The intent is to provide form authors with a means of expressing a <code>value</code> attribute that is relative to the repeat context node when the Single Node Binding result is not.}}

</div>

</div>

<div class="div2">

==== <span id="fn-bind">The bind() Function</span> ====

<code class="function">xf:bind</code>(<code class="arg">$id</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">node()*</code>

This function returns the sequence of nodes associated with the bind specified by the <code>id</code> parameter.

The <code>id</code> parameter is interpreted as an ID resolved as per [[XForms_2.0#Resolving ID References in XForms|Resolving ID References in XForms]]<sup><small>XF</small></sup>, as if using the <code>bind</code> attribute. It is an error to specify a non existing bind ID.

If the function is used in a [[XForms_2.0#def-model-binding-expression|model binding expression]]<sup><small>XF</small></sup> the XForms Processor should dispatch the event [[XForms_2.0#evt-bindingError|xforms-binding-error Event]]<sup><small>XF</small></sup> to the model.

Example:

<div class="exampleOuter">

<div class="exampleInner">

<pre><nowiki>
<model>
    <instance>
        <data>
            <color>red</color>
            <color>blue</color>
            <color>green</color>
            <selected-color/>
        </data>
    </instance>
    <bind id="color-bind" ref="color"/>
    <bind id="selected-color-bind" ref="selected-color"/>
</model>
<repeat bind="color-bind" id="color-repeat">
    <output bind="color-bind">
        <label>Color:</label>
    </output>
    <trigger>
        <label>Select Color</label>
        <setvalue
            ev:event="DOMActivate"
            bind="selected-color-bind"
            value="bind('color-bind')[index('color-repeat')]"/>
    </trigger>
</repeat>
<output bind="selected-color-bind">
    <label>Selected Color:</label>
</output>
</nowiki></pre>

</div>

The <code>setvalue</code> action in this example is equivalent to writing:

<div class="exampleInner">

<pre><nowiki>
<setvalue
    ev:event="DOMActivate"
    bind="selected-color-bind"
    value="context()"/>
</nowiki></pre>

</div>

</div>

</div>

</div>

<div class="div2">

=== <span id="expr-lib-node-creation-functions">Node Creation Functions</span>===

<div class="div3">

==== <span id="fn-element">The element() Function</span> ====

<code class="function">xf:element</code>(<code class="arg">$qname</code><code class="as"> as </code><code class="type">xs:anyAtomicType</code>, <code class="arg">$content</code><code class="as"> as </code><code class="type">item()*</code>)<code class="as"> as </code><code class="return-type">element()</code>

This function returns a new XML element with the qualified name provided. If the qualified name is not of type xs:QName the namespace of the element is resolved using the in-scope namespaces (the in-scope default namespace is used for qualified names that are unprefixed). The content argument is a sequence of items specifying attributes and content for the new element.

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:element('value')

</div>

Returns an empty element called "value" (in serialized form the result is <value/>).

<div class="exampleInner">

 xf:element('value', (xf:attribute('id', 'my-value'), 'John'))

</div>

Returns an element called "value" with an attribute "id" and text content "John" (in serialized form the result is <value id="my-value">John</value>).

<div class="exampleInner">

 xf:element('value', ('John', xf:attribute('id', 'my-value')))

</div>

This example illustrates that the attributes may be specified after the content of the element. The result is the same as the previous example (an element called "value" with an attribute "id" and text content "John").

</div>

</div>

<div class="div3">

==== <span id="fn-attribute">The attribute() Function</span> ====

<code class="function">xf:attribute</code>(<code class="arg">$qname</code><code class="as"> as </code><code class="type">xs:anyAtomicType</code>, <code class="arg">$value</code><code class="as"> as </code><code class="type">xs:anyAtomicType?</code>)<code class="as"> as </code><code class="return-type">attribute()</code>

This function returns a new XML attribute with the qualified name provided as first argument. If the qualified name is not of type xs:QName the namespace of the element is resolved using the in-scope namespaces (the in-scope default namespace is used for qualified names that are unprefixed). The second argument is an optional value for the attribute with the empty string as default.

Example:

<div class="exampleOuter">

<div class="exampleInner">

 xf:attribute('id', 'first-name')

</div>

Returns an attribute called "id" with a value of "first-name".

</div>

</div>


<div class="div3">

==== <span id="fn-parse">The parse() Function</span> ====

<code class="function">xf:parse</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">element()?</code>

<code class="function">xf:parse</code>(<code class="arg">$arg</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$format</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">element()?</code>

This function takes as input a document represented as a string in $arg, and returns the XML document element node for the parsed document. The default if the $format is not specified, the XML 1.0 parsing is used. If $arg is the empty sequence or is not well-formed according to the $format parsing rules, the function returns the empty sequence.

The $format is a space-separated list of QNames intended to control various features of parsing, such as the grammar and grammatic variations, as well as allowing namespace qualified custom extensions.

{| summary="The $format specifiers of the xf:parse() function" border="1"
! rowspan="1" colspan="1" | Token
! rowspan="1" colspan="1" | Meaning
|-
| rowspan="1" colspan="1" | <code>xml</code>
| rowspan="1" colspan="1" | Parse input as XML 1.0
|-
| rowspan="1" colspan="1" | <code>json</code>
| rowspan="1" colspan="1" | Parse input as JSON data
|-
| rowspan="1" colspan="1" |
Any other [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]
| rowspan="1" colspan="1" |
Reserved. Their use results in an exception (see [[#expr-lib| '''4 The XForms Function Library''']] for the exception type)
|-
| rowspan="1" colspan="1" |
[[#def-QNameButNotNCName| QNameButNotNCName]]
| rowspan="1" colspan="1" | An implementation-specific parser. If the implementation does not support the parser, then the empty sequence is returned.
|}

<div class="exampleOuter">

<div class="exampleInner">

<pre><nowiki>
 <insert context="container/node" nodeset="elem" at="last()" position="after"
         origin="xf:parse('&amp;lt;elem&amp;gt; &amp;lt;a/&amp;gt; &amp;lt;b/&amp;gt; &amp;lt;/elem&amp;gt;')"/>
</nowiki></pre>

</div>

The function returns the document element node named <code>elem</code>, which is then used as the insert origin, i.e. the source node of the copy operation.

</div>

'''Note:'''

An important use case for this function is to convert unparsed data received by a form, such as from a submission, into parsed data.

</div>

</div>

<div class="div2">

=== <span id="expr-lib-object">Object Functions</span> ===

<div class="div3">

==== <span id="fn-choose">The choose() Function</span> ====

<code class="function">xf:choose</code>(<code class="arg">$condition</code><code class="as"> as </code><code class="type">xs:boolean</code>, <code class="arg">$choice-true</code><code class="as"> as </code><code class="type">item()*</code>, <code class="arg">$choice-false</code><code class="as"> as </code><code class="type">item()*</code>)<code class="as"> as </code><code class="return-type">item()*</code>

This function provides a conditional test that chooses an object to return based on the boolean parameter. If the boolean parameter is true, then the first object is returned, otherwise the second object is returned. Each of the object parameters can be of any XPath datatype as described in Section [[XForms_2.0#Datatypes|Datatypes]]<sup><small>XF</small></sup>, and this function does no type conversion of the parameter it chooses to return.

<div class="note">

'''Note:'''

All parameters of an XPath function are evaluated, so the parameter that is not returned by this function is still evaluated, and its result is discarded by this function.

</div>

Example:

<div class="exampleOuter">

<div class="exampleInner">

 xf:choose(count(x) > 0, x, y)

</div>

Returns the node-set of matching <code>x</code> if it is non-empty and the node-set matching <code>y</code> otherwise.

<div class="exampleInner">

 xf:choose(@x, @x, 0)

</div>

If the context node of the function contains attribute <code>x</code>, then the nodeset containing that attribute is returned. Otherwise, the number <code>0</code> is returned.

</div>

</div>

<div class="div3">

==== <span id="fn-event">The event() Function</span> ====

<code class="function">xf:event</code>(<code class="arg">$property-name</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">item()*</code>

Function <code>event</code> returns context specific information determined by the ''string'' argument. The returned context information is an XPath object whose type and content depends upon the requested property. Each event describes what properties can be accessed by this function and the type and value that will be returned as the result.

The event context properties available on each event are:

{| summary="Event context properties" border="1"
!width="120pt"| Property
!| Type
!| Value
|-
| type
| xs:string
| The name of the event.
|-
| bubbles
| xs:boolean
| Indicates whether or not an event is a bubbling event. If the event can bubble the value is true, else the value is false.
|-
| cancelable
| xs:boolean
| Indicates whether or not an event can have its default action prevented. If the default action can be prevented the value is true, else the value is false.
|-
| targetid
| xs:string?
| The id of the target to which the event was originally dispatched.  If the target does not have an id an empty sequence is returned.
|-
| current-targetid
| xs:string?
| The id of the target whose EventListeners are currently being processed.  If that target does not have an id an empty sequence is returned.
|-
| event-phase
| xs:string
| The current event phase: capture, target, or bubbling (When the event arrives at the target, the value is 'target'. Values capture and bubbling are as described in XML events)
|-
| time-stamp
| xs:integer?
| The time (in milliseconds relative to the epoch) at which the event was created. Due to the fact that some systems may not provide this information the value of timeStamp may be not available for all events. When not available, an empty sequence will be returned. Examples of epoch time are the time of the system start or 0:0:0 UTC 1st January 1970.
|}

The event-specific context properties for each event type are provided in the sections that describe the events.

This function is intended for use in the XPath expressions of XForms actions. If invoked for any other XPath expression, such as a binding expression or model item property expression, this function returns the empty string. If this function is invoked from an XPath expression for an XForms action, then event context information is used from the most recently dispatched event whose action handler contains the XForms action.

Some properties defined for an event may be unavailable if certain prerequisite conditions were not met prior to the event being dispatched. Implementations may also add custom properties. If the event context information does not contain the property indicated by the ''string'' argument, then an empty node-set is returned.

Examples:

<div class="exampleOuter">

<div class="exampleInner">

 xf:event('inserted-nodes')

</div>

If called from an <code>xforms-insert</code> event handler, a nodeset is returned containing the instance data node or nodes inserted.

</div>

</div>

<div class="div3">

==== <span id="fn-eval">The eval() Function</span> ====

<code class="function">xf:eval</code>(<code class="arg">$expression</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">item()*</code>

The function returns the result of evaluating the $expression in the context of the <code>eval()</code> function call. The expression containing the <code>eval()</code> function invocation references the XPath nodes referenced by the $expression, which introduces additional dependencies for the containing expression.

<div class="exampleOuter">

<div class="exampleInner">

<pre><nowiki>
<model>
   <instance xmlns="">
      <data>
         <A>3</A>
         <B>4</B>
         <C value="power(../A * ../A + ../B * ../B, 0.5)">5</C>
      </data>
   </instance>
   <bind nodeset="descendant::*[@value]" calculate="xf:eval(@value)"/>
</model></nowiki></pre>

</div>

The model above responds to changes of data elements <code>A</code> and <code>B</code> by recalculating the value of <code>C</code>. For example, if <code>A</code> and <code>B</code> are changed to <code>5</code> and <code>12</code>, then element <code>C</code> would be recalculated to the value <code>13</code>.  The model below is the same except that the expression in the value attribute is simplified due to the context change performed before the <code>eval()</code> function invocation.

<div class="exampleInner">

<pre><nowiki>
<model>
   <instance xmlns="">
      <data>
         <A>3</A>
         <B>4</B>
         <C value="power(A * A + B * B, 0.5)">5</C>
      </data>
   </instance>
   <bind nodeset="descendant::*[@value]" calculate="../xf:eval(current()/@value)"/>
</model></nowiki></pre>

</div>

</div>

</div>

<div class="div3">

==== <span id="fn-eval-in-context">The eval-in-context() Function</span> ====

<code class="function">xf:eval-in-context</code>(<code class="arg">$expression</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$context</code><code class="as"> as </code><code class="type">node()*</code>)<code class="as"> as </code><code class="return-type">item()*</code>

The function returns the result of evaluating the $expression in the $context.  The expression containing the <code>eval()</code> function invocation references the XPath nodes referenced by the $expression, which introduces additional dependencies for the containing expression.  In XPath 2.0, the <code>eval()</code> function can be invoked later in an expression, after setting the desired context, so this function is included for ease of authoring and XPath 1.0 expression compatibility.

<div class="exampleOuter">

<div class="exampleInner">

<pre><nowiki>
<model>
   <instance xmlns="">
      <data>
         <A>3</A>
         <B>4</B>
         <C value="power(A * A + B * B, 0.5)">5</C>
      </data>
   </instance>
   <bind nodeset="descendant::*[@value]" calculate="xf:eval-in-context(@value, ..)"/>
</model></nowiki></pre>

</div>

The model above responds to changes of data elements <code>A</code> and <code>B</code> by recalculating the value of <code>C</code>. For example, if <code>A</code> and <code>B</code> are changed to <code>5</code> and <code>12</code>, then element <code>C</code> would be recalculated to the value <code>13</code>.  The expression in the value attribute is simplified, relative to a normal calculate expression, due to the context change provided by the second parameter.

</div>


</div>

</div>

<div class="div2">
=== URI Functions===

==== <span id="fn-location-uri">The location-uri() Function</span> ====

<code class="function">xf:location-uri</code>()<code class="as"> as </code><code class="return-type">xs:anyURI</code>

The function returns a URL associated with the current XForms document. The URL should represent the location from which the current document has been loaded.

In a web browser environment, this function must return the same URL that the JavaScript <code>Window.location</code> function would return.

NOTE: If an implementation is not on the client, the fragment might not be returned.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:location-uri()
</nowiki></pre>
</div>

can return the value <code>https://username:password@example.org/pages/order?id=42#content</code>.

</div>

==== <span id="fn-location-param">The location-param() Function</span> ====

<code class="function">xf:location-param</code>(<code class="arg">$name</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:string*</code>

The function returns the current location URL's parameter values for the given name, if any. It is equivalent to:

<code>
xf:uri-param-values(xf:uri-location(), $name)
</code>

The parameter values must be returned in the order they appear in the query. There can be more than one value if the parameter name appears more than once in the query.

</div>

==== <span id="fn-uri-scheme">The uri-scheme() Function</span> ====

<code class="function">xf:uri-scheme</code>(<code class="arg">$uri</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:string?</code>

The function returns the given URI's scheme or protocol if present.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:uri-scheme('https://username:password@example.org/pages/order?id=42#content')
</nowiki></pre>
</div>

returns <code>https</code>.

<div class="exampleInner">
<pre><nowiki>
xf:uri-scheme('mailto:info@example.org')
</nowiki></pre>
</div>

returns <code>mailto</code>.

</div>

==== <span id="fn-uri-scheme-specific-part">The uri-scheme-specific-part() Function</span> ====

<code class="function">xf:uri-scheme-specific-part</code>(<code class="arg">$uri</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$raw</code><code class="as"> as </code><code class="type">xs:boolean</code>)<code class="as"> as </code><code class="return-type">xs:string?</code>

The function returns the given URI's scheme-specific part if present. The scheme-specific part is the URI without its scheme, including the colon delimiter, and without its fragment, including the <code>#</code> character.

If <code>$raw</code> is <code>true()</code>, the escaped octets are not decoded. Otherwise, they are decoded.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:uri-scheme-specific-part('https://username:password@example.org/pages/order?id=42#content')
</nowiki></pre>
</div>

returns <code>//username:password@example.org/pages/order?id=42</code>.

<div class="exampleInner">
<pre><nowiki>
xf:uri-scheme-specific-part('mailto:info@example.org')
</nowiki></pre>
</div>

returns <code>info@example.org</code>.

</div>

==== <span id="fn-uri-authority">The uri-authority() Function</span> ====

<code class="function">xf:uri-authority</code>(<code class="arg">$uri</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$raw</code><code class="as"> as </code><code class="type">xs:boolean</code>)<code class="as"> as </code><code class="return-type">xs:string?</code>

For a hierarchical URI, the function returns the given URI's authority if present. The authority can include, for hierarchical URIs, user information, host, and port.

If <code>$raw</code> is <code>true()</code>, the escaped octets are not decoded. Otherwise, they are decoded.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:uri-authority('https://username:password@example.org/pages/order?id=42#content')
</nowiki></pre>
</div>

returns <code>username:password@example.org</code>.

<div class="exampleInner">
<pre><nowiki>
xf:uri-authority('mailto:info@example.org')
</nowiki></pre>
</div>

returns the empty sequence as the URI is not hierarchical.

</div>

==== <span id="fn-uri-user-info">The uri-user-info() Function</span> ====

<code class="function">xf:uri-user-info</code>(<code class="arg">$uri</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$raw</code><code class="as"> as </code><code class="type">xs:boolean</code>)<code class="as"> as </code><code class="return-type">xs:string?</code>

For a hierarchical URI, the function returns the given URI's user info if present.

If <code>$raw</code> is <code>true()</code>, the escaped octets are not decoded. Otherwise, they are decoded.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:uri-user-info('https://username:password@example.org/pages/order?id=42#content')
</nowiki></pre>
</div>

returns <code>username:password</code>.

<div class="exampleInner">
<pre><nowiki>
xf:uri-user-info('mailto:info@example.org')
</nowiki></pre>
</div>

returns the empty sequence as the URI is not hierarchical.

</div>

==== <span id="fn-uri-host">The uri-host() Function</span> ====

<code class="function">xf:uri-host</code>(<code class="arg">$uri</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:string?</code>

For a hierarchical URI, the function returns the given URI's host if present.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:uri-host('https://username:password@example.org/pages/order?id=42#content')
</nowiki></pre>
</div>

returns <code>example.org</code>.

<div class="exampleInner">
<pre><nowiki>
xf:uri-host('mailto:info@example.org')
</nowiki></pre>
</div>

returns the empty sequence as the URI is not hierarchical.

</div>

==== <span id="fn-uri-port">The uri-port() Function</span> ====

<code class="function">xf:uri-port</code>(<code class="arg">$uri</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:integer?</code>

For a hierarchical URI, the function returns the given URI's port if present.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:uri-port('https://username:password@example.org/pages/order?id=42#content')
</nowiki></pre>
</div>

returns the empty sequence as not port is specified.

<div class="exampleInner">
<pre><nowiki>
xf:uri-port('https://username:password@example.org:8080/pages/order?id=42#content')
</nowiki></pre>
</div>

returns the integer <code>8080</code>.

<div class="exampleInner">
<pre><nowiki>
xf:uri-port('mailto:info@example.org')
</nowiki></pre>
</div>

returns the empty sequence as the URI is not hierarchical.

</div>

==== <span id="fn-uri-path">The uri-path() Function</span> ====

<code class="function">xf:uri-path</code>(<code class="arg">$uri</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$raw</code><code class="as"> as </code><code class="type">xs:boolean</code>)<code class="as"> as </code><code class="return-type">xs:string?</code>

For a hierarchical URI, the function returns the given URI's path if present.

If <code>$raw</code> is <code>true()</code>, the escaped octets are not decoded. Otherwise, they are decoded.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:uri-path('https://username:password@example.org/pages/order?id=42#content')
</nowiki></pre>
</div>

returns <code>/pages/order</code>.

<div class="exampleInner">
<pre><nowiki>
xf:uri-path('mailto:info@example.org')
</nowiki></pre>
</div>

returns the empty sequence as the URI is not hierarchical.

</div>

==== <span id="fn-uri-query">The uri-query() Function</span> ====

<code class="function">xf:uri-query</code>(<code class="arg">$uri</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$raw</code><code class="as"> as </code><code class="type">xs:boolean</code>)<code class="as"> as </code><code class="return-type">xs:string?</code>

For a hierarchical URI, the function returns the given URI's query if present.

If <code>$raw</code> is <code>true()</code>, the escaped octets are not decoded. Otherwise, they are decoded.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:uri-query('https://username:password@example.org/pages/order?id=42#content')
</nowiki></pre>
</div>

returns <code>id=42</code>.

<div class="exampleInner">
<pre><nowiki>
xf:uri-query('mailto:info@example.org?subject=Hello')
</nowiki></pre>
</div>

returns the empty sequence as the URI is not hierarchical.

</div>

==== <span id="fn-uri-fragment">The uri-fragment() Function</span> ====

<code class="function">xf:uri-fragment</code>(<code class="arg">$uri</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$raw</code><code class="as"> as </code><code class="type">xs:boolean</code>)<code class="as"> as </code><code class="return-type">xs:string?</code>

The function returns the given URI's fragment if present.

If <code>$raw</code> is <code>true()</code>, the escaped octets are not decoded. Otherwise, they are decoded.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:uri-fragment('https://username:password@example.org/pages/order?id=42#content')
</nowiki></pre>
</div>

returns <code>content</code>.

<div class="exampleInner">
<pre><nowiki>
xf:uri-fragment('mailto:info@example.org#ignored')
</nowiki></pre>
</div>

returns the empty sequence as the URI is not hierarchical.

</div>

==== <span id="fn-uri-param-names">The uri-param-names() Function</span> ====

<code class="function">xf:uri-param-names</code>(<code class="arg">$uri</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:string*</code>

The function returns the given URI's query parameter names, if present.

The parameter names must be returned in the order they appear in the query. Duplicates are possible, if a parameter name appears more than once.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:uri-param-names('https://example.org/?n1=v11&n2=v21&n1=v12&n2=v22')
</nowiki></pre>
</div>

returns the sequence <code>'n1', 'n2', 'n1', 'n2'</code>. The XPath function <code>distinct-values()</code> can be used to obtain unique values:

<div class="exampleInner">
<pre><nowiki>
distinct-values(xf:uri-param-names('https://example.org/?n1=v11&n2=v21&n1=v12&n2=v22'))
</nowiki></pre>
</div>

returns the sequence <code>'n1', 'n2'</code>.

</div>

==== <span id="fn-uri-param-values">The uri-param-values() Function</span> ====

<code class="function">xf:uri-param-values</code>(<code class="arg">$uri</code><code class="as"> as </code><code class="type">xs:string</code>, <code class="arg">$name</code><code class="as"> as </code><code class="type">xs:string</code>)<code class="as"> as </code><code class="return-type">xs:string*</code>

The function returns the given URI's parameter values for the given parameter name, if present.

The parameter values must be returned in the order they appear in the query. There can be more than one value if the parameter name appears more than once in the query.

<div class="exampleOuter">
<div class="exampleInner">
<pre><nowiki>
xf:uri-param-values('https://example.org/?n1=v11&n2=v21&n1=v12&n2=v22', 'n1')
</nowiki></pre>
</div>

returns the sequence <code>'v11', 'v12'</code>.

If the document was loaded from the location <code>http://example.org/page?q=xforms</code>, then:

<div class="exampleInner">
<pre><nowiki>
xf:uri-param-values(xf:uri-location(), 'q')
</nowiki></pre>
</div>

returns <code>xforms</code>.

</div>

<div class="div2">

=== Extension Functions===
See [[XForms_2.0#Extension_Functions|Extension Functions]]<sup><small>XF</small></sup> in XForms core.
</div>

=== <span id="references-and-dependencies">References and Dependencies</span> ===

<div class="div3">

==== <span id="reference-selection">Reference Selection</span> ====

An XPath node is referenced by an expression if it is selected. A node is selected by matching an XPath NodeTest or by being returned by a function call. For examples, a node can match a name test, a wildcard test, a node type test, or it can be returned by or used as a parameter to a function, or it can appear in a filter expression (where all of the prior examples recursively apply).

The expression parameters of [[#fn-eval|the eval() function]] and [[#fn-eval-in-context|the eval-in-context() function]]) make references to XPath nodes and therefore introduce additional dependencies.

</div>

<div class="div3">

==== <span id="additional-references">Additional dependencies for the computational dependency data structure</span> ====

The <code>index</code> ([[#fn-index|The index() Function]]) and <code>case</code> ([[#fn-case|The case() Function]]) functions introduce additional dependencies for the computational dependency data structure. Beside the normal dependencies introduced by their arguments, these functions also need addtional dependencies to ensure that automatic recalculation happens when respectively the repeat index or selected case changes.

Implementation must behave as if each occurrence of a <code>repeat</code> is associated with an implicitly managed instance data node containing the repeat index. If a <code>repeat</code> identified as <code>R1</code> contains a <code>repeat</code> identified as <code>R2</code>, then a repeat index instance node is managed for each occurrence of <code>R2</code> that is generated by <code>R1</code>. An invocation of the function <code>index()</code> in an expression is considered to reference the repeat index instance node corresponding to the repeat index value that it returns. The same strategy should by used for the function <code>case()</code> (each occurrence of a switch is associated with an implicitly managed instance data node containing the ID of the selected case). An invocation of the function <code>case()</code> in an expression is considered to reference the switch instance node corresponding to the <code>ID</code> of the selected case that it returns. Note that if a <code>switch</code> is embedded in a <code>repeat</code> a seperate instance node (to track the ID of the selected case of the switch) should be created for every iteration in the repeat.

</div>

</div>

<div class="div2">

=== Error Indications===

Error indications happen as a result of unusual conditions in the XForms Processor. Some of these are "fatal" errors, which halt processing, and bear the suffix "exception". Others are simply for notification, and bear the suffix "error". For all events in this section, it is permissible for the XForms Processor to perform some kind of default handling, for example logging error messages to a file.

<div class="div3">

==== <span id="evt-xpathVersionException">The xforms-xpath-version-exception Event</span> ====

Dispatched as an indication of failure of the XPath version checks defined in the description of the <code>xpath-version</code> attribute in Section [[#xpath-version-attribute| '''2 The xpath-version attribute''']].

Target: the default <code>model</code>

Bubbles: Yes

Cancelable: No

Context Info:

{| summary="Event context properties for xforms-version-exception event" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Type
! rowspan="1" colspan="1" | Value
|-
| rowspan="1" colspan="1" | error-information
| rowspan="1" colspan="1" | string
| rowspan="1" colspan="1" | An implementation-specific error string
|}

Default Action: Fatal error (halts processing).

<div class="note">

'''Note:'''

This exception occurs early in processing. XForms processors are not expected to product XForms user interface elements nor even execute XForms action handlers (such as a <code>message</code> action) in response to this event. This exception is dispatched for the benefit of implementation-specific processing code that may be monitoring the behavior of an XForms processor.

</div></div></div><div class="div1">

== Reserved Namespaces==

[Definition<nowiki>: Definition: The XForms namespace, together with certain other namespaces recognized by an XForms processor, are classified as reserved namespaces and must be used only as specified in this and related specifications.] The reserved namespaces are those listed below. </nowiki>

* [Definition<nowiki>: The </nowiki>'''XForms namespace''', described in [[XForms_2.0#structure-namespace|Namespace for XForms]]<sup><small>XP</small></sup>, is reserved.]
* [Definition<nowiki>: The </nowiki>'''xforms function namespace''' <code>http://www.w3.org/2002/xforms</code> is used for xforms extension functions defined in this specification.]
* [Definition<nowiki>: The </nowiki>'''standard function namespace''' <code>http://www.w3.org/2005/xpath-functions</code> is used for functions in the function library defined in [[#ref-xpath-functions| [Functions and Operators]]].]

</div><div class="div1">

== <span id="terms">Glossary Of Terms</span> ==

; Binding expression
: [Definition<nowiki>: An </nowiki>[[#ref-xpath-2.0| [XPath 2.0]]] expression used in a binding.]
; QNameButNotNCName
: [Definition<nowiki>: A </nowiki>[http://www.w3.org/TR/REC-xml-names/#NT-QName QName] that is not an [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]. In 2006, the W3C named this a [http://www.w3.org/TR/REC-xml-names/#NT-PrefixedName PrefixedName]. ]
; XPath 1.0 compatibility mode
: [Definition<nowiki>: The term XPath 1.0 compatibility mode is defined in </nowiki>[http://www.w3.org/TR/xpath20/#static_context Section 2.1.1 Static Context]<sup><small>XP</small></sup>. This is a setting in the static context of an XPath expression; it has two values, <code>true</code> and <code>false</code>. When the value is set to true, the semantics of function calls and certain other operations are adjusted to give a greater degree of backwards compatibility between XPath 2.0 and XPath 1.0.]

</div><div class="div1">

==References==

<div class="div2">

===Normative References===

; HMAC
: [http://www.ietf.org/rfc/rfc2104.txt <cite id="ref-hmac">RFC 2104 - HMAC: Keyed-Hashing for Message Authentication</cite>], H. Krawczyk, M. Bellare, R. Canetti, 1997. Available at http://www.ietf.org/rfc/rfc2104.txt
; RFC 2119
: [http://www.ietf.org/rfc/rfc2119.txt <cite id="ref-rfc-2119">RFC 2119: Key words for use in RFCs to Indicate Requirement Levels</cite>], S. Bradner, 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
; SHA2
: [http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf <cite id="ref-sha2">SECURE HASH STANDARD. FIPS PUB 180-2</cite>], August 2002. Available at http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
; XML Events
: [http://www.w3.org/TR/2003/REC-xml-events-20031014/ <cite id="ref-xml-events">XML Events - An events syntax for XML</cite>], Steven Pemberton, T. V. Raman, Shane P. McCarron, 2003. W3C Recommendation available at: http://www.w3.org/TR/2003/REC-xml-events-20031014/.
; XHTML 1.0
: [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ <cite id="ref-xhtml-1.0">XHTML 1.0: The Extensible HyperText Markup Language - A Reformulation of HTML 4 in XML 1.0</cite>], Steven Pemberton, et al., 2002. W3C Recommendation available at: http://www.w3.org/TR/2002/REC-xhtml1-20020801/.
; XHTML Modularization
: [http://www.w3.org/TR/2008/REC-xhtml-modularization-20081008 <cite id="ref-xhtml-mod">XHTML Modularization 1.1</cite>], D. Austin, S. Peruvemba, S. McCarron, M. Ishikawa, M. Birbeck, 2008. W3C Recommendation available at http://www.w3.org/TR/2008/REC-xhtml-modularization-20081008.
; XPath 1.0
: [http://www.w3.org/TR/1999/REC-xpath-19991116/ <cite id="ref-xpath-1.0">XML Path Language (XPath) Version 1.0</cite>], James Clark, Steve DeRose, 1999. W3C Recommendation available at: http://www.w3.org/TR/1999/REC-xpath-19991116/.
; XPath 2.0
: [http://www.w3.org/TR/2007/REC-xpath20-20070123/ <cite id="ref-xpath-2.0">XML Path Language (XPath) 2.0</cite>], Anders Berglund, Scott Boag, Don Chamberlin, Mary F. Fern&#xe1;ndez, Michael Kay, Jonathan Robie, and J&#xe9;r&#xf4;me Sim&#xe9;on, 2007. W3C Recommendation available at: http://www.w3.org/TR/2007/REC-xpath20-20070123/.
; Functions and Operators
: [http://www.w3.org/TR/2007/REC-xpath-functions-20070123/ <cite id="ref-xpath-functions">XQuery 1.0 and XPath 2.0 Functions and Operators</cite>], Ashok Malhotra, Jim Melton, and Norman Walsh, Editors. World Wide Web Consortium, 23 Jan 2007.
; Luhn Patent
: <cite  id="ref-luhn">Computer for Verifying Numbers</cite>, H. P. Luhn, U.S. Patent 2,950,048, 1960.
; MD5
: [http://www.ietf.org/rfc/rfc1321.txt <cite id="ref-md5">RFC 1321: The MD5 Message-Digest Algorithm</cite>], R. Rivest, 1992. Available at http://www.ietf.org/rfc/rfc1321.txt
; XML 1.0
: [http://www.w3.org/TR/2008/REC-xml-20081126/ <cite id="ref-xml-1.0">XML 1.0</cite>], Extensible Markup Language (XML) 1.0 (Fourth Edition), Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 2008. W3C Recommendation available at: http://www.w3.org/TR/2008/REC-xml-20081126/.
; XML 1.1
: [http://www.w3.org/TR/2006/REC-xml11-20060816/ <cite id="ref-xml-1.1">XML 1.1</cite>], Extensible Markup Language (XML) 1.1 (Second Edition), Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, Fran&#xe7;ois Yergeau, John Cowan, 2006. W3C Recommendation available at: http://www.w3.org/TR/2006/REC-xml11-20060816/.
; XML Schema part 1
: [http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/ <cite id="ref-xschema-1">XML Schema Part 1: Structures</cite>], Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2004. W3C Recommendation available at: http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/.
; XML Schema part 2
: [http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/ <cite id="ref-xschema-2">XML Schema Part 2: Datatypes</cite>], Paul V. Biron, Ashok Malhotra, 2004. W3C Recommendation available at: http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.
; Unicode Collation Algorithm
: [http://www.unicode.org/unicode/reports/tr10/ <cite id="ref-unicode-collation">Unicode Technical Standard #10, Unicode Collation Algorithm</cite>], Available at: http://www.unicode.org/unicode/reports/tr10/.
; <span id="def-QNameButNotNCName">QNameButNotNCName</span>
: <nowiki>[Definition:</nowiki> A [http://www.w3.org/TR/REC-xml-names/#NT-QName QName] that is not an [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]. In 2006, the W3C named this a [http://www.w3.org/TR/REC-xml-names/#NT-PrefixedName PrefixedName]. <nowiki>]</nowiki>

</div><div class="div2">

===Informative References===

; EXSLT
: [http://www.exslt.org <cite>EXSLT Web site</cite>]. Available at http://www.exslt.org.

</div></div><div class="div1">

{{:Acknowledgements20}}

{{:ProductionNotes}}

</div>
</div>