Functions

A function call consists of the name of the function and a list of comma-separated expressions, which are the arguments to the function. Here is an example:

 fn:concat("http://www.example.com/auction/", "1001") 

This function call applies the built-in function fn:concat to the values of the literal expressions "http://www.example.com/auction/" and "1001" and returns the concatenation of its arguments.

A function's signature specifies the required types of its arguments and the type of its result. The XQuery specifications (see [XQ-FO]) provide the signatures for all built-in XQuery functions. Here is the signature for the function fn:concat :

 fn:concat($op1 as xs:string ?, $op2 as xs:string ?) as xs:string 

This signature specifies that the first and second argument to fn:concat must each be the empty sequence or a string and that the value returned will be a string. The signature serves as a contract between the function call and the function: The function call is required to provide an empty sequence or a string for each argument, and in turn the function guarantees to return a string. (The argument to fn:concat may be the empty sequence because the function treats the empty sequence as the zero-length string.)

A function call is well typed if the types of the argument expressions match the required types of the function's arguments declared in its signature. An argument type matches the required type if the argument type is derived from the required type or if the argument type can be promoted to the required type.

In the following examples of function calls, we assume the variable $resource is of any type derived from xs:string .

 fn:concat("http://www.example.com/auction/", $resource)  has type  xs:string fn:concat((), "http://www.example.com/auction/")  has type  xs:string fn:concat(10e1, $resource)  is a static type error  

The third example raises a type error because the literal expression 10e1 has type xs:double , which is not derived from or promotable to the required type xs:string ? .

A user -defined function consists of the function's signature and its body, which is an expression. A function definition is well typed if the type of the body expression matches the return type. Here is the function makeURI from Listing 4.4:

 define function makeURI ($resource as xs:string) as xs:anyURI {   xs:anyURI(fn:concat(xs:string($base), $resource)) } 

The function makeURI takes one string argument and returns one URI value. The function is well-typed because the type of its body is xs:anyURI , which matches the required return type.

As a convenience to programmers, XQuery permits operators and functions that require sequences of atomic values as arguments to be applied to any item sequence. Before applying the operator or function, the function fn:data is applied to convert the item sequence to a sequence of atomic values. Each atomic value in the item sequence is returned unchanged, and each node is converted to its typed value . In the XQuery specification, automatic conversion of arguments is called atomization . For example, an idref attribute defined in Listing 4.2 must contain one IDREF value. In the following examples of atomization, we assume the variable $idref has type attribute idref :

 makeURI($idref)  has type  xs:anyURI fn:concat("Item ID is:", $idref)  has type  xs:string $idref * 0.07  is a static type error  

The first and second function calls are both well typed, because the atomic content of $idref is xs:IDREF , which is derived from xs:string , and xs:string is the required type of makeURI and fn:concat . The third call is a static type error, because xs:idref is not derived from or promotable to any numeric type.