Package com.saxonica.ee.optim

## Class SwitchExpression

- java.lang.Object
- - net.sf.saxon.expr.Expression
  - - com.saxonica.ee.optim.SwitchExpression

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

      public class SwitchExpression
      extends Expression
      implements TailCallReturner, ConditionalInstruction

  An optimized Choose expression in which all the branches are tests of the same expression for equality with some value. Note this is not quite the same as the XQuery 3.1 switch expression; this switch expression is usually generated as the result of optimizing an xsl:choose or extended if/then/else expression.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `SwitchExpression.SwitchCaseInfo` | Data structure used for holding details of a switch expression

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static OperandRole` | `SUBJECT` |

    - ### 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
    --- | ---
    `SwitchExpression​(SwitchExpression.SwitchCaseInfo switchCaseInfo)` | Create a switch expression

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `allowExtractingCommonSubexpressions()` | Ask whether common subexpressions found in the operands of this expression can be extracted and evaluated outside the expression itself.
    `protected int` | `computeCardinality()` | Compute the static cardinality of this expression
    `Expression` | `copy​(RebindingMap rebindings)` | Copy an expression.
    `Item` | `evaluateItem​(XPathContext context)` | Evaluate an expression as a single item.
    `void` | `export​(ExpressionPresenter out)` | Diagnostic print of expression structure.
    `Operand` | `getAction​(int index)` |
    `java.util.List<Operand>` | `getActions()` |
    `java.util.Map<AtomicMatchKey,​java.lang.Integer>` | `getCaseMap()` | Get the map from XPathComparable objects representing the values to the expressions to be executed for each of these values
    `StringCollator` | `getCollation()` | Get the collation used
    `java.lang.String` | `getExpressionName()` | Get a name identifying the kind of expression, in terms meaningful to a user.
    `int` | `getImplementationMethod()` | An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process().
    `ItemType` | `getItemType()` | Determine the data type of the expression, if possible.
    `Expression` | `getOtherwiseExpression()` | Get the default ("otherwise") expression
    `Operand` | `getOtherwiseOperand()` |
    `java.lang.String` | `getStreamerName()` | Get the (partial) name of a class that supports streaming of this kind of expression
    `Expression` | `getSubjectExpression()` | Get the subject expression (the expression that computes the switch value)
    `boolean` | `isInstruction()` | Ask whether this expression is an instruction.
    `SequenceIterator` | `iterate​(XPathContext context)` | Return an Iterator to iterate over the values of a sequence.
    `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` | `process​(Outputter output, XPathContext context)` | Process the instruction, without returning any tail calls
    `TailCall` | `processLeavingTail​(Outputter output, XPathContext context)` | ProcessLeavingTail: called to do the real work of this instruction.
    `void` | `setInstruction​(boolean inst)` | Say whether this switch expression originates as an XSLT instruction
    `Expression` | `unordered​(boolean retainAllNodes, boolean forStreaming)` | Replace this expression by a simpler expression that delivers the results without regard to order.

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

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

    - #### SUBJECT

          public static final OperandRole SUBJECT

  - ### Constructor Detail

    - #### SwitchExpression

          public SwitchExpression​(SwitchExpression.SwitchCaseInfo switchCaseInfo)

      Create a switch expression
      Parameters:
        `switchCaseInfo` - details of the expression to be constructed

  - ### Method Detail

    - #### setInstruction

          public void setInstruction​(boolean inst)

      Say whether this switch expression originates as an XSLT instruction
      Parameters:
        `inst` - true if this started life as an xsl:choose instruction

    - #### isInstruction

          public boolean isInstruction()

      Ask whether this expression is an instruction. In XSLT streamability analysis this is used to distinguish constructs corresponding to XSLT instructions from other constructs.
      Overrides:
        `isInstruction` in class `Expression`
      Returns:
        true if this construct originates as an XSLT instruction

    - #### getSubjectExpression

          public Expression getSubjectExpression()

      Get the subject expression (the expression that computes the switch value)
      Returns:
        the expression that computes the switch value

    - #### getCaseMap

          public java.util.Map<AtomicMatchKey,​java.lang.Integer> getCaseMap()

      Get the map from XPathComparable objects representing the values to the expressions to be executed for each of these values
      Returns:
        the map of case clauses

    - #### getOtherwiseExpression

          public Expression getOtherwiseExpression()

      Get the default ("otherwise") expression
      Returns:
        the "otherwise" expression giving the value to be returned if none of the cases match

    - #### getAction

          public Operand getAction​(int index)

    - #### getActions

          public java.util.List<Operand> getActions()

    - #### getOtherwiseOperand

          public Operand getOtherwiseOperand()

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

    - #### getCollation

          public StringCollator getCollation()

      Get the collation used
      Returns:
        the collation

    - #### computeCardinality

          protected int computeCardinality()

      Compute the static cardinality of this expression
      Specified by:
        `computeCardinality` in class `Expression`
      Returns:
        the computed cardinality, as one of the values `StaticProperty.ALLOWS_ZERO_OR_ONE`, `StaticProperty.EXACTLY_ONE`, `StaticProperty.ALLOWS_ONE_OR_MORE`, `StaticProperty.ALLOWS_ZERO_OR_MORE`

    - #### allowExtractingCommonSubexpressions

          public boolean allowExtractingCommonSubexpressions()

      Ask whether common subexpressions found in the operands of this expression can be extracted and evaluated outside the expression itself. The result is irrelevant in the case of operands evaluated with a different focus, which will never be extracted in this way, even if they have no focus dependency.
      Overrides:
        `allowExtractingCommonSubexpressions` in class `Expression`
      Returns:
        false for this kind of expression

    - #### copy

          public Expression copy​(RebindingMap rebindings)

      Copy an expression. This makes a deep copy.
      Specified by:
        `copy` in class `Expression`
      Parameters:
        `rebindings` - variables that need to be re-bound
      Returns:
        the copy of the original expression

    - #### export

          public void export​(ExpressionPresenter out)
                      throws XPathException

      Diagnostic print of expression structure. The abstract expression tree is written to the supplied output destination.
      Specified by:
        `export` in interface `ExportAgent`
      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.

    - #### getItemType

          public ItemType getItemType()

      Determine the data type of the expression, if possible. All expression return sequences, in general; this method determines the type of the items within the sequence, assuming that (a) this is known in advance, and (b) it is the same for all items in the sequence.

      This method should always return a result, though it may be the best approximation that is available at the time.

      Specified by:
        `getItemType` in class `Expression`
      Returns:
        a value such as Type.STRING, Type.BOOLEAN, Type.NUMBER, Type.NODE, or Type.ITEM (meaning not known at compile time)

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

    - #### evaluateItem

          public Item evaluateItem​(XPathContext context)
                            throws XPathException

      Evaluate an expression as a single item. This always returns either a single Item or null (denoting the empty sequence). No conversion is done. This method should not be used unless the static type of the expression is a subtype of "item" or "item?": that is, it should not be called if the expression may return a sequence. There is no guarantee that this condition will be detected.
      Overrides:
        `evaluateItem` in class `Expression`
      Parameters:
        `context` - The context in which the expression is to be evaluated
      Returns:
        the node or atomic value that results from evaluating the expression; or null to indicate that the result is an empty sequence
      Throws:
        `XPathException` - if any dynamic error occurs evaluating the expression

    - #### iterate

          public SequenceIterator iterate​(XPathContext context)
                                   throws XPathException

      Return an Iterator to iterate over the values of a sequence. The value of every expression can be regarded as a sequence, so this method is supported for all expressions. This default implementation handles iteration for expressions that return singleton values: for non-singleton expressions, the subclass must provide its own implementation.
      Overrides:
        `iterate` in class `Expression`
      Parameters:
        `context` - supplies the context for evaluation
      Returns:
        a SequenceIterator that can be used to iterate over the result of the expression
      Throws:
        `XPathException` - if any dynamic error occurs evaluating the expression

    - #### process

          public void process​(Outputter output,
                              XPathContext context)
                       throws XPathException

      Process the instruction, without returning any tail calls
      Overrides:
        `process` in class `Expression`
      Parameters:
        `output` - the destination for the result
        `context` - The dynamic context, giving access to the current node,
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### processLeavingTail

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

      Description copied from interface: `TailCallReturner`
      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`
      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

    - #### getImplementationMethod

          public int getImplementationMethod()

      Description copied from class: `Expression`
      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 directly. The other methods will always be available indirectly, using an implementation that relies on one of the other methods.
      Specified by:
        `getImplementationMethod` in class `Expression`
      Returns:
        the implementation method, for example `Expression.ITERATE_METHOD` or `Expression.EVALUATE_METHOD` or `Expression.PROCESS_METHOD`

    - #### getExpressionName

          public java.lang.String getExpressionName()

      Get a name identifying the kind of expression, in terms meaningful to a user.
      Overrides:
        `getExpressionName` in class `Expression`
      Returns:
        a name identifying the kind of expression, in terms meaningful to a user. The name will always be in the form of a lexical XML QName, and should match the name used in export() output displaying the expression.

    - #### getStreamerName

          public java.lang.String getStreamerName()

      Description copied from class: `Expression`
      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