Package net.sf.saxon.expr.instruct

## Class IterateInstr

- java.lang.Object
- - net.sf.saxon.expr.Expression
  - - net.sf.saxon.expr.instruct.Instruction
    - - net.sf.saxon.expr.instruct.IterateInstr

- All Implemented Interfaces:
    `ContextOriginator`, `ContextSwitchingExpression`, `ExportAgent`, `TailCallReturner`, `Locatable`, `IdentityComparable`, `Traceable`

      public final class IterateInstr
      extends Instruction
      implements ContextSwitchingExpression

  An IterateInstr is the compiled form of an xsl:iterate instruction

- - ### Field Summary

    - ### 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
    --- | ---
    `IterateInstr​(Expression select, LocalParamBlock initiallyExp, Expression action, Expression onCompletion)` | Create an xsl:iterate instruction

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `checkPermittedContents​(SchemaType parentType, boolean whole)` | Check that any elements and attributes constructed or returned by this expression are acceptable in the content model of a given complex type.
    `Expression` | `copy​(RebindingMap rebindings)` | Copy an expression.
    `void` | `export​(ExpressionPresenter out)` | Diagnostic print of expression structure.
    `Expression` | `getActionExpression()` | Get the action expression (the content of the xsl:iterate)
    `int` | `getImplementationMethod()` | An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process().
    `LocalParamBlock` | `getInitiallyExp()` |
    `int` | `getInstructionNameCode()` | Get the namecode of the instruction for use in diagnostics
    `ItemType` | `getItemType()` | Determine the data type of the items returned by this expression
    `Expression` | `getOnCompletion()` |
    `Expression` | `getSelectExpression()` | Get the select expression (the select attribute of the xsl:iterate)
    `java.lang.String` | `getStreamerName()` | Get the (partial) name of a class that supports streaming of this kind of expression
    `boolean` | `hasVariableBinding​(Binding binding)` | Ask whether this expression is, or contains, the binding of a given variable
    `boolean` | `isCompilable()` | Test whether it is possible to generate byte-code for the instruction.
    `boolean` | `mayCreateNewNodes()` | Determine whether this instruction creates new nodes.
    `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.
    `Expression` | `optimize​(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo)` | Perform optimisation of an expression and its subexpressions.
    `TailCall` | `processLeavingTail​(Outputter output, XPathContext context)` | ProcessLeavingTail: called to do the real work of this instruction.
    `void` | `setAction​(Expression action)` |
    `void` | `setInitiallyExp​(LocalParamBlock initiallyExp)` |
    `void` | `setOnCompletion​(Expression onCompletion)` |
    `void` | `setSelect​(Expression select)` |
    `Expression` | `typeCheck​(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo)` | Type-check the expression

    - ### Methods inherited from class net.sf.saxon.expr.instruct.Instruction

      `alwaysCreatesNewNodes, assembleParams, assembleTunnelParams, computeCardinality, computeSpecialProperties, dynamicError, evaluateAsString, evaluateItem, getExpressionName, getNetCost, getSourceLocator, isInstruction, isXSLT, iterate, process, someOperandCreatesNewNodes`

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

      `addToPathMap, adoptChildExpression, allowExtractingCommonSubexpressions, checkedOperands, checkForUpdatingSubexpressions, computeDependencies, computeHashCode, computeStaticProperties, dynamicError, effectiveBooleanValue, equals, evaluatePendingUpdates, explain, getCardinality, getConfiguration, getCost, getDependencies, getEvaluationMethod, getExtraProperty, getIntegerBounds, getInterpretedExpression, getIntrinsicDependencies, getLocalRetainedStaticContext, getLocation, getObjectName, getPackageData, getParentExpression, getProperties, getProperty, getRetainedStaticContext, getScopingExpression, getSlotsUsed, getSpecialProperties, getStaticBaseURI, getStaticBaseURIString, getStaticType, getStaticUType, getTracingTag, hasCompatibleStaticContext, hashCode, hasSpecialProperty, identityHashCode, implementsStaticTypeCheck, isCallOn, isEqual, isIdentical, isLiftable, isMultiThreaded, isStaticPropertiesKnown, isSubtreeExpression, isUpdatingExpression, isVacuousExpression, markTailFunctionCalls, operandList, operandSparseList, optimizeChildren, prepareForStreaming, resetLocalStaticProperties, restoreParentPointers, setEvaluationMethod, setExtraProperty, setFiltered, setFlattened, setLocation, setParentExpression, setRetainedStaticContext, setRetainedStaticContextLocally, setRetainedStaticContextThoroughly, setStaticProperty, simplify, simplifyChildren, staticTypeCheck, suppressValidation, toPattern, toShortString, toString, typeCheckChildren, typeError, unordered, 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`

- - ### Constructor Detail

    - #### IterateInstr

          public IterateInstr​(Expression select,
                              LocalParamBlock initiallyExp,
                              Expression action,
                              Expression onCompletion)

      Create an xsl:iterate instruction
      Parameters:
        `select` - the select expression
        `initiallyExp` - the initialization of the xsl:param elements
        `action` - the body of the xsl:iterate loop
        `onCompletion` - the expression to be evaluated before final completion, may be null

  - ### Method Detail

    - #### setSelect

          public void setSelect​(Expression select)

    - #### getInitiallyExp

          public LocalParamBlock getInitiallyExp()

    - #### setInitiallyExp

          public void setInitiallyExp​(LocalParamBlock initiallyExp)

    - #### setAction

          public void setAction​(Expression action)

    - #### getOnCompletion

          public Expression getOnCompletion()

    - #### setOnCompletion

          public void setOnCompletion​(Expression onCompletion)

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

      Specified by:
        `operands` in class `Instruction`
      Returns:
        an iterator containing the sub-expressions of this expression

    - #### getInstructionNameCode

          public int getInstructionNameCode()

      Get the namecode of the instruction for use in diagnostics
      Overrides:
        `getInstructionNameCode` in class `Instruction`
      Returns:
        a code identifying the instruction: typically but not always the fingerprint of a name in the XSLT namespace

    - #### getSelectExpression

          public Expression getSelectExpression()

      Get the select expression (the select attribute of the xsl:iterate)
      Specified by:
        `getSelectExpression` in interface `ContextSwitchingExpression`
      Returns:
        the select expression

    - #### getActionExpression

          public Expression getActionExpression()

      Get the action expression (the content of the xsl:iterate)
      Specified by:
        `getActionExpression` in interface `ContextSwitchingExpression`
      Returns:
        the body of the xsl:iterate loop

    - #### typeCheck

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

      Type-check the expression
      Overrides:
        `typeCheck` in class `Expression`
      Parameters:
        `visitor` - an expression visitor
        `contextInfo` - Information available statically about the context item: whether it is (possibly) absent; its static type; its streaming posture.
      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)

    - #### optimize

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

      Description copied from class: `Expression`
      Perform optimisation of an expression and its subexpressions. This is the third and final phase of static optimization.

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

    - #### isCompilable

          public boolean isCompilable()

      Test whether it is possible to generate byte-code for the instruction. This is not possible unless any xsl:break or xsl:next-iteration instructions are part of the same compilation unit, which is not the case if they appear within a try-catch.
      Returns:
        true if the instruction does not contain an xsl:break or xsl:next-iteration instruction within a try/catch block

    - #### getItemType

          public final ItemType getItemType()

      Determine the data type of the items returned by this expression
      Overrides:
        `getItemType` in class `Instruction`
      Returns:
        the data type

    - #### mayCreateNewNodes

          public final boolean mayCreateNewNodes()

      Determine whether this instruction creates new nodes. This implementation returns true if the "action" creates new nodes. (Nodes created by the condition can't contribute to the result).
      Overrides:
        `mayCreateNewNodes` in class `Instruction`
      Returns:
        true if the instruction creates new nodes under some input conditions (or if it can't be proved that it doesn't)

    - #### hasVariableBinding

          public boolean hasVariableBinding​(Binding binding)

      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.

    - #### getStreamerName

          public java.lang.String getStreamerName()

      Get the (partial) name of a class that supports streaming of this kind of expression
      Overrides:
        `getStreamerName` in class `Expression`
      Returns:
        the partial name of a class that can be instantiated to provide streaming support in Saxon-EE, or null if there is no such class

    - #### getImplementationMethod

          public int getImplementationMethod()

      An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process(). This method indicates which of these methods is provided. This implementation provides both iterate() and process() methods natively.
      Overrides:
        `getImplementationMethod` in class `Instruction`
      Returns:
        the implementation method, for example `Expression.ITERATE_METHOD` or `Expression.EVALUATE_METHOD` or `Expression.PROCESS_METHOD`

    - #### checkPermittedContents

          public void checkPermittedContents​(SchemaType parentType,
                                             boolean whole)
                                      throws XPathException

      Check that any elements and attributes constructed or returned by this expression are acceptable in the content model of a given complex type. It's always OK to say yes, since the check will be repeated at run-time. The process of checking element and attribute constructors against the content model of a complex type also registers the type of content expected of those constructors, so the static validation can continue recursively.
      Overrides:
        `checkPermittedContents` in class `Expression`
      Parameters:
        `parentType` - the "given complex type": the method is checking that the nodes returned by this expression are acceptable members of the content model of this type
        `whole` - if true, we want to check that the value of this expression satisfies the content model as a whole; if false we want to check that the value of the expression is acceptable as one part of the content
      Throws:
        `XPathException` - if the value delivered by this expression cannot be part of the content model of the given type

    - #### copy

          public Expression copy​(RebindingMap rebindings)

      Copy an expression. This makes a deep copy.
      Specified by:
        `copy` in class `Expression`
      Parameters:
        `rebindings` - a mutable list of (old binding, new binding) pairs that is used to update the bindings held in any local variable references that are copied.
      Returns:
        the copy of the original expression

    - #### processLeavingTail

          public TailCall processLeavingTail​(Outputter output,
                                             XPathContext context)
                                      throws XPathException

      Description copied from class: `Instruction`
      ProcessLeavingTail: called to do the real work of this instruction. This method must be implemented in each subclass. The results of the instruction are written to the current Receiver, which can be obtained via the Controller.
      Specified by:
        `processLeavingTail` in interface `TailCallReturner`
      Specified by:
        `processLeavingTail` in class `Instruction`
      Parameters:
        `output` - the destination for the result
        `context` - The dynamic context of the transformation, giving access to the current node, the current variables, etc.
      Returns:
        null if the instruction has completed execution; or a TailCall indicating a function call or template call that is delegated to the caller, to be made after the stack has been unwound so as to save stack space.
      Throws:
        `XPathException` - if a dynamic error occurs during the evaluation of the instruction

    - #### 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`
      Specified by:
        `export` in class `Expression`
      Parameters:
        `out` - the expression presenter used to display the structure
      Throws:
        `XPathException` - if the export fails, for example if an expression is found that won't work in the target environment.