Package net.sf.saxon.functions.hof

## Class CoercedFunction

- java.lang.Object
- - net.sf.saxon.functions.AbstractFunction
  - - net.sf.saxon.functions.hof.CoercedFunction

- All Implemented Interfaces:
    `Callable`, `Function`, `GroundedValue`, `Item`, `Sequence`

      public class CoercedFunction
      extends AbstractFunction

  A function item obtained by coercing a supplied function; this adds a wrapper to perform dynamic type checking of the arguments in any call, and type checking of the result.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `CoercedFunction​(Function targetFunction, SpecificFunctionType requiredType)` | Create a CoercedFunction as a wrapper around a target function
    `CoercedFunction​(SpecificFunctionType requiredType)` | Create a CoercedFunction whose target function is not yet known (happens during package re-loading)

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Sequence` | `call​(XPathContext context, Sequence[] args)` | Invoke the function
    `static CoercedFunction` | `coerce​(Function suppliedFunction, SpecificFunctionType requiredType, RoleDiagnostic role)` | Factory method to create a CoercedFunction with a given type, for a given targetFunction.
    `void` | `export​(ExpressionPresenter out)` | Export information about this function item to the SEF file
    `AnnotationList` | `getAnnotations()` | Get the function annotations (as defined in XQuery).
    `int` | `getArity()` | Get the arity of the function
    `java.lang.String` | `getDescription()` | Get a description of this function for use in error messages.
    `FunctionItemType` | `getFunctionItemType()` | Get the item type of the function item
    `StructuredQName` | `getFunctionName()` | Get the name of the function, or null if it is anonymous
    `void` | `setTargetFunction​(Function targetFunction)` | Set the target function
    `void` | `typeCheck​(ExpressionVisitor visitor, ContextItemStaticInfo contextItemType)` | Type check the function (may modify it by adding code for converting the arguments)

    - ### Methods inherited from class net.sf.saxon.functions.AbstractFunction

      `atomize, deepEquals, effectiveBooleanValue, getOperandRoles, getStringValue, getStringValueCS, isArray, isMap, isTrustedResultType, makeNewContext, simplify`

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface net.sf.saxon.om.Function

      `getGenre, toShortString`

    - ### Methods inherited from interface net.sf.saxon.om.GroundedValue

      `asIterable, concatenate, containsNode, materialize`

    - ### Methods inherited from interface net.sf.saxon.om.Item

      `getLength, head, isStreamed, itemAt, iterate, reduce, subsequence`

    - ### Methods inherited from interface net.sf.saxon.om.Sequence

      `makeRepeatable`

- - ### Constructor Detail

    - #### CoercedFunction

          public CoercedFunction​(Function targetFunction,
                                 SpecificFunctionType requiredType)
                          throws XPathException

      Create a CoercedFunction as a wrapper around a target function
      Parameters:
        `targetFunction` - the function to be wrapped by a type-checking layer
        `requiredType` - the type of the coerced function, that is the type required by the context in which the target function is being used
      Throws:
        `XPathException` - if the arity of the supplied function does not match the arity of the required type

    - #### CoercedFunction

          public CoercedFunction​(SpecificFunctionType requiredType)

      Create a CoercedFunction whose target function is not yet known (happens during package re-loading)
      Parameters:
        `requiredType` - the type of the coerced function, that is the type required by the context in which the target function is being used

  - ### Method Detail

    - #### setTargetFunction

          public void setTargetFunction​(Function targetFunction)
                                 throws XPathException

      Set the target function
      Parameters:
        `targetFunction` - the function to be wrapped by a type-checking layer
      Throws:
        `XPathException` - if the arity of the supplied function does not match the arity of the required type

    - #### typeCheck

          public void typeCheck​(ExpressionVisitor visitor,
                                ContextItemStaticInfo contextItemType)
                         throws XPathException

      Type check the function (may modify it by adding code for converting the arguments)
      Overrides:
        `typeCheck` in class `AbstractFunction`
      Parameters:
        `visitor` - the expression visitor, supplies context information
        `contextItemType` - the context item type at the point where the function definition appears
      Throws:
        `XPathException` - if type checking of the target function fails

    - #### getFunctionItemType

          public FunctionItemType getFunctionItemType()

      Get the item type of the function item
      Returns:
        the function item's type

    - #### getFunctionName

          public StructuredQName getFunctionName()

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

    - #### getDescription

          public java.lang.String getDescription()

      Get a description of this function for use in error messages. For named functions, the description is the function name (as a lexical QName). For others, it might be, for example, "inline function", or "partially-applied ends-with function".
      Returns:
        a description of the function for use in error messages

    - #### getArity

          public int getArity()

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

    - #### getAnnotations

          public AnnotationList getAnnotations()

      Description copied from interface: `Function`
      Get the function annotations (as defined in XQuery). Returns an empty list if there are no function annotations.
      Specified by:
        `getAnnotations` in interface `Function`
      Overrides:
        `getAnnotations` in class `AbstractFunction`
      Returns:
        the function annotations

    - #### call

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

      Invoke the function
      Parameters:
        `context` - the XPath dynamic evaluation context
        `args` - the actual arguments to be supplied
      Returns:
        the result of invoking the function
      Throws:
        `XPathException` - if execution of the function fails

    - #### coerce

          public static CoercedFunction coerce​(Function suppliedFunction,
                                               SpecificFunctionType requiredType,
                                               RoleDiagnostic role)
                                        throws XPathException

      Factory method to create a CoercedFunction with a given type, for a given targetFunction. It is assumed that we have already established that coercion is needed. Called from Bytecode compiler.
      Parameters:
        `suppliedFunction` - the function to be coerced
        `requiredType` - the target type for the coercion
        `role` - diagnostic information about the role of the expression being coerced
      Returns:
        the function after coercion
      Throws:
        `XPathException` - if the function cannot be coerced to the required type (for example, because it has the wrong arity)

    - #### export

          public void export​(ExpressionPresenter out)
                      throws XPathException

      Export information about this function item to the SEF file
      Specified by:
        `export` in interface `Function`
      Overrides:
        `export` in class `AbstractFunction`
      Parameters:
        `out` - the SEF output destination
      Throws:
        `XPathException`