## net.sf.saxon.expr
Class Assignation

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

All Implemented Interfaces:
  java.io.Serializable, javax.xml.transform.SourceLocator, LocationProvider, SaxonLocator, Binding, EvaluableItem, SequenceIterable, InstructionInfo, org.xml.sax.Locator

Direct Known Subclasses:
  ForExpression, LetExpression, QuantifiedExpression

    public abstract class Assignation

extends Expression
implements Binding

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

See Also:
  Serialized Form

Field Summary
`protected Expression` `action`
`protected SequenceType` `requiredType`
`protected Expression` `sequence`
`protected int` `slotNumber`
`protected StructuredQName` `variableName`

Fields inherited from class net.sf.saxon.expr.Expression
`EVALUATE_METHOD, ITERATE_METHOD, locationId, PROCESS_METHOD, staticProperties`

Constructor Summary
`Assignation()`

Method Summary
`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.
`ValueRepresentation` `evaluateVariable(XPathContext context)` Get the value of the range variable
`protected Binding[]` `extendBindingList(Binding[] in)` Extend an array of variable bindings to include the binding(s) defined in this expression
`Expression` `getAction()` Get the action expression
`int` `getLocalSlotNumber()` If this is a local variable held on the local stack frame, return the corresponding slot number.
`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
`java.lang.String` `getVariableName()` Get the display name of the range variable, for diagnostics only
`StructuredQName` `getVariableQName()` Get the name of the 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` `isUpdatingExpression()` Determine whether this is an updating expression as defined in the XQuery update specification
`java.util.Iterator` `iterateSubExpressions()` Get the immediate subexpressions of this expression
`Expression` `promote(PromotionOffer offer)` Promote this expression if possible
`protected Expression` `promoteWhereClause(Binding positionBinding)` Promote a WHERE clause whose condition doesn't depend on the variable being bound.
`void` `refineTypeInformation(ItemType type, int cardinality, Value constantValue, int properties, ExpressionVisitor visitor, Assignation currentExpression)` Refine the type information associated with this variable declaration.
`boolean` `replaceSubExpression(Expression original, Expression replacement)` Replace one subexpression by a replacement subexpression
`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` `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
`Expression` `simplify(ExpressionVisitor visitor)` Simplify the expression
`void` `suppressValidation(int validationMode)` Suppress validation on contained element constructors, on the grounds that the parent element is already performing validation.

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

`adoptChildExpression, checkPermittedContents, computeCardinality, computeDependencies, computeSpecialProperties, computeStaticProperties, copy, display, doPromotion, dynamicError, effectiveBooleanValue, evaluateAsString, evaluateItem, evaluatePendingUpdates, explain, explain, findParentOf, getCardinality, getColumnNumber, getColumnNumber, getConstructType, getContainer, getDependencies, getExecutable, getHostLanguage, getImplementationMethod, getIntrinsicDependencies, getItemType, getLineNumber, getLineNumber, getLocationId, getLocationProvider, getProperties, getProperty, getPublicId, getSlotsUsed, getSpecialProperties, getSystemId, getSystemId, hasLoopingSubexpression, implementsStaticTypeCheck, iterate, iterateEvents, markTailFunctionCalls, optimize, process, resetLocalStaticProperties, setContainer, setFiltered, setFlattened, setLocationId, staticTypeCheck, toString, typeCheck, typeError`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### slotNumber

    protected int slotNumber

### sequence

    protected Expression sequence

### action

    protected Expression action

### variableName

    protected StructuredQName variableName

### requiredType

    protected SequenceType requiredType

Constructor Detail

### Assignation

    public Assignation()

Method Detail

### 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: `InstructionInfo`
  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 `InstructionInfo`
  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

### 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 `Binding`
  Returns:
    the slot number on the local stack frame

### evaluateVariable

    public ValueRepresentation 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`

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

### simplify

    public Expression simplify(ExpressionVisitor visitor)
                        throws XPathException

  Simplify the expression

  Overrides:
    `simplify` in class `Expression`
  Parameters:
    `visitor` - an expression visitor
  Returns:
    the simplified expression
  Throws:
    `XPathException` - if an error is discovered during expression rewriting

### promote

    public Expression promote(PromotionOffer offer)
                       throws XPathException

  Promote this expression if possible

  Overrides:
    `promote` in class `Expression`
  Parameters:
    `offer` - details of the offer, for example the offer to move expressions that don't depend on the context to an outer level in the containing expression
  Returns:
    if the offer is not accepted, return this expression unchanged. Otherwise return the result of rewriting the expression to promote this subexpression
  Throws:
    `XPathException` - if any error is detected

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

### extendBindingList

    protected Binding[] extendBindingList(Binding[] in)

  Extend an array of variable bindings to include the binding(s) defined in this expression

  Parameters:
    `in` - a set of variable bindings
  Returns:
    a set of variable bindings including all those supplied plus this one

### promoteWhereClause

    protected Expression promoteWhereClause(Binding positionBinding)

  Promote a WHERE clause whose condition doesn't depend on the variable being bound. This rewrites an expression of the form

  let $i := SEQ return if (C) then R else ()

  to the form:

  if (C) then (let $i := SEQ return R) else ()

  Parameters:
    `positionBinding` - the binding of the position variable if any
  Returns:
    an expression in which terms from the WHERE clause that can be extracted have been extracted

### iterateSubExpressions

    public java.util.Iterator iterateSubExpressions()

  Get the immediate subexpressions of this expression

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

### replaceSubExpression

    public boolean replaceSubExpression(Expression original,
                                        Expression replacement)

  Replace one subexpression by a replacement subexpression

  Overrides:
    `replaceSubExpression` in class `Expression`
  Parameters:
    `original` - the original subexpression
    `replacement` - the replacement subexpression
  Returns:
    true if the original subexpression is found

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

### refineTypeInformation

    public void refineTypeInformation(ItemType type,
                                      int cardinality,
                                      Value constantValue,
                                      int properties,
                                      ExpressionVisitor visitor,
                                      Assignation currentExpression)

  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
    `visitor` - an expression visitor to provide context information
    `currentExpression` - the expression that binds the variable

Copyright (c) Saxonica Limited. All rights reserved.