Package net.sf.saxon.expr.parser

## Class ExpressionTool

- java.lang.Object
- - net.sf.saxon.expr.parser.ExpressionTool

-     public class ExpressionTool
      extends java.lang.Object

  This class, ExpressionTool, contains a number of useful static methods for manipulating expressions. Most importantly, it provides the factory method make() for constructing a new expression

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `ExpressionTool.ExpressionSelector` | Callback for selecting expressions in the tree

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static int` | `allocateSlots​(Expression exp, int nextFree, SlotManager frame)` | Allocate slot numbers to range variables
    `static boolean` | `callsFunction​(Expression exp, StructuredQName qName, boolean sameFocusOnly)` | Determine whether an expression contains a call on the function with a given name
    `static boolean` | `changesXsltContext​(Expression exp)` | Determine whether an expression possible calls (directly or indirectly) xsl:result-document, or has other context dependencies that prevent function inlining, which we assume is true if it contains a template call.
    `static void` | `clearStreamabilityData​(Expression exp)` | Clear all computed streamability properties for an expression and its contained subtree
    `static void` | `computeEvaluationModesForUserFunctionCalls​(Expression exp)` | Compute argument evaluation modes for all calls on user defined functions with a specified expression
    `static boolean` | `contains​(Expression exp, boolean sameFocusOnly, java.util.function.Predicate<Expression> predicate)` | Test whether a given expression is, or contains, at any depth, an expression that satisfies a supplied condition
    `static boolean` | `contains​(Expression a, Expression b)` | Ask whether one expression is a subexpression of another
    `static boolean` | `containsLocalParam​(Expression exp)` | Determine whether an expression contains a LocalParamSetter subexpression
    `static boolean` | `containsLocalVariableReference​(Expression exp)` | Determine whether an expression contains a local variable reference, other than a reference to a local variable whose binding occurs within this expression
    `static boolean` | `containsSubexpression​(Expression exp, java.lang.Class<? extends Expression> subClass)` | Determine whether an expression has a subexpression of a given implementation class
    `static void` | `copyLocationInfo​(Expression from, Expression to)` | Copy location information (the line number and reference to the container) from one expression to another
    `static boolean` | `dependsOnFocus​(Expression exp)` | Ask whether an expression has a dependency on the focus
    `static boolean` | `dependsOnVariable​(Expression exp, Binding[] bindingList)` | Determine whether an expression depends on any one of a set of variables
    `static GroundedValue` | `eagerEvaluate​(Expression exp, XPathContext context)` | Evaluate an expression now; lazy evaluation is not permitted in this case
    `static Evaluator` | `eagerEvaluator​(Expression exp)` | Get the evaluator to be used when eager evaluation of an expression is preferred.
    `static void` | `ebvError​(java.lang.String reason)` | Report an error in computing the effective boolean value of an expression
    `static void` | `ebvError​(java.lang.String reason, Expression cause)` | Report an error in computing the effective boolean value of an expression
    `static boolean` | `effectiveBooleanValue​(Item item)` | Determine the effective boolean value of a single item
    `static boolean` | `effectiveBooleanValue​(SequenceIterator iterator)` | Determine the effective boolean value of a sequence, given an iterator over the sequence
    `static boolean` | `equalOrNull​(java.lang.Object x, java.lang.Object y)` | Return true if two objects are equal or if both are null
    `static int` | `expressionSize​(Expression exp)` | Get the size of an expression tree (the number of subexpressions it contains)
    `static boolean` | `factorOutDot​(Expression exp, Binding variable)` | Replace references to the context item with references to a variable
    `static Operand` | `findOperand​(Expression parentExpression, Expression childExpression)` | Find the operand corresponding to a particular child expression
    `static void` | `gatherCalledFunctionNames​(Expression e, java.util.List<SymbolicName> list)` | Gather a list of the names of the user-defined functions which a given expression calls directly
    `static void` | `gatherCalledFunctions​(Expression e, java.util.List<UserFunction> list)` | Gather a list of all the user-defined functions which a given expression calls directly
    `static void` | `gatherReferencedVariables​(Expression e, java.util.List<Binding> list)` | Gather a list of all the variable bindings on which a given expression depends.
    `static void` | `gatherVariableReferences​(Expression exp, Binding binding, java.util.List<VariableReference> list)` | Get a list of all references to a particular variable within a subtree
    `static int` | `getAxisNavigation​(Expression exp)` | Get the axis followed by this expression, if there is one.
    `static java.net.URI` | `getBaseURI​(StaticContext env, javax.xml.transform.SourceLocator locator, boolean fail)` | Determine the base URI of an expression, so that it can be saved on the expression tree for use when the expression is evaluated
    `static Expression` | `getContextDocumentSettingContainer​(Expression exp)` | Get the context-document-setting container of an expression.
    `static java.lang.String` | `getCurrentDirectory()` |
    `static Expression` | `getFocusSettingContainer​(Expression exp)` | Get the focus-setting container of an expression *
    `static Item` | `getItemFromProcessMethod​(Expression exp, XPathContext context)` | Helper method to construct an item representing the results of the expression when all that the expression itself offers is a process() method.
    `static SequenceIterator` | `getIteratorFromProcessMethod​(Expression exp, XPathContext context)` | Helper method to construct an iterator over the results of the expression when all that the expression itself offers is a process() method.
    `static int` | `getReferenceCount​(Expression exp, Binding binding, boolean inLoop)` | Determine how often a variable is referenced.
    `static boolean` | `hasLoopingSubexpression​(Expression parent, Expression child)` |
    `static java.lang.String` | `indent​(int level)` | Construct indent string, for diagnostic output
    `static Expression` | `injectCode​(Expression exp, CodeInjector injector)` | Inject extra code into an expression, recursively, by applying a supplied `CodeInjector` to every expression (and FLWOR clause) in the subtree
    `static boolean` | `inlineVariableReferences​(Expression expr, Binding binding, Expression replacement)` | Inline variable references.
    `static boolean` | `inlineVariableReferencesInternal​(Expression expr, Binding binding, Expression replacement)` |
    `static boolean` | `isCallOnSystemFunction​(Expression e, java.lang.String localName)` |
    `static boolean` | `isLocalConstructor​(Expression child)` | Ask whether a supplied expression is a nested node constructor.
    `static boolean` | `isLoopingReference​(VariableReference reference, Binding binding)` |
    `static boolean` | `isLoopingSubexpression​(Expression child, Expression ancestor)` | Return true if a given expression is evaluated repeatedly when a given ancestor expression is evaluated once
    `static boolean` | `isNotAllowedInUpdatingContext​(Expression exp)` | Determine whether the expression is either an updating expression, or an expression that is permitted in a context where updating expressions are allowed
    `static Sequence` | `lazyEvaluate​(Expression exp, XPathContext context, boolean repeatable)` | Do lazy evaluation of an expression.
    `static Evaluator` | `lazyEvaluator​(Expression exp, boolean repeatable)` | Get an expression evaluator to be used when lazy evaluation of an expression is preferred.
    `static Expression` | `make​(java.lang.String expression, StaticContext env, int start, int terminator, CodeInjector codeInjector)` | Parse an XPath expression.
    `static Expression` | `makePathExpression​(Expression start, Expression step)` | Make a mapping expression.
    `static int` | `markTailFunctionCalls​(Expression exp, StructuredQName qName, int arity)` | Scan an expression to find and mark any recursive tail function calls
    `static Expression` | `optimizeComponentBody​(Expression body, Compilation compilation, ExpressionVisitor visitor, ContextItemStaticInfo cisi, boolean extractGlobals)` | Optimize the implementation of a component such as a function, template, or global variable
    `static java.lang.String` | `parenthesize​(Expression exp)` | Display an expression adding parentheses if it is possible they are necessary because the expression has sub-expressions
    `static java.lang.String` | `parenthesizeShort​(Expression exp)` |
    `static boolean` | `processExpressionTree​(Expression root, java.lang.Object result, ExpressionAction action)` | Process every node on a subtree of the expression tree using a supplied action.
    `static void` | `rebindVariableReferences​(Expression exp, Binding oldBinding, Binding newBinding)` | Rebind all variable references to a binding
    `static boolean` | `refersToVariableOrFunction​(Expression exp)` | Determine whether the expression contains any variable references or calls to user-written functions
    `static boolean` | `replaceCallsToCurrent​(Expression expr, LocalBinding binding)` | Replace calls to current() by a variable reference.
    `static boolean` | `replaceSelectedSubexpressions​(Expression exp, ExpressionTool.ExpressionSelector selector, Expression replacement, boolean mustCopy)` | Replace all selected subexpressions within a subtree
    `static boolean` | `replaceTrivialCallsToCurrent​(Expression expr)` | Replace trivial calls to current() by a context item expression (`.`).
    `static void` | `replaceVariableReferences​(Expression exp, Binding binding, Expression replacement, boolean mustCopy)` | Replace all references to a particular variable within a subtree
    `static void` | `resetPropertiesWithinSubtree​(Expression exp)` | Reset cached static properties within a subtree, meaning that they have to be recalulated next time they are required
    `static void` | `resetStaticProperties​(Expression exp)` | Reset the static properties for the current expression and for all its containing expressions.
    `static Expression` | `resolveCallsToCurrentFunction​(Expression exp)` | Resolve calls to the XSLT current() function within an expression
    `static void` | `setDeepRetainedStaticContext​(Expression exp, RetainedStaticContext rsc)` | Ensure that every node in the expression tree has a retained static context.
    `static Expression` | `tryToFactorOutDot​(Expression exp, ItemType contextItemType)` | Try to factor out dependencies on the context item, by rewriting an expression f(.) as let $dot := .
    `static Expression` | `unfilteredExpression​(Expression exp, boolean allowPositional)` | Get the expression that remains after removing any filter predicates
    `static Expression` | `unsortedIfHomogeneous​(Expression exp, boolean forStreaming)` | Remove unwanted sorting from an expression, at compile time, if and only if it is known that the result of the expression will be homogeneous (all nodes, or all atomic values).
    `static void` | `validateTree​(Expression exp)` |

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

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

- - ### Method Detail

    - #### make

          public static Expression make​(java.lang.String expression,
                                        StaticContext env,
                                        int start,
                                        int terminator,
                                        CodeInjector codeInjector)
                                 throws XPathException

      Parse an XPath expression. This performs the basic analysis of the expression against the grammar, it binds variable references and function calls to variable definitions and function definitions, and it performs context-independent expression rewriting for optimization purposes.
      Parameters:
        `expression` - The expression (as a character string)
        `env` - An object giving information about the compile-time context of the expression
        `start` - position of the first significant character in the expression
        `terminator` - The token that marks the end of this expression; typically Token.EOF, but may for example be a right curly brace
        `codeInjector` - true allows injection of tracing, debugging, or performance monitoring code; null if not required
      Returns:
        an object of type Expression
      Throws:
        `XPathException` - if the expression contains a static error

    - #### setDeepRetainedStaticContext

          public static void setDeepRetainedStaticContext​(Expression exp,
                                                          RetainedStaticContext rsc)

      Ensure that every node in the expression tree has a retained static context. A node that already has a retained static context will propagate it to its children.
      Parameters:
        `exp` - the root of the expression tree
        `rsc` - the retained static context to be applied to nodes that do not already have one, and that do not have an ancestor with an existing retained static context.

    - #### copyLocationInfo

          public static void copyLocationInfo​(Expression from,
                                              Expression to)

      Copy location information (the line number and reference to the container) from one expression to another
      Parameters:
        `from` - the expression containing the location information
        `to` - the expression to which the information is to be copied

    - #### unsortedIfHomogeneous

          public static Expression unsortedIfHomogeneous​(Expression exp,
                                                         boolean forStreaming)
                                                  throws XPathException

      Remove unwanted sorting from an expression, at compile time, if and only if it is known that the result of the expression will be homogeneous (all nodes, or all atomic values). This is done when we need the effective boolean value of a sequence: the EBV of a homogenous sequence does not depend on its order, but this is not true when atomic values and nodes are mixed: (N, AV) is true, but (AV, N) is an error.
      Parameters:
        `exp` - the expression to be optimized
        `forStreaming` - true if streamed evaluation of the expression is required
      Returns:
        the expression after rewriting
      Throws:
        `XPathException` - if a static error is found while doing the rewrite

    - #### injectCode

          public static Expression injectCode​(Expression exp,
                                              CodeInjector injector)

      Inject extra code into an expression, recursively, by applying a supplied `CodeInjector` to every expression (and FLWOR clause) in the subtree
      Parameters:
        `exp` - the expression to be augmented with injected code
        `injector` - the code injector
      Returns:
        the augmented expression

    - #### lazyEvaluator

          public static Evaluator lazyEvaluator​(Expression exp,
                                                boolean repeatable)

      Get an expression evaluator to be used when lazy evaluation of an expression is preferred. This method is called at compile time, after all optimizations have been done, to determine the preferred strategy for lazy evaluation, depending on the type of expression.
      Parameters:
        `exp` - the expression to be evaluated
        `repeatable` - true if the returned value needs to be readable more than once
      Returns:
        an expression evaluator

    - #### eagerEvaluator

          public static Evaluator eagerEvaluator​(Expression exp)

      Get the evaluator to be used when eager evaluation of an expression is preferred. This method is called at compile time, after all optimizations have been done, to determine the preferred strategy for lazy evaluation, depending on the type of expression.
      Parameters:
        `exp` - the expression to be evaluated
      Returns:
        an integer constant identifying the evaluation mode

    - #### lazyEvaluate

          public static Sequence lazyEvaluate​(Expression exp,
                                              XPathContext context,
                                              boolean repeatable)
                                       throws XPathException

      Do lazy evaluation of an expression. This will return a value, which may optionally be a SequenceIntent, which is a wrapper around an iterator over the value of the expression.
      Parameters:
        `exp` - the expression to be evaluated
        `context` - the run-time evaluation context for the expression. If the expression is not evaluated immediately, then parts of the context on which the expression depends need to be saved as part of the Closure
        `repeatable` - an indication of how the value will be used. The value false indicates that the value is only expected to be used once, so that there is no need to keep it in memory. The value true indicates multiple references, so the value will be saved when first evaluated.
      Returns:
        a value: either the actual value obtained by evaluating the expression, or a Closure containing all the information needed to evaluate it later
      Throws:
        `XPathException` - if any error occurs in evaluating the expression

    - #### eagerEvaluate

          public static GroundedValue eagerEvaluate​(Expression exp,
                                                    XPathContext context)
                                             throws XPathException

      Evaluate an expression now; lazy evaluation is not permitted in this case
      Parameters:
        `exp` - the expression to be evaluated
        `context` - the run-time evaluation context
      Returns:
        the result of evaluating the expression
      Throws:
        `XPathException` - if any dynamic error occurs evaluating the expression

    - #### markTailFunctionCalls

          public static int markTailFunctionCalls​(Expression exp,
                                                  StructuredQName qName,
                                                  int arity)

      Scan an expression to find and mark any recursive tail function calls
      Parameters:
        `exp` - the expression to be analyzed
        `qName` - the name of the containing function
        `arity` - the arity of the containing function
      Returns:
        0 if no tail call was found; 1 if a tail call to a different function was found; 2 if a tail call to the specified function was found. In this case the UserFunctionCall object representing the tail function call will also have been marked as a tail call.

    - #### indent

          public static java.lang.String indent​(int level)

      Construct indent string, for diagnostic output
      Parameters:
        `level` - the indentation level (the number of spaces to return)
      Returns:
        a string of "level*2" spaces

    - #### contains

          public static boolean contains​(Expression a,
                                         Expression b)

      Ask whether one expression is a subexpression of another
      Parameters:
        `a` - the containing expression
        `b` - the putative contained expression
      Returns:
        true if and only if b is a subexpression (at some level) of a

    - #### containsLocalParam

          public static boolean containsLocalParam​(Expression exp)

      Determine whether an expression contains a LocalParamSetter subexpression
      Parameters:
        `exp` - the expression to be tested
      Returns:
        true if the exprssion contains a local parameter setter

    - #### containsLocalVariableReference

          public static boolean containsLocalVariableReference​(Expression exp)

      Determine whether an expression contains a local variable reference, other than a reference to a local variable whose binding occurs within this expression
      Parameters:
        `exp` - the expression to be tested
      Returns:
        true if the expression contains a local variable reference to a local variable declared outside this expression.

    - #### contains

          public static boolean contains​(Expression exp,
                                         boolean sameFocusOnly,
                                         java.util.function.Predicate<Expression> predicate)

      Test whether a given expression is, or contains, at any depth, an expression that satisfies a supplied condition
      Parameters:
        `exp` - the given expression
        `sameFocusOnly` - if true, only subexpressions evaluated in the same focus are searched. If false, all subexpressions are searched
        `predicate` - the condition to be satisfied
      Returns:
        true if the given expression is or contains an expression that satisfies the condition.

    - #### changesXsltContext

          public static boolean changesXsltContext​(Expression exp)

      Determine whether an expression possible calls (directly or indirectly) xsl:result-document, or has other context dependencies that prevent function inlining, which we assume is true if it contains a template call. A call on result-document disqualifies the function from being inlined, because error XTDE1480 would then not be detected. We don't have to worry about functions containing further function calls because they are disqualified from inlining anyway.
      Parameters:
        `exp` - the expression to be tested
      Returns:
        true if there is any possibility that calling the function might result in a call on xsl:result-document

    - #### isLoopingSubexpression

          public static boolean isLoopingSubexpression​(Expression child,
                                                       Expression ancestor)

      Return true if a given expression is evaluated repeatedly when a given ancestor expression is evaluated once
      Parameters:
        `child` - the expression to be tested
        `ancestor` - the ancestor expression. May be null, in which case the search goes all the way to the base of the stack.
      Returns:
        true if the current expression is evaluated repeatedly

    - #### isLoopingReference

          public static boolean isLoopingReference​(VariableReference reference,
                                                   Binding binding)

    - #### hasLoopingSubexpression

          public static boolean hasLoopingSubexpression​(Expression parent,
                                                        Expression child)

    - #### getFocusSettingContainer

          public static Expression getFocusSettingContainer​(Expression exp)

      Get the focus-setting container of an expression *

      Note, this always returns an expression or null. Unlike the like-named concept in the spec, it can't return a component such as a template or an attribute set.

      Parameters:
        `exp` - the expression whose focus-setting container is required
      Returns:
        the focus-setting container, or null if the focus for the expression is the same as the focus for the containing component as a whole

    - #### getContextDocumentSettingContainer

          public static Expression getContextDocumentSettingContainer​(Expression exp)

      Get the context-document-setting container of an expression. This is the same as the focus-setting container, except when the context-setting operand is a single-document node-set, in which case we can go up one more level. For example, given /a/b[/d/e = 3], the predicate /d/e = 3 can be loop-lifted from the filter expression, because it is known that the base expression /a/b is a single-document node-set.
      Parameters:
        `exp` - the expression whose document-context-setting container is required
      Returns:
        the context-document-setting container, or null if the focus for the expression is the same as the focus for the containing component as a whole

    - #### resetStaticProperties

          public static void resetStaticProperties​(Expression exp)

      Reset the static properties for the current expression and for all its containing expressions. This should be done whenever the expression is changed in a way that might affect the properties. It causes the properties to be recomputed next time they are needed.
      Parameters:
        `exp` - the expression whose properties are to be reset; the method also resets local properties for all its ancestor expressions.

    - #### getAxisNavigation

          public static int getAxisNavigation​(Expression exp)

      Get the axis followed by this expression, if there is one. For an axis expression or a filtered axis expression this returns the axis. For a union/intersect/except expression it returns the common axis if they all use the same axis. Where no axis can be discerned, return -1
      Returns:
        the axis followed by this expression if applicable (as an `AxisInfo` constant) or -1 otherwise.

    - #### equalOrNull

          public static boolean equalOrNull​(java.lang.Object x,
                                            java.lang.Object y)

      Return true if two objects are equal or if both are null
      Parameters:
        `x` - the first object
        `y` - the second object
      Returns:
        true if both x and y are null or if x.equals(y)

    - #### getIteratorFromProcessMethod

          public static SequenceIterator getIteratorFromProcessMethod​(Expression exp,
                                                                      XPathContext context)
                                                               throws XPathException

      Helper method to construct an iterator over the results of the expression when all that the expression itself offers is a process() method. This builds the entire results of the expression as a sequence in memory and then iterates over it.
      Parameters:
        `context` - the dynamic evaluation context
      Returns:
        an iterator over the results of the expression
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### getItemFromProcessMethod

          public static Item getItemFromProcessMethod​(Expression exp,
                                                      XPathContext context)
                                               throws XPathException

      Helper method to construct an item representing the results of the expression when all that the expression itself offers is a process() method.
      Parameters:
        `context` - the dynamic evaluation context
      Returns:
        an iterator over the results of the expression
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### allocateSlots

          public static int allocateSlots​(Expression exp,
                                          int nextFree,
                                          SlotManager frame)

      Allocate slot numbers to range variables
      Parameters:
        `exp` - the expression whose range variables need to have slot numbers assigned
        `nextFree` - the next slot number that is available for allocation
        `frame` - a SlotManager object that is used to track the mapping of slot numbers to variable names for debugging purposes. May be null.
      Returns:
        the next unallocated slot number.

    - #### effectiveBooleanValue

          public static boolean effectiveBooleanValue​(SequenceIterator iterator)
                                               throws XPathException

      Determine the effective boolean value of a sequence, given an iterator over the sequence
      Parameters:
        `iterator` - An iterator over the sequence whose effective boolean value is required
      Returns:
        the effective boolean value
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### effectiveBooleanValue

          public static boolean effectiveBooleanValue​(Item item)
                                               throws XPathException

      Determine the effective boolean value of a single item
      Parameters:
        `item` - the item whose effective boolean value is required
      Returns:
        the effective boolean value
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### ebvError

          public static void ebvError​(java.lang.String reason)
                               throws XPathException

      Report an error in computing the effective boolean value of an expression
      Parameters:
        `reason` - the nature of the error
      Throws:
        `XPathException` - always

    - #### ebvError

          public static void ebvError​(java.lang.String reason,
                                      Expression cause)
                               throws XPathException

      Report an error in computing the effective boolean value of an expression
      Parameters:
        `reason` - the nature of the error
      Throws:
        `XPathException` - always

    - #### dependsOnFocus

          public static boolean dependsOnFocus​(Expression exp)

      Ask whether an expression has a dependency on the focus
      Parameters:
        `exp` - the expression
      Returns:
        true if the value of the expression depends on the context item, position, or size

    - #### dependsOnVariable

          public static boolean dependsOnVariable​(Expression exp,
                                                  Binding[] bindingList)

      Determine whether an expression depends on any one of a set of variables
      Parameters:
        `exp` - the expression being tested
        `bindingList` - the set of variables being tested
      Returns:
        true if the expression depends on one of the given variables

    - #### gatherReferencedVariables

          public static void gatherReferencedVariables​(Expression e,
                                                       java.util.List<Binding> list)

      Gather a list of all the variable bindings on which a given expression depends. In the light of spec bug 29590, this only considers variable references that are unconditionally evaluated: that is, it ignores variable references appearing in the then/else branches of a conditional or equivalent. Cycles involving conditional evaluation are detected dynamically.
      Parameters:
        `e` - the expression being tested
        `list` - a list to which the bindings are to be added. The items in this list must implement `Binding`

    - #### refersToVariableOrFunction

          public static boolean refersToVariableOrFunction​(Expression exp)

      Determine whether the expression contains any variable references or calls to user-written functions
      Parameters:
        `exp` - the expression being tested
      Returns:
        true if the expression includes a variable reference or function call, or an XSLT construct equivalent to a function call (e.g call-template). Also returns true if the expression includes a variable binding element, as (a) this is likely to mean it also contains a reference, and (b) it also needs to be caught on the same paths.

    - #### isCallOnSystemFunction

          public static boolean isCallOnSystemFunction​(Expression e,
                                                       java.lang.String localName)

    - #### callsFunction

          public static boolean callsFunction​(Expression exp,
                                              StructuredQName qName,
                                              boolean sameFocusOnly)

      Determine whether an expression contains a call on the function with a given name
      Parameters:
        `exp` - The expression being tested
        `qName` - The name of the function
        `sameFocusOnly` - If true, only expressions with the same (top-level) focus are searched
      Returns:
        true if the expression contains a call on the function

    - #### containsSubexpression

          public static boolean containsSubexpression​(Expression exp,
                                                      java.lang.Class<? extends Expression> subClass)

      Determine whether an expression has a subexpression of a given implementation class
      Parameters:
        `exp` - The expression being tested
        `subClass` - The implementation class of the sought subexpression
      Returns:
        true if the expression contains a subexpression that is an instance of the specified class

    - #### gatherCalledFunctions

          public static void gatherCalledFunctions​(Expression e,
                                                   java.util.List<UserFunction> list)

      Gather a list of all the user-defined functions which a given expression calls directly
      Parameters:
        `e` - the expression being tested
        `list` - a list of the functions that are called. The items in this list must be objects of class `UserFunction`

    - #### gatherCalledFunctionNames

          public static void gatherCalledFunctionNames​(Expression e,
                                                       java.util.List<SymbolicName> list)

      Gather a list of the names of the user-defined functions which a given expression calls directly
      Parameters:
        `e` - the expression being tested
        `list` - a list of the functions that are called. The items in this list are strings in the format "{uri}local/arity"

    - #### optimizeComponentBody

          public static Expression optimizeComponentBody​(Expression body,
                                                         Compilation compilation,
                                                         ExpressionVisitor visitor,
                                                         ContextItemStaticInfo cisi,
                                                         boolean extractGlobals)
                                                  throws XPathException

      Optimize the implementation of a component such as a function, template, or global variable
      Parameters:
        `body` - the expression forming the body of the component
        `compilation` - the current compilation. May be null.
        `visitor` - the expression visitor
        `cisi` - information about the context item for evaluation of the component body
        `extractGlobals` - true if constant expressions are to be extracted as global variables
      Returns:
        the optimized expression body
      Throws:
        `XPathException` - if anything goes wrong

    - #### computeEvaluationModesForUserFunctionCalls

          public static void computeEvaluationModesForUserFunctionCalls​(Expression exp)
                                                                 throws XPathException

      Compute argument evaluation modes for all calls on user defined functions with a specified expression
      Throws:
        `XPathException`

    - #### clearStreamabilityData

          public static void clearStreamabilityData​(Expression exp)
                                             throws XPathException

      Clear all computed streamability properties for an expression and its contained subtree
      Parameters:
        `exp` - the expression whose streamability data is to be reset
      Throws:
        `XPathException` - should not happen

    - #### resetPropertiesWithinSubtree

          public static void resetPropertiesWithinSubtree​(Expression exp)

      Reset cached static properties within a subtree, meaning that they have to be recalulated next time they are required
      Parameters:
        `exp` - the root of the subtree within which static properties should be reset

    - #### resolveCallsToCurrentFunction

          public static Expression resolveCallsToCurrentFunction​(Expression exp)

      Resolve calls to the XSLT current() function within an expression
      Parameters:
        `exp` - the expression within which calls to current() should be resolved
      Returns:
        the expression after resolving calls to current()

    - #### gatherVariableReferences

          public static void gatherVariableReferences​(Expression exp,
                                                      Binding binding,
                                                      java.util.List<VariableReference> list)

      Get a list of all references to a particular variable within a subtree
      Parameters:
        `exp` - the expression at the root of the subtree
        `binding` - the variable binding whose references are sought
        `list` - a list to be populated with the references to this variable

    - #### processExpressionTree

          public static boolean processExpressionTree​(Expression root,
                                                      java.lang.Object result,
                                                      ExpressionAction action)
                                               throws XPathException

      Process every node on a subtree of the expression tree using a supplied action.
      Parameters:
        `root` - the root of the subtree to be processed
        `result` - an arbitrary object that is passed to each action call and that can be updated to gather results of the processing
        `action` - an action to be performed on each node of the expression tree. Processing stops if any action returns the value true
      Returns:
        true if any call on the action operand returned true
      Throws:
        `XPathException` - if the callback throws an error

    - #### replaceSelectedSubexpressions

          public static boolean replaceSelectedSubexpressions​(Expression exp,
                                                              ExpressionTool.ExpressionSelector selector,
                                                              Expression replacement,
                                                              boolean mustCopy)

      Replace all selected subexpressions within a subtree
      Parameters:
        `exp` - the expression at the root of the subtree
        `selector` - callback to determine whether a subexpression is selected
        `replacement` - the expression to be used in place of the variable reference
        `mustCopy` - if true, the replacement expression must be copied before use
      Returns:
        true if a replacement has been performed (in which case the replacement expression must be copied before being used again).

    - #### replaceVariableReferences

          public static void replaceVariableReferences​(Expression exp,
                                                       Binding binding,
                                                       Expression replacement,
                                                       boolean mustCopy)

      Replace all references to a particular variable within a subtree
      Parameters:
        `exp` - the expression at the root of the subtree
        `binding` - the variable binding whose references are sought
        `replacement` - the expression to be used in place of the variable reference
        `mustCopy` - true if the replacement expression must be copied before use

    - #### getReferenceCount

          public static int getReferenceCount​(Expression exp,
                                              Binding binding,
                                              boolean inLoop)

      Determine how often a variable is referenced. This is the number of times it is referenced at run-time: so a reference in a loop counts as "many". This code currently handles local variables (Let expressions) and function parameters. It is not currently used for XSLT template parameters. It's not the end of the world if the answer is wrong (unless it's wrongly given as zero), but if wrongly returned as 1 then the variable will be repeatedly evaluated.
      Parameters:
        `exp` - the expression within which variable references are to be counted
        `binding` - identifies the variable of interest
        `inLoop` - true if the expression is within a loop, in which case a reference counts as many. This should be set to false on the initial call, it may be set to true on an internal recursive call
      Returns:
        the number of references. The interesting values are 0, 1, "many" (represented by any value >1), and the special value FILTERED, which indicates that there are multiple references and one or more of them is of the form `$x[....]` indicating that an index might be useful.

    - #### expressionSize

          public static int expressionSize​(Expression exp)

      Get the size of an expression tree (the number of subexpressions it contains)
      Parameters:
        `exp` - the expression whose size is required
      Returns:
        the size of the expression tree, as the number of nodes

    - #### rebindVariableReferences

          public static void rebindVariableReferences​(Expression exp,
                                                      Binding oldBinding,
                                                      Binding newBinding)

      Rebind all variable references to a binding
      Parameters:
        `exp` - the expression whose contained variable references are to be rebound
        `oldBinding` - the old binding for the variable references
        `newBinding` - the new binding to which the variables should be rebound

    - #### makePathExpression

          public static Expression makePathExpression​(Expression start,
                                                      Expression step)

      Make a mapping expression. The resulting expression will include logic to check that the first operand returns nodes, and that the expression as a whole is homogeneous, unless the caller requests otherwise.
      Parameters:
        `start` - the start expression (the first operand of "/")
        `step` - the step expression (the second operand of "/")
      Returns:
        the resulting expression.

    - #### findOperand

          public static Operand findOperand​(Expression parentExpression,
                                            Expression childExpression)

      Find the operand corresponding to a particular child expression
      Parameters:
        `parentExpression` - the parent expression
        `childExpression` - the child expression
      Returns:
        the relevant operand, or null if not found

    - #### unfilteredExpression

          public static Expression unfilteredExpression​(Expression exp,
                                                        boolean allowPositional)

      Get the expression that remains after removing any filter predicates
      Parameters:
        `exp` - the expression to be examined
        `allowPositional` - true if positional predicates are allowed
      Returns:
        the expression underlying exp after removing any predicates

    - #### tryToFactorOutDot

          public static Expression tryToFactorOutDot​(Expression exp,
                                                     ItemType contextItemType)

      Try to factor out dependencies on the context item, by rewriting an expression f(.) as let $dot := . return f($dot). This is not always possible, for example where f() is an extension function call that uses XPathContext as an implicit argument. However, doing this increases the chances of distributing a "where" condition in a FLWOR expression to the individual input sequences selected by the "for" clauses.
      Parameters:
        `exp` - the expression from which references to "." should be factored out if possible
        `contextItemType` - the static type of the context item
      Returns:
        either the expression, after binding "." to a local variable and replacing all references to it; or null, if no changes were made.

    - #### factorOutDot

          public static boolean factorOutDot​(Expression exp,
                                             Binding variable)

      Replace references to the context item with references to a variable
      Parameters:
        `exp` - the expression in which the replacement is to take place
        `variable` - the declaration of the variable
      Returns:
        true if replacement has taken place (at any level)

    - #### inlineVariableReferences

          public static boolean inlineVariableReferences​(Expression expr,
                                                         Binding binding,
                                                         Expression replacement)

      Inline variable references.
      Parameters:
        `expr` - the expression containing the variable references to be inlined
        `binding` - the variable binding to be inlined
        `replacement` - the expression to be used as a replacement for the variable reference
      Returns:
        true if any replacement was carried out within the subtree of this expression

    - #### inlineVariableReferencesInternal

          public static boolean inlineVariableReferencesInternal​(Expression expr,
                                                                 Binding binding,
                                                                 Expression replacement)

    - #### replaceTrivialCallsToCurrent

          public static boolean replaceTrivialCallsToCurrent​(Expression expr)

      Replace trivial calls to current() by a context item expression (`.`).
      Parameters:
        `expr` - the expression potentially containing the calls to be replaced
      Returns:
        true if any replacement was carried out within the subtree of this expression

    - #### replaceCallsToCurrent

          public static boolean replaceCallsToCurrent​(Expression expr,
                                                      LocalBinding binding)

      Replace calls to current() by a variable reference.
      Parameters:
        `expr` - the expression potentially containing the calls to be replaced
        `binding` - the variable binding to be referenced
      Returns:
        true if any replacement was carried out within the subtree of this expression

    - #### isNotAllowedInUpdatingContext

          public static boolean isNotAllowedInUpdatingContext​(Expression exp)

      Determine whether the expression is either an updating expression, or an expression that is permitted in a context where updating expressions are allowed
      Parameters:
        `exp` - the expression under test
      Returns:
        true if the expression is neither an updating expression, nor an empty sequence, nor a call on error()

    - #### getCurrentDirectory

          public static java.lang.String getCurrentDirectory()

    - #### getBaseURI

          public static java.net.URI getBaseURI​(StaticContext env,
                                                javax.xml.transform.SourceLocator locator,
                                                boolean fail)
                                         throws XPathException

      Determine the base URI of an expression, so that it can be saved on the expression tree for use when the expression is evaluated
      Parameters:
        `env` - the static context
        `locator` - location of the expression for error messages
        `fail` - if true, the method throws an exception when there is no absolute base URI; otherwise, the method returns null
      Returns:
        the absolute base URI of the expression
      Throws:
        `XPathException` - if an error occurs

    - #### parenthesize

          public static java.lang.String parenthesize​(Expression exp)

      Display an expression adding parentheses if it is possible they are necessary because the expression has sub-expressions
      Parameters:
        `exp` - the expression to be displayed
      Returns:
        a representation of the expression in parentheses

    - #### parenthesizeShort

          public static java.lang.String parenthesizeShort​(Expression exp)

    - #### validateTree

          public static void validateTree​(Expression exp)

    - #### isLocalConstructor

          public static boolean isLocalConstructor​(Expression child)

      Ask whether a supplied expression is a nested node constructor. That is, return true if the child expression creates nodes that will only be used as children of some parent node (meaning that they never need to be copied).
      Parameters:
        `child` - child expression to be tested
      Returns:
        true if the node constructed by the child expression does not need to be copied.