Package net.sf.saxon.functions.hof

## Class UserFunctionReference

- java.lang.Object
- - net.sf.saxon.expr.Expression
  - - net.sf.saxon.functions.hof.UserFunctionReference

- All Implemented Interfaces:
    `Callable`, `ComponentInvocation`, `ExportAgent`, `Locatable`, `UserFunctionResolvable`, `IdentityComparable`, `Traceable`

      public class UserFunctionReference
      extends Expression
      implements ComponentInvocation, UserFunctionResolvable, Callable

  A UserFunctionReference is an expression in the form local:f#1 where local:f is a user-defined function. Evaluating the expression returns a function item. The reason that UserFunctionReference is treated as an expression rather than a value is that the binding to the actual function may be deferred, for example if the function is overridden in a different package.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `UserFunctionReference.BoundUserFunction` | A BoundUserFunction represents a user-defined function seen as a component.

  - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.expr.Expression

      `EFFECTIVE_BOOLEAN_VALUE, EVALUATE_METHOD, ITEM_FEED_METHOD, ITERATE_METHOD, MAX_COST, MAX_SEQUENCE_LENGTH, MAX_STRING_LENGTH, PROCESS_METHOD, staticProperties, UNBOUNDED_LOWER, UNBOUNDED_UPPER, UPDATE_METHOD, WATCH_METHOD`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `UserFunctionReference​(UserFunction target)` |
    `UserFunctionReference​(SymbolicName name)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Function` | `call​(XPathContext context, Sequence[] arguments)` | Call the Callable.
    `protected int` | `computeCardinality()` | Compute the static cardinality of this expression
    `Expression` | `copy​(RebindingMap rebindings)` | Copy an expression.
    `Function` | `evaluateItem​(XPathContext context)` | Evaluate an expression as a single item.
    `void` | `export​(ExpressionPresenter out)` | Diagnostic print of expression structure.
    `int` | `getArity()` | Get the arity of the function
    `int` | `getBindingSlot()` | Get the binding slot to be used.
    `java.lang.String` | `getExpressionName()` | Get a name identifying the kind of expression, in terms meaningful to a user.
    `Component` | `getFixedTarget()` | Get the target component if this is known in advance, that is, if the target component is private or final.
    `FunctionItemType` | `getFunctionItemType​(TypeHierarchy th)` | Get the item type of the function item
    `StructuredQName` | `getFunctionName()` | Get the name of the function, or null if it is anonymous
    `int` | `getImplementationMethod()` | An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process().
    `ItemType` | `getItemType()` | Determine the data type of the expression, if possible.
    `UserFunction` | `getNominalTarget()` |
    `UType` | `getStaticUType​(UType contextItemType)` | Get the static type of the expression as a UType, following precisely the type inference rules defined in the XSLT 3.0 specification.
    `SymbolicName` | `getSymbolicName()` | Get the symbolic name of the component that this invocation references
    `Expression` | `optimize​(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo)` | Perform optimisation of an expression and its subexpressions.
    `void` | `setBindingSlot​(int slot)` | Set the binding slot to be used.
    `void` | `setFunction​(UserFunction function)` |
    `Expression` | `simplify()` | Simplify an expression.
    `java.lang.String` | `toShortString()` | Produce a short string identifying the expression for use in error messages
    `java.lang.String` | `toString()` | The toString() method for an expression attempts to give a representation of the expression in an XPath-like form.
    `Expression` | `typeCheck​(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo)` | Perform type checking of an expression and its subexpressions.

    - ### Methods inherited from class net.sf.saxon.expr.Expression

      `addToPathMap, adoptChildExpression, allowExtractingCommonSubexpressions, checkedOperands, checkForUpdatingSubexpressions, checkPermittedContents, computeDependencies, computeHashCode, computeSpecialProperties, computeStaticProperties, dynamicError, effectiveBooleanValue, equals, evaluateAsString, evaluatePendingUpdates, explain, getCardinality, getConfiguration, getCost, getDependencies, getEvaluationMethod, getExtraProperty, getIntegerBounds, getInterpretedExpression, getIntrinsicDependencies, getLocalRetainedStaticContext, getLocation, getNetCost, getObjectName, getPackageData, getParentExpression, getProperties, getProperty, getRetainedStaticContext, getScopingExpression, getSlotsUsed, getSpecialProperties, getStaticBaseURI, getStaticBaseURIString, getStaticType, getStreamerName, getTracingTag, hasCompatibleStaticContext, hashCode, hasSpecialProperty, hasVariableBinding, identityHashCode, implementsStaticTypeCheck, isCallOn, isEqual, isIdentical, isInstruction, isLiftable, isMultiThreaded, isStaticPropertiesKnown, isSubtreeExpression, isUpdatingExpression, isVacuousExpression, iterate, markTailFunctionCalls, operandList, operands, operandSparseList, optimizeChildren, prepareForStreaming, process, resetLocalStaticProperties, restoreParentPointers, setEvaluationMethod, setExtraProperty, setFiltered, setFlattened, setLocation, setParentExpression, setRetainedStaticContext, setRetainedStaticContextLocally, setRetainedStaticContextThoroughly, setStaticProperty, simplifyChildren, staticTypeCheck, suppressValidation, toPattern, typeCheckChildren, typeError, unordered, verifyParentPointers`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface net.sf.saxon.trace.Traceable

      `gatherProperties`

- - ### Constructor Detail

    - #### UserFunctionReference

          public UserFunctionReference​(UserFunction target)

    - #### UserFunctionReference

          public UserFunctionReference​(SymbolicName name)

  - ### Method Detail

    - #### setFunction

          public void setFunction​(UserFunction function)

      Specified by:
        `setFunction` in interface `UserFunctionResolvable`

    - #### simplify

          public Expression simplify()
                              throws XPathException

      Description copied from class: `Expression`
      Simplify an expression. This performs any static optimization (by rewriting the expression as a different expression). The default implementation simplifies its operands.
      Overrides:
        `simplify` in class `Expression`
      Returns:
        the simplified expression (or the original if unchanged, or if modified in-situ)
      Throws:
        `XPathException` - if an error is discovered during expression rewriting

    - #### typeCheck

          public Expression typeCheck​(ExpressionVisitor visitor,
                                      ContextItemStaticInfo contextInfo)
                               throws XPathException

      Perform type checking of an expression and its subexpressions. This is the second phase of static optimization.

      This checks statically that the operands of the expression have the correct type; if necessary it generates code to do run-time type checking or type conversion. A static type error is reported only if execution cannot possibly succeed, that is, if a run-time type error is inevitable. The call may return a modified form of the expression.

      This method is called after all references to functions and variables have been resolved to the declaration of the function or variable. However, the types of such functions and variables may not be accurately known if they have not been explicitly declared.

      Overrides:
        `typeCheck` in class `Expression`
      Parameters:
        `visitor` - an expression visitor
        `contextInfo` - Information available statically about the context item: whether it is (possibly) absent; its static type; its streaming posture.
      Returns:
        the original expression, rewritten to perform necessary run-time type checks, and to perform other type-related optimizations
      Throws:
        `XPathException` - if an error is discovered during this phase (typically a type error)

    - #### optimize

          public Expression optimize​(ExpressionVisitor visitor,
                                     ContextItemStaticInfo contextInfo)
                              throws XPathException

      Perform optimisation of an expression and its subexpressions. This is the third and final phase of static optimization.

      This method is called after all references to functions and variables have been resolved to the declaration of the function or variable, and after all type checking has been done.

      Overrides:
        `optimize` in class `Expression`
      Parameters:
        `visitor` - an expression visitor
        `contextInfo` - the static type of "." at the point where this expression is invoked. The parameter is set to null if it is known statically that the context item will be undefined. If the type of the context item is not known statically, the argument is set to `Type.ITEM_TYPE`
      Returns:
        the original expression, rewritten if appropriate to optimize execution
      Throws:
        `XPathException` - if an error is discovered during this phase (typically a type error)

    - #### getBindingSlot

          public int getBindingSlot()

      Get the binding slot to be used. This is the offset within the binding vector of the containing component where the actual target component is to be found.
      Specified by:
        `getBindingSlot` in interface `ComponentInvocation`
      Returns:
        the offset in the binding vector of the containing package where the target component can be found.

    - #### getFixedTarget

          public Component getFixedTarget()

      Get the target component if this is known in advance, that is, if the target component is private or final. Otherwise, return null.
      Specified by:
        `getFixedTarget` in interface `ComponentInvocation`
      Returns:
        the bound component if the binding has been fixed

    - #### getNominalTarget

          public UserFunction getNominalTarget()

    - #### setBindingSlot

          public void setBindingSlot​(int slot)

      Set the binding slot to be used. This is the offset within the binding vector of the containing component where the actual target component is to be found. The target template is not held directly in the invocation instruction/expression itself because it can be overridden in a using package.
      Specified by:
        `setBindingSlot` in interface `ComponentInvocation`
      Parameters:
        `slot` - the offset in the binding vector of the containing package where the target component can be found.

    - #### getSymbolicName

          public SymbolicName getSymbolicName()

      Get the symbolic name of the component that this invocation references
      Specified by:
        `getSymbolicName` in interface `ComponentInvocation`
      Returns:
        the symbolic name of the target component

    - #### getFunctionItemType

          public FunctionItemType getFunctionItemType​(TypeHierarchy th)

      Get the item type of the function item
      Parameters:
        `th` - the type hierarchy cache
      Returns:
        the function item's type

    - #### getFunctionName

          public StructuredQName getFunctionName()

      Get the name of the function, or null if it is anonymous
      Returns:
        the function name, or null for an anonymous inline function

    - #### getArity

          public int getArity()

      Get the arity of the function
      Returns:
        the number of arguments in the function signature

    - #### computeCardinality

          protected int computeCardinality()

      Compute the static cardinality of this expression
      Specified by:
        `computeCardinality` in class `Expression`
      Returns:
        the computed cardinality, as one of the values `StaticProperty.ALLOWS_ZERO_OR_ONE`, `StaticProperty.EXACTLY_ONE`, `StaticProperty.ALLOWS_ONE_OR_MORE`, `StaticProperty.ALLOWS_ZERO_OR_MORE`

    - #### getImplementationMethod

          public int getImplementationMethod()

      An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process(). This method indicates which of these methods is provided directly. The other methods will always be available indirectly, using an implementation that relies on one of the other methods.
      Specified by:
        `getImplementationMethod` in class `Expression`
      Returns:
        the implementation method, for example `Expression.ITERATE_METHOD` or `Expression.EVALUATE_METHOD` or `Expression.PROCESS_METHOD`

    - #### getItemType

          public ItemType getItemType()

      Determine the data type of the expression, if possible. All expression return sequences, in general; this method determines the type of the items within the sequence, assuming that (a) this is known in advance, and (b) it is the same for all items in the sequence.

      This method should always return a result, though it may be the best approximation that is available at the time.

      Specified by:
        `getItemType` in class `Expression`
      Returns:
        a value such as Type.STRING, Type.BOOLEAN, Type.NUMBER, Type.NODE, or Type.ITEM (meaning not known at compile time)

    - #### getStaticUType

          public UType getStaticUType​(UType contextItemType)

      Get the static type of the expression as a UType, following precisely the type inference rules defined in the XSLT 3.0 specification.
      Overrides:
        `getStaticUType` in class `Expression`
      Parameters:
        `contextItemType` - the static type of the context item
      Returns:
        the static item type of the expression according to the XSLT 3.0 defined rules

    - #### copy

          public Expression copy​(RebindingMap rebindings)

      Copy an expression. This makes a deep copy.
      Specified by:
        `copy` in class `Expression`
      Parameters:
        `rebindings` - variables that need to be re-bound
      Returns:
        the copy of the original expression

    - #### evaluateItem

          public Function evaluateItem​(XPathContext context)
                                throws XPathException

      Evaluate an expression as a single item. This always returns either a single Item or null (denoting the empty sequence). No conversion is done. This method should not be used unless the static type of the expression is a subtype of "item" or "item?": that is, it should not be called if the expression may return a sequence. There is no guarantee that this condition will be detected.
      Overrides:
        `evaluateItem` in class `Expression`
      Parameters:
        `context` - The context in which the expression is to be evaluated
      Returns:
        the node or atomic value that results from evaluating the expression; or null to indicate that the result is an empty sequence
      Throws:
        `XPathException` - if any dynamic error occurs evaluating the expression

    - #### call

          public Function call​(XPathContext context,
                               Sequence[] arguments)
                        throws XPathException

      Call the Callable.
      Specified by:
        `call` in interface `Callable`
      Parameters:
        `context` - the dynamic evaluation context
        `arguments` - the values of the arguments, supplied as Sequences.

        Generally it is advisable, if calling iterate() to process a supplied sequence, to call it only once; if the value is required more than once, it should first be converted to a `GroundedValue` by calling the utility method SequenceTool.toGroundedValue().

        If the expected value is a single item, the item should be obtained by calling Sequence.head(): it cannot be assumed that the item will be passed as an instance of `Item` or `AtomicValue`.

        It is the caller's responsibility to perform any type conversions required to convert arguments to the type expected by the callee. An exception is where this Callable is explicitly an argument-converting wrapper around the original Callable.

      Returns:
        the result of the evaluation, in the form of a Sequence. It is the responsibility of the callee to ensure that the type of result conforms to the expected result type.
      Throws:
        `XPathException` - if a dynamic error occurs during the evaluation of the expression

    - #### getExpressionName

          public java.lang.String getExpressionName()

      Description copied from class: `Expression`
      Get a name identifying the kind of expression, in terms meaningful to a user.
      Overrides:
        `getExpressionName` in class `Expression`
      Returns:
        a name identifying the kind of expression, in terms meaningful to a user. The name will always be in the form of a lexical XML QName, and should match the name used in export() output displaying the expression.

    - #### toString

          public java.lang.String toString()

      Description copied from class: `Expression`

      The toString() method for an expression attempts to give a representation of the expression in an XPath-like form.

      For subclasses of Expression that represent XPath expressions, the result should always be a string that parses as an XPath 3.0 expression. The expression produced should be equivalent to the original making certain assumptions about the static context. In general the expansion will make no assumptions about namespace bindings, except that (a) the prefix "xs" is used to refer to the XML Schema namespace, and (b) the default function namespace is assumed to be the "fn" namespace.

      In the case of XSLT instructions and XQuery expressions, the toString() method gives an abstracted view of the syntax that is not designed in general to be parseable.

      Overrides:
        `toString` in class `Expression`
      Returns:
        a representation of the expression as a string

    - #### toShortString

          public java.lang.String toShortString()

      Description copied from class: `Expression`
      Produce a short string identifying the expression for use in error messages
      Overrides:
        `toShortString` in class `Expression`
      Returns:
        a short string, sufficient to identify the expression

    - #### export

          public void export​(ExpressionPresenter out)
                      throws XPathException

      Description copied from class: `Expression`
      Diagnostic print of expression structure. The abstract expression tree is written to the supplied output destination.
      Specified by:
        `export` in interface `ExportAgent`
      Specified by:
        `export` in class `Expression`
      Parameters:
        `out` - the expression presenter used to display the structure
      Throws:
        `XPathException` - if the export fails, for example if an expression is found that won't work in the target environment.