XQuery 4.0: An XML Query Language

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

   • 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: An empty set. The annotations of FD are not retained.annotations: The annotations of FD.annotations: An empty set. The annotations of FD are not retained.

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

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

   • 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: An empty set. The annotations of FI are not retained.annotations: The annotations of FI.annotations: An empty set. The annotations of FI are not retained.

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

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