Returns the function having a given name and arity, if there is one.
fn:function-lookup( $name as xs:QName,$arity as xs:integerfunction(*)?A call to fn:function-lookup returns the function obtained by looking up
the expanded QName supplied as $name and the arity supplied as
$arity in the named functions component of the dynamic context
(specifically, the dynamic context of the call to fn:function-lookup).
Furthermore, if that function has an implementation-dependent implementation (see note
below), then the implementation of the function returned by
fn:function-lookup is associated with the static and dynamic context of
the call to fn:function-lookup.
The above rule deliberately uses the same wording as the corresponding rule for Named Function References. The term "a function [with] an implementation-dependent implementation" essentially means a function whose implementation is provided by the language processor rather than by the stylesheet or query author. This rule is therefore relevant to built-in functions and vendor-supplied extension functions whose result depends on the context of the function call.
Otherwise (if no known function can be identified by name and arity), an empty sequence is returned.
If the arguments to fn:function-lookup identify a function that is present
in the static context of the function call, the function will always return the same
function that a static reference to this function would bind to. If there is no such
function in the static context, then the results depend on what is present in the
dynamic context, which is implementation-defined.
The expression fn:function-lookup(xs:QName('fn:substring'), 2)('abcd',
2) returns 'bcd'.
The expression (fn:function-lookup(xs:QName('xs:dateTimeStamp'), 1),
xs:dateTime#1)[1] ('2011-11-11T11:11:11Z') returns an
xs:dateTime value set to the specified date, time, and timezone; if
the implementation supports XSD 1.1 then the result will be an instance of the
derived type xs:dateTimeStamp. The query is written to ensure that no
failure occurs when the implementation does not recognize the type
xs:dateTimeStamp.
The expression let $f := fn:function-lookup(xs:QName('zip:binary-entry'), 2)
return if (exists($f)) then $f($href, $entry) else () returns the result of
calling zip:binary-entry($href, $entry) if the function is available, or
an empty sequence otherwise.
This function can be useful where there is a need to make a dynamic decision on which of several statically-known functions to call. It can thus be used as a substitute for polymorphism, in the case where the application has been designed so several functions implement the same interface.
The function can also be useful in cases where a query or stylesheet module is written
to work with alternative versions of a library module. In such cases the author of the
main module might wish to test whether an imported library module contains or does not
contain a particular function, and to call a function in that module only if it is
available in the version that was imported. A static call would cause a static error if
the function is not available, whereas getting the function using
fn:function-lookup allows the caller to take fallback action in this
situation.
If the function that is retrieved by fn:function-lookup is context-dependent, that is, if it has
dependencies on the static or dynamic context of its caller, the context that applies is
the static and/or dynamic context of the call to the fn:function-lookup
function itself. The context thus effectively forms part of the closure of the returned
function. In practice this applies only where the target of
fn:function-lookup is a built-in function, because user-defined
functions never depend on the static or dynamic context of the function call. The rule
applies recursively, since fn:function-lookup is itself a context-dependent
built-in function.
These specifications do not define any circumstances in which the dynamic context will contain functions that are not present in the static context, but neither do they rule this out. For example an API may provide the ability to add functions to the dynamic context. Equally, these specifications do not define any mechanism for creating context-dependent functions other than the built-in context-dependent functions, but neither do they rule out the existence of such functions.
The mere fact that a function exists and has a name does not of itself mean that the
function is present in the dynamic context. For example, functions obtained through
use of the fn:load-xquery-module function are not added to the dynamic context.