Package net.sf.saxon.expr

## Class Assignation

- java.lang.Object
- - net.sf.saxon.expr.Expression
  - - net.sf.saxon.expr.Assignation

- All Implemented Interfaces:
    `Binding`, `ExportAgent`, `LocalBinding`, `Locatable`, `IdentityComparable`, `Traceable`
  Direct Known Subclasses:
    `ForExpression`, `ForMemberExpression`, `LetExpression`, `QuantifiedExpression`

      public abstract class Assignation
      extends Expression
      implements LocalBinding

  Assignation is an abstract superclass for the kinds of expression that declare range variables: for, some, and every.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected boolean` | `hasLoopingReference` |
    `protected boolean` | `isIndexedVariable` |
    `protected java.util.List<VariableReference>` | `references` |
    `protected SequenceType` | `requiredType` |
    `protected int` | `slotNumber` |
    `protected StructuredQName` | `variableName` |

    - ### 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
    --- | ---
    `Assignation()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addReference​(VariableReference ref, boolean isLoopingReference)` | Register a variable reference that refers to the variable bound in this expression
    `PathMap.PathMapNodeSet` | `addToPathMap​(PathMap pathMap, PathMap.PathMapNodeSet pathMapNodeSet)` | Add a representation of this expression to a PathMap.
    `void` | `checkForUpdatingSubexpressions()` | Check to ensure that this expression does not contain any inappropriate updating subexpressions.
    `int` | `computeDependencies()` | Compute the dependencies of an expression, as the union of the dependencies of its sub-expressions.
    `Sequence` | `evaluateVariable​(XPathContext context)` | Get the value of the range variable
    `Expression` | `getAction()` | Get the action expression
    `Operand` | `getActionOp()` |
    `double` | `getCost()` | Return the estimated cost of evaluating an expression.
    `IntegerValue[]` | `getIntegerBoundsForVariable()` | If the variable is bound to an integer, get the minimum and maximum possible values.
    `int` | `getLocalSlotNumber()` | If this is a local variable held on the local stack frame, return the corresponding slot number.
    `int` | `getNominalReferenceCount()` | Get the (nominal) count of the number of references to this variable
    `StructuredQName` | `getObjectName()` | Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc.
    `int` | `getRequiredSlots()` | Get the number of slots required.
    `SequenceType` | `getRequiredType()` | Get the declared type of the variable
    `Expression` | `getSequence()` | Get the "sequence" expression - the one to which the variable is bound
    `Operand` | `getSequenceOp()` |
    `java.lang.String` | `getVariableEQName()` | Get the name of the range variable as a Name or EQName.
    `java.lang.String` | `getVariableName()` | Get the display name of the range variable, for diagnostics only
    `StructuredQName` | `getVariableQName()` | Get the name of the variable
    `boolean` | `hasVariableBinding​(Binding binding)` | Ask whether this expression is, or contains, the binding of a given variable
    `boolean` | `isAssignable()` | Test whether it is permitted to assign to the variable using the saxon:assign extension element.
    `boolean` | `isGlobal()` | Indicate whether the binding is local or global.
    `boolean` | `isIndexedVariable()` | Test whether the variable bound by this let expression should be indexable
    `boolean` | `isUpdatingExpression()` | Determine whether this is an updating expression as defined in the XQuery update specification
    `java.lang.Iterable<Operand>` | `operands()` | Get the immediate sub-expressions of this expression, with information about the relationship of each expression to its parent expression.
    `void` | `rebuildReferenceList​(boolean force)` | Rebuild the reference list to guide subsequent optimization.
    `void` | `refineTypeInformation​(ItemType type, int cardinality, GroundedValue constantValue, int properties, Assignation currentExpression)` | Refine the type information associated with this variable declaration.
    `protected boolean` | `removeDeadReferences()` | Remove dead references from the reference list of the variable; at the same time, check whether any of the variable references is in a loop, and return true if so.
    `boolean` | `replaceVariable​(Expression seq)` | Replace all references to the variable bound by this let expression, that occur within the action expression, with the given expression
    `void` | `setAction​(Expression action)` | Add the "return" or "satisfies" expression, and fix up all references to the range variable that occur within that expression
    `void` | `setIndexedVariable()` | Indicate that the variable bound by this let expression should be indexable (because it is used in an appropriate filter expression)
    `void` | `setRequiredType​(SequenceType requiredType)` | Set the required type (declared type) of the variable
    `void` | `setSequence​(Expression sequence)` | Set the "sequence" expression - the one to which the variable is bound
    `void` | `setSlotNumber​(int nr)` | Set the slot number for the range variable
    `void` | `setVariableQName​(StructuredQName variableName)` | Set the name of the variable
    `void` | `suppressValidation​(int validationMode)` | Suppress validation on contained element constructors, on the grounds that the parent element is already performing validation.
    `Expression` | `unordered​(boolean retainAllNodes, boolean forStreaming)` | Replace this expression by a simpler expression that delivers the results without regard to order.
    `protected void` | `verifyReferences()` | This method recomputes the reference list by scanning the subtree rooted at this variable binding.

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

      `adoptChildExpression, allowExtractingCommonSubexpressions, checkedOperands, checkPermittedContents, computeCardinality, computeHashCode, computeSpecialProperties, computeStaticProperties, copy, dynamicError, effectiveBooleanValue, equals, evaluateAsString, evaluateItem, evaluatePendingUpdates, explain, export, getCardinality, getConfiguration, getDependencies, getEvaluationMethod, getExpressionName, getExtraProperty, getImplementationMethod, getIntegerBounds, getInterpretedExpression, getIntrinsicDependencies, getItemType, getLocalRetainedStaticContext, getLocation, getNetCost, getPackageData, getParentExpression, getProperties, getProperty, getRetainedStaticContext, getScopingExpression, getSlotsUsed, getSpecialProperties, getStaticBaseURI, getStaticBaseURIString, getStaticType, getStaticUType, getStreamerName, getTracingTag, hasCompatibleStaticContext, hashCode, hasSpecialProperty, identityHashCode, implementsStaticTypeCheck, isCallOn, isEqual, isIdentical, isInstruction, isLiftable, isMultiThreaded, isStaticPropertiesKnown, isSubtreeExpression, isVacuousExpression, iterate, markTailFunctionCalls, operandList, operandSparseList, optimize, optimizeChildren, prepareForStreaming, process, resetLocalStaticProperties, restoreParentPointers, setEvaluationMethod, setExtraProperty, setFiltered, setFlattened, setLocation, setParentExpression, setRetainedStaticContext, setRetainedStaticContextLocally, setRetainedStaticContextThoroughly, setStaticProperty, simplify, simplifyChildren, staticTypeCheck, toPattern, toShortString, toString, typeCheck, 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

    - #### slotNumber

          protected int slotNumber

    - #### variableName

          protected StructuredQName variableName

    - #### requiredType

          protected SequenceType requiredType

    - #### isIndexedVariable

          protected boolean isIndexedVariable

    - #### hasLoopingReference

          protected boolean hasLoopingReference

    - #### references

          protected java.util.List<VariableReference> references

  - ### Constructor Detail

    - #### Assignation

          public Assignation()

  - ### Method Detail

    - #### getSequenceOp

          public Operand getSequenceOp()

    - #### getActionOp

          public Operand getActionOp()

    - #### operands

          public java.lang.Iterable<Operand> operands()

      Description copied from class: `Expression`
      Get the immediate sub-expressions of this expression, with information about the relationship of each expression to its parent expression. Default implementation works off the results of iterateSubExpressions()

      If the expression is a Callable, then it is required that the order of the operands returned by this function is the same as the order of arguments supplied to the corresponding call() method.

      Overrides:
        `operands` in class `Expression`
      Returns:
        an iterator containing the sub-expressions of this expression

    - #### setRequiredType

          public void setRequiredType​(SequenceType requiredType)

      Set the required type (declared type) of the variable
      Parameters:
        `requiredType` - the required type

    - #### setVariableQName

          public void setVariableQName​(StructuredQName variableName)

      Set the name of the variable
      Parameters:
        `variableName` - the name of the variable

    - #### getVariableQName

          public StructuredQName getVariableQName()

      Get the name of the variable
      Specified by:
        `getVariableQName` in interface `Binding`
      Returns:
        the variable name, as a QName

    - #### getObjectName

          public StructuredQName getObjectName()

      Description copied from interface: `Traceable`
      Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc. This is used only where the name is known statically.
      Specified by:
        `getObjectName` in interface `Traceable`
      Overrides:
        `getObjectName` in class `Expression`
      Returns:
        the QName of the object declared or manipulated by this instruction or expression

    - #### getRequiredType

          public SequenceType getRequiredType()

      Get the declared type of the variable
      Specified by:
        `getRequiredType` in interface `Binding`
      Returns:
        the declared type

    - #### getIntegerBoundsForVariable

          public IntegerValue[] getIntegerBoundsForVariable()

      If the variable is bound to an integer, get the minimum and maximum possible values. Return null if unknown or not applicable
      Specified by:
        `getIntegerBoundsForVariable` in interface `Binding`
      Returns:
        a pair of integers containing the minimum and maximum values for the integer value; or null if the value is not an integer or the range is unknown

    - #### getLocalSlotNumber

          public int getLocalSlotNumber()

      If this is a local variable held on the local stack frame, return the corresponding slot number. In other cases, return -1.
      Specified by:
        `getLocalSlotNumber` in interface `LocalBinding`
      Returns:
        the slot number on the local stack frame

    - #### computeDependencies

          public int computeDependencies()

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

    - #### evaluateVariable

          public Sequence evaluateVariable​(XPathContext context)
                                    throws XPathException

      Get the value of the range variable
      Specified by:
        `evaluateVariable` in interface `Binding`
      Parameters:
        `context` - the XPath dynamic evaluation context
      Returns:
        the result of evaluating the variable
      Throws:
        `XPathException` - if an error occurs while evaluating the variable

    - #### setAction

          public void setAction​(Expression action)

      Add the "return" or "satisfies" expression, and fix up all references to the range variable that occur within that expression
      Parameters:
        `action` - the expression that occurs after the "return" keyword of a "for" expression, the "satisfies" keyword of "some/every", or the ":=" operator of a "let" expression.

    - #### isGlobal

          public final boolean isGlobal()

      Indicate whether the binding is local or global. A global binding is one that has a fixed value for the life of a query or transformation; any other binding is local.
      Specified by:
        `isGlobal` in interface `Binding`
      Returns:
        true if the binding is global

    - #### isAssignable

          public final boolean isAssignable()

      Test whether it is permitted to assign to the variable using the saxon:assign extension element. This will only be for an XSLT global variable where the extra attribute saxon:assignable="yes" is present.
      Specified by:
        `isAssignable` in interface `Binding`
      Returns:
        true if the binding is assignable

    - #### checkForUpdatingSubexpressions

          public void checkForUpdatingSubexpressions()
                                              throws XPathException

      Check to ensure that this expression does not contain any inappropriate updating subexpressions. This check is overridden for those expressions that permit updating subexpressions.
      Overrides:
        `checkForUpdatingSubexpressions` in class `Expression`
      Throws:
        `XPathException` - if the expression has a non-permitted updateing subexpression

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

    - #### getAction

          public Expression getAction()

      Get the action expression
      Returns:
        the action expression (introduced by "return" or "satisfies")

    - #### setSequence

          public void setSequence​(Expression sequence)

      Set the "sequence" expression - the one to which the variable is bound
      Parameters:
        `sequence` - the expression to which the variable is bound

    - #### getSequence

          public Expression getSequence()

      Get the "sequence" expression - the one to which the variable is bound
      Returns:
        the expression to which the variable is bound

    - #### setSlotNumber

          public void setSlotNumber​(int nr)

      Set the slot number for the range variable
      Parameters:
        `nr` - the slot number to be used

    - #### getRequiredSlots

          public int getRequiredSlots()

      Get the number of slots required. Normally 1, except for a FOR expression with an AT clause, where it is 2.
      Returns:
        the number of slots required

    - #### hasVariableBinding

          public boolean hasVariableBinding​(Binding binding)

      Description copied from class: `Expression`
      Ask whether this expression is, or contains, the binding of a given variable
      Overrides:
        `hasVariableBinding` in class `Expression`
      Parameters:
        `binding` - the variable binding
      Returns:
        true if this expression is the variable binding (for example a ForExpression or LetExpression) or if it is a FLWOR expression that binds the variable in one of its clauses.

    - #### 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 optimizing for streaming
      Returns:
        an expression that delivers the same nodes in a more convenient order
      Throws:
        `XPathException` - if the rewrite fails

    - #### getCost

          public double getCost()

      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:
        `getCost` in class `Expression`
      Returns:
        the estimated cost

    - #### suppressValidation

          public void suppressValidation​(int validationMode)

      Suppress validation on contained element constructors, on the grounds that the parent element is already performing validation. The default implementation does nothing.
      Overrides:
        `suppressValidation` in class `Expression`
      Parameters:
        `validationMode` - the kind of validation being performed on the parent expression

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

    - #### getVariableName

          public java.lang.String getVariableName()

      Get the display name of the range variable, for diagnostics only
      Returns:
        the lexical QName of the range variable. For system allocated variables, the conventional namespace prefix "zz" is used.

    - #### getVariableEQName

          public java.lang.String getVariableEQName()

      Get the name of the range variable as a Name or EQName.
      Returns:
        the name of the range variable. For system allocated variables, the namespace "http://ns.saxonica.com/anonymous-var" is used. For names in no namespace, the local name alone is used

    - #### refineTypeInformation

          public void refineTypeInformation​(ItemType type,
                                            int cardinality,
                                            GroundedValue constantValue,
                                            int properties,
                                            Assignation currentExpression)
                                     throws XPathException

      Refine the type information associated with this variable declaration. This is useful when the type of the variable has not been explicitly declared (which is common); the variable then takes a static type based on the type of the expression to which it is bound. The effect of this call is to update the static expression type for all references to this variable.
      Parameters:
        `type` - the inferred item type of the expression to which the variable is bound
        `cardinality` - the inferred cardinality of the expression to which the variable is bound
        `constantValue` - the constant value to which the variable is bound (null if there is no constant value)
        `properties` - other static properties of the expression to which the variable is bound
        `currentExpression` - the expression that binds the variable
      Throws:
        `XPathException` - if things go wrong

    - #### addReference

          public void addReference​(VariableReference ref,
                                   boolean isLoopingReference)

      Register a variable reference that refers to the variable bound in this expression
      Specified by:
        `addReference` in interface `Binding`
      Parameters:
        `ref` - the variable reference
        `isLoopingReference` - - true if the reference occurs within a loop, such as the predicate of a filter expression

    - #### getNominalReferenceCount

          public int getNominalReferenceCount()

      Get the (nominal) count of the number of references to this variable
      Returns:
        zero if there are no references, one if there is a single reference that is not in a loop, some higher number if there are multiple references (or a single reference in a loop), or the special value @link RangeVariable#FILTERED} if there are any references in filter expressions that require searching.

    - #### removeDeadReferences

          protected boolean removeDeadReferences()

      Remove dead references from the reference list of the variable; at the same time, check whether any of the variable references is in a loop, and return true if so. References are considered dead if they do not have this Binding as an ancestor in the expression tree; this typically occurs because they are in a part of the tree that has been rewritten or removed.
      Returns:
        true if any of the references in the reference list occurs within a looping construct.

    - #### verifyReferences

          protected void verifyReferences()

      This method recomputes the reference list by scanning the subtree rooted at this variable binding. If the scan proves expensive, or if more than two references are found, or if a looping reference is found, then the scan is abandoned. On completion the reference list for the variable is either accurate, or is null.

    - #### rebuildReferenceList

          public void rebuildReferenceList​(boolean force)

      Rebuild the reference list to guide subsequent optimization.
      Parameters:
        `force` - if true, the search is exhaustive. If false, the search (and therefore the attempt to inline variables) is abandoned after a while to avoid excessive cost. This happens when a stylesheet contains very large templates or functions.

    - #### isIndexedVariable

          public boolean isIndexedVariable()

      Test whether the variable bound by this let expression should be indexable
      Specified by:
        `isIndexedVariable` in interface `LocalBinding`
      Returns:
        true if the variable should be indexable

    - #### replaceVariable

          public boolean replaceVariable​(Expression seq)

      Replace all references to the variable bound by this let expression, that occur within the action expression, with the given expression
      Parameters:
        `seq` - the expression
      Returns:
        true if the variable was successfully inlined. (Returns false, for example, if a variable reference occurs inside a try/catch, which inhibits inlining).

    - #### setIndexedVariable

          public void setIndexedVariable()

      Indicate that the variable bound by this let expression should be indexable (because it is used in an appropriate filter expression)
      Specified by:
        `setIndexedVariable` in interface `LocalBinding`