Package net.sf.saxon.expr

## Class SystemFunctionCall

- java.lang.Object
- - net.sf.saxon.expr.Expression
  - - net.sf.saxon.expr.FunctionCall
    - - net.sf.saxon.expr.StaticFunctionCall
      - - net.sf.saxon.expr.SystemFunctionCall

- All Implemented Interfaces:
    `Callable`, `ExportAgent`, `Locatable`, `Negatable`, `IdentityComparable`, `Traceable`
  Direct Known Subclasses:
    `SystemFunctionCall.Optimized`

      public class SystemFunctionCall
      extends StaticFunctionCall
      implements Negatable

  A call to a system-defined function (specifically, a function implemented as an instance of `SystemFunction`)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `SystemFunctionCall.Optimized` | Subclass representing a system function call that has been optimized; this overrides the optimize() method to do nothing, thus ensuring that optimization converges.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `Evaluator[]` | `argumentEvaluators` |

    - ### 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
    --- | ---
    `SystemFunctionCall​(SystemFunction target, Expression[] arguments)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `PathMap.PathMapNodeSet` | `addToPathMap​(PathMap pathMap, PathMap.PathMapNodeSet pathMapNodeSet)` | Add a representation of this expression to a PathMap.
    `void` | `allocateArgumentEvaluators​(Expression[] arguments)` |
    `protected int` | `computeCardinality()` | Compute the static cardinality of this expression
    `protected int` | `computeSpecialProperties()` | Compute the special properties of this expression.
    `Expression` | `copy​(RebindingMap rebindings)` | Copy an expression.
    `Sequence[]` | `evaluateArguments​(XPathContext context)` |
    `void` | `export​(ExpressionPresenter out)` | Diagnostic print of expression structure.
    `java.lang.String` | `getExpressionName()` | Get a name identifying the kind of expression, in terms meaningful to a user.
    `IntegerValue[]` | `getIntegerBounds()` | For an expression that returns an integer or a sequence of integers, get a lower and upper bound on the values of the integers that may be returned, from static analysis.
    `int` | `getIntrinsicDependencies()` | Compute the dependencies of an expression, as the union of the dependencies of its subexpressions.
    `ItemType` | `getItemType()` | Determine the data type of the expression, if possible.
    `int` | `getNetCost()` | Return the estimated cost of evaluating an expression.
    `Expression` | `getScopingExpression()` | Get the innermost scoping expression of this expression, for expressions that directly depend on something in the dynamic context.
    `SystemFunction` | `getTargetFunction()` | Get the target function to be called
    `boolean` | `isLiftable​(boolean forStreaming)` | Ask whether the expression can be lifted out of a loop, assuming it has no dependencies on the controlling variable/focus of the loop
    `boolean` | `isNegatable​(TypeHierarchy th)` | Check whether this specific instance of the expression is negatable
    `boolean` | `isVacuousExpression()` | Determine whether this is a vacuous expression as defined in the XQuery update specification
    `Expression` | `negate()` | Create an expression that returns the negation of this expression
    `Expression` | `optimize​(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo)` | Perform optimisation of an expression and its subexpressions.
    `Expression` | `preEvaluate​(ExpressionVisitor visitor)` | Pre-evaluate a function at compile time.
    `void` | `process​(Outputter output, XPathContext context)` | Process the instruction, without returning any tail calls
    `void` | `resetLocalStaticProperties()` | Reset the static properties of the expression to -1, so that they have to be recomputed next time they are used.
    `void` | `setRetainedStaticContext​(RetainedStaticContext rsc)` | Set the retained static context
    `Pattern` | `toPattern​(Configuration config)` | Convert this expression to an equivalent XSLT pattern
    `Expression` | `typeCheck​(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo)` | Type-check the expression.
    `Expression` | `unordered​(boolean retainAllNodes, boolean forStreaming)` | Replace this expression by a simpler expression that delivers the results without regard to order.

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

      `call, getFunctionName, getStaticUType, getTargetFunction, isCallOn`

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

      `addExternalFunctionCallToPathMap, adjustRequiredType, checkArgumentCount, checkArguments, checkFunctionCall, computeHashCode, equals, getArg, getArguments, getArity, getDisplayName, getImplementationMethod, getOperanda, iterate, operands, pluralArguments, preEvaluateIfConstant, setArg, setArguments, setOperanda, setOperanda, simplifyArguments, toShortString, toString`

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

      `adoptChildExpression, allowExtractingCommonSubexpressions, checkedOperands, checkForUpdatingSubexpressions, checkPermittedContents, computeDependencies, computeStaticProperties, dynamicError, effectiveBooleanValue, evaluateAsString, evaluateItem, evaluatePendingUpdates, explain, getCardinality, getConfiguration, getCost, getDependencies, getEvaluationMethod, getExtraProperty, getInterpretedExpression, getLocalRetainedStaticContext, getLocation, getObjectName, getPackageData, getParentExpression, getProperties, getProperty, getRetainedStaticContext, getSlotsUsed, getSpecialProperties, getStaticBaseURI, getStaticBaseURIString, getStaticType, getStreamerName, getTracingTag, hasCompatibleStaticContext, hashCode, hasSpecialProperty, hasVariableBinding, identityHashCode, implementsStaticTypeCheck, isEqual, isIdentical, isInstruction, isMultiThreaded, isStaticPropertiesKnown, isSubtreeExpression, isUpdatingExpression, markTailFunctionCalls, operandList, operandSparseList, optimizeChildren, prepareForStreaming, restoreParentPointers, setEvaluationMethod, setExtraProperty, setFiltered, setFlattened, setLocation, setParentExpression, setRetainedStaticContextLocally, setRetainedStaticContextThoroughly, setStaticProperty, simplify, simplifyChildren, staticTypeCheck, suppressValidation, typeCheckChildren, typeError, 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`

- - ### Field Detail

    - #### argumentEvaluators

          public Evaluator[] argumentEvaluators

  - ### Constructor Detail

    - #### SystemFunctionCall

          public SystemFunctionCall​(SystemFunction target,
                                    Expression[] arguments)

  - ### Method Detail

    - #### setRetainedStaticContext

          public void setRetainedStaticContext​(RetainedStaticContext rsc)

      Set the retained static context
      Overrides:
        `setRetainedStaticContext` in class `Expression`
      Parameters:
        `rsc` - the static context to be retained

    - #### preEvaluate

          public Expression preEvaluate​(ExpressionVisitor visitor)
                                 throws XPathException

      Pre-evaluate a function at compile time. Functions that do not allow pre-evaluation, or that need access to context information, can prevent early evaluation by setting the LATE bit in the function properties.
      Overrides:
        `preEvaluate` in class `FunctionCall`
      Parameters:
        `visitor` - an expression visitor
      Returns:
        the result of the early evaluation, or the original expression, or potentially a simplified expression
      Throws:
        `XPathException` - if evaluation fails

    - #### typeCheck

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

      Type-check the expression. This also calls preEvaluate() to evaluate the function if all the arguments are constant; functions that do not require this behavior can override the preEvaluate method.
      Overrides:
        `typeCheck` in class `StaticFunctionCall`
      Parameters:
        `visitor` - the expression visitor
        `contextInfo` - information about the type of the context item
      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)

    - #### allocateArgumentEvaluators

          public void allocateArgumentEvaluators​(Expression[] arguments)

    - #### getTargetFunction

          public SystemFunction getTargetFunction()

      Description copied from class: `StaticFunctionCall`
      Get the target function to be called
      Overrides:
        `getTargetFunction` in class `StaticFunctionCall`
      Returns:
        the target function

    - #### getIntrinsicDependencies

          public int getIntrinsicDependencies()

      Compute the dependencies of an expression, as the union of the dependencies of its subexpressions. (This is overridden for path expressions and filter expressions, where the dependencies of a subexpression are not all propogated). This method should be called only once, to compute the dependencies; after that, getDependencies should be used.
      Overrides:
        `getIntrinsicDependencies` in class `Expression`
      Returns:
        the depencies, as a bit-mask

    - #### computeCardinality

          protected int computeCardinality()

      Compute the static cardinality of this expression
      Overrides:
        `computeCardinality` in class `StaticFunctionCall`
      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`

    - #### computeSpecialProperties

          protected int computeSpecialProperties()

      Compute the special properties of this expression. These properties are denoted by a bit-significant integer, possible values are in class `StaticProperty`. The "special" properties are properties other than cardinality and dependencies, and most of them relate to properties of node sequences, for example whether the nodes are in document order.
      Overrides:
        `computeSpecialProperties` in class `Expression`
      Returns:
        the special properties, as a bit-significant integer

    - #### getNetCost

          public int getNetCost()

      Return the estimated cost of evaluating an expression. This is a very crude measure based on the syntactic form of the expression (we have no knowledge of data values). We take the cost of evaluating a simple scalar comparison or arithmetic expression as 1 (one), and we assume that a sequence has length 5. The resulting estimates may be used, for example, to reorder the predicates in a filter expression so cheaper predicates are evaluated first.
      Overrides:
        `getNetCost` in class `FunctionCall`
      Returns:
        the intrinsic cost of this operation, excluding the costs of evaluating the operands

    - #### getScopingExpression

          public Expression getScopingExpression()

      Description copied from class: `Expression`
      Get the innermost scoping expression of this expression, for expressions that directly depend on something in the dynamic context. For example, in the case of a local variable reference this is the expression that causes the relevant variable to be bound; for a context item expression it is the innermost focus-setting container. For expressions that have no intrinsic dependency on the dynamic context, the value returned is null; the scoping container for such an expression is the innermost scoping container of its operands.
      Overrides:
        `getScopingExpression` in class `Expression`
      Returns:
        the innermost scoping container of this expression

    - #### isLiftable

          public boolean isLiftable​(boolean forStreaming)

      Ask whether the expression can be lifted out of a loop, assuming it has no dependencies on the controlling variable/focus of the loop
      Overrides:
        `isLiftable` in class `Expression`
      Parameters:
        `forStreaming` - true if we are optimizing for streamed evaluation
      Returns:
        true if the expression can be loop lifted

    - #### optimize

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

      Description copied from class: `FunctionCall`
      Perform optimisation of an expression and its subexpressions.

      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 `FunctionCall`
      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)

    - #### isVacuousExpression

          public boolean isVacuousExpression()

      Description copied from class: `Expression`
      Determine whether this is a vacuous expression as defined in the XQuery update specification
      Overrides:
        `isVacuousExpression` in class `Expression`
      Returns:
        true if this expression is vacuous

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

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

    - #### copy

          public Expression copy​(RebindingMap rebindings)

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

    - #### getIntegerBounds

          public IntegerValue[] getIntegerBounds()

      For an expression that returns an integer or a sequence of integers, get a lower and upper bound on the values of the integers that may be returned, from static analysis. The default implementation returns null, meaning "unknown" or "not applicable". Other implementations return an array of two IntegerValue objects, representing the lower and upper bounds respectively. The values UNBOUNDED_LOWER and UNBOUNDED_UPPER are used by convention to indicate that the value may be arbitrarily large. The values MAX_STRING_LENGTH and MAX_SEQUENCE_LENGTH are used to indicate values limited by the size of a string or the size of a sequence.
      Overrides:
        `getIntegerBounds` in class `Expression`
      Returns:
        the lower and upper bounds of integer values in the result, or null to indicate unknown or not applicable.

    - #### isNegatable

          public boolean isNegatable​(TypeHierarchy th)

      Check whether this specific instance of the expression is negatable
      Specified by:
        `isNegatable` in interface `Negatable`
      Parameters:
        `th` - the TypeHierarchy (in case it's needed)
      Returns:
        true if it is

    - #### negate

          public Expression negate()

      Create an expression that returns the negation of this expression
      Specified by:
        `negate` in interface `Negatable`
      Returns:
        the negated expression
      Throws:
        `java.lang.UnsupportedOperationException` - if isNegatable() returns false

    - #### unordered

          public Expression unordered​(boolean retainAllNodes,
                                      boolean forStreaming)
                               throws XPathException

      Replace this expression by a simpler expression that delivers the results without regard to order.
      Overrides:
        `unordered` in class `Expression`
      Parameters:
        `retainAllNodes` - set to true if the result must contain exactly the same nodes as the original; set to false if the result can eliminate (or introduce) duplicates.
        `forStreaming` - set to true if the result is to be optimized for streaming
      Returns:
        an expression that delivers the same nodes in a more convenient order
      Throws:
        `XPathException` - if the rewrite fails

    - #### addToPathMap

          public PathMap.PathMapNodeSet addToPathMap​(PathMap pathMap,
                                                     PathMap.PathMapNodeSet pathMapNodeSet)

      Add a representation of this expression to a PathMap. The PathMap captures a map of the nodes visited by an expression in a source tree.

      The default implementation of this method assumes that an expression does no navigation other than the navigation done by evaluating its subexpressions, and that the subexpressions are evaluated in the same context as the containing expression. The method must be overridden for any expression where these assumptions do not hold. For example, implementations exist for AxisExpression, ParentExpression, and RootExpression (because they perform navigation), and for the doc(), document(), and collection() functions because they create a new navigation root. Implementations also exist for PathExpression and FilterExpression because they have subexpressions that are evaluated in a different context from the calling expression.

      Overrides:
        `addToPathMap` in class `Expression`
      Parameters:
        `pathMap` - the PathMap to which the expression should be added
        `pathMapNodeSet` - the PathMapNodeSet to which the paths embodied in this expression should be added
      Returns:
        the pathMapNodeSet representing the points in the source document that are both reachable by this expression, and that represent possible results of this expression. For an expression that does navigation, it represents the end of the arc in the path map that describes the navigation route. For other expressions, it is the same as the input pathMapNode.

    - #### toPattern

          public Pattern toPattern​(Configuration config)
                            throws XPathException

      Convert this expression to an equivalent XSLT pattern
      Overrides:
        `toPattern` in class `Expression`
      Parameters:
        `config` - the Saxon configuration
      Returns:
        the equivalent pattern
      Throws:
        `XPathException` - if conversion is not possible

    - #### evaluateArguments

          public Sequence[] evaluateArguments​(XPathContext context)
                                       throws XPathException

      Overrides:
        `evaluateArguments` in class `FunctionCall`
      Throws:
        `XPathException`

    - #### resetLocalStaticProperties

          public void resetLocalStaticProperties()

      Description copied from class: `Expression`
      Reset the static properties of the expression to -1, so that they have to be recomputed next time they are used.
      Overrides:
        `resetLocalStaticProperties` in class `Expression`

    - #### process

          public void process​(Outputter output,
                              XPathContext context)
                       throws XPathException

      Description copied from class: `Expression`
      Process the instruction, without returning any tail calls
      Overrides:
        `process` in class `Expression`
      Parameters:
        `output` - the destination for the result
        `context` - The dynamic context, giving access to the current node, the current variables, etc.
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### getExpressionName

          public java.lang.String getExpressionName()

      Get a name identifying the kind of expression, in terms meaningful to a user.
      Overrides:
        `getExpressionName` in class `StaticFunctionCall`
      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 explain() output displaying the expression.

    - #### export

          public void export​(ExpressionPresenter out)
                      throws XPathException

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