Package net.sf.saxon.expr

Class SystemFunctionCall

    • Method Detail

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

      • 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

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

      • process

        public void process​(Outputter output,
                    XPathContext context)
             throws XPathException
        Description copied from class: Expression
        Process the instruction
        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

      • call

        public Sequence call​(XPathContext context,
                     Sequence[] arguments)
              throws XPathException
        Description copied from class: StaticFunctionCall
        Call the Callable.
        Specified by:
        call in interface Callable
        Overrides:
        call in class StaticFunctionCall
        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 methd 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()
        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.

      • isUpdatingExpression

        public boolean isUpdatingExpression()
        Determine whether this is an updating expression as defined in the XQuery update specification
        Overrides:
        isUpdatingExpression in class Expression
        Returns:
        true if this is an updating 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.