XML Path Language (XPath) 4.0 WG Review Draft

3.4.4 Function Coercion

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

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

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

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

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

   Note:

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

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

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

4. Function coercion then returns a new function item with the following properties (as defined in Section 7.1 Function Items^DM):

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

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

     Note:

     See also 4.5.7 Function Identity.

   • parameter names: The parameter names of F.

   • parameter names: The parameter names of F.

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

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

   • nonlocal variable bindings: An empty mapping.

These rules have the following consequences:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Consider the following expression:

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

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

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

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

4.5.4 Partial Function Application

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

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

In each case, the result of a partial function application is a function item, whose arity is equal to the number of placeholders in the call.

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

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

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

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

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

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

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

   Note:

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

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

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

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

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

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

4. The result is a partially applied function having the following properties (which are defined in Section 7.1 Function Items^DM):

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

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

     Note:

     See also 4.5.7 Function Identity.

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

   • parameter names: The names of the parameters of FD that have been identified as placeholder parameters, retaining the order in which the placeholders appear in the function call.

     Note:

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

   • parameter names: The names of the parameters of FD that have been identified as placeholder parameters, retaining the order in which the placeholders appear in the function call.

     Note:

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

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

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

   • annotations: The annotations of FD.

   • body: The body of FD.

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

   Note:

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

   Example: Partial Application of a System Function

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

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

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

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

1. The function itemFI to be partially applied is determined in the same way as for a dynamic function call without placeholders, as described in 4.5.3 Dynamic Function Calls. For this purpose an ArgumentPlaceholder contributes to the count of arguments.

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

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

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

   Note:

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

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

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

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

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

4. The result of the partial function application is a partially applied function with the following properties (which are defined in Section 7.1 Function Items^DM):

   • name: Absent.

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

   • parameter names: The names of parameters in FI that have been identified as placeholder parameters, in order.

     Note:

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

   • parameter names: The names of parameters in FI that have been identified as placeholder parameters, in order.

     Note:

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

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

   • annotations: The annotations of FI.

   • body: The body of FI.

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

   Note:

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

   Example: Partial Application of an Anonymous Function

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

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

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

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

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

4.5.5 Named Function References

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

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

If the EQName is a lexical QName, it is expanded using the default function namespace in the static context.

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

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

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

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

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

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

• name: The name of FD.

• identity:

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

    Note:

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

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

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

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

  Note:

  See also 4.5.7 Function Identity.

• arity: As specified in the named function reference.

• parameter names: The first A parameter names of FD, where A is the required arity.

• parameter names: The first A parameter names of FD, where A is the required arity.

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

• annotations: The annotations of FD.

• body: The body of FD.

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

  Note:

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

The following are examples of named function references:

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

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

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

4.5.6 Inline Function Expressions

[Definition: An inline function expression, when evaluated, creates an anonymous function defined directly in the inline function expression.] An inline function expression specifies the names and SequenceTypes of the parameters to the function, the SequenceType of the result, and the body of the function.

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

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

The keywords function and fn are synonymous.

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

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

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

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

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

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

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

The annotation keyword %method is described in 4.5.6.1 Methods.

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

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

The result of an inline function expression is a single function item with the following properties (as defined in Section 7.1 Function Items^DM):

• name: Absent.

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

  Note:

  See also 4.5.7 Function Identity.

• parameter names: The parameter names in the InlineFunctionExpr’s ParamList.

• parameter names: The parameter names in the InlineFunctionExpr’s ParamList.

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

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

• body: The FunctionBody of the InlineFunctionExpr.

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

The following are examples of some inline function expressions:

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

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

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

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

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

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

  The result of this expression is 6