Package net.sf.saxon.expr

## Class GeneralComparison

- java.lang.Object
- - net.sf.saxon.expr.Expression
  - - net.sf.saxon.expr.BinaryExpression
    - - net.sf.saxon.expr.GeneralComparison

- All Implemented Interfaces:
    `Callable`, `ComparisonExpression`, `ExportAgent`, `Locatable`, `IdentityComparable`, `Traceable`
  Direct Known Subclasses:
    `GeneralComparison20`, `GeneralComparisonEE`

      public abstract class GeneralComparison
      extends BinaryExpression
      implements ComparisonExpression, Callable

  GeneralComparison: a boolean expression that compares two expressions for equals, not-equals, greater-than or less-than. This implements the operators =, !=, <, >, etc. This implementation is not used when in backwards-compatible mode

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `GeneralComparison.ComparisonCardinality` |

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected AtomicComparer` | `comparer` |
    `protected GeneralComparison.ComparisonCardinality` | `comparisonCardinality` |
    `protected boolean` | `doneWarnings` |
    `protected boolean` | `needsRuntimeCheck` |
    `protected int` | `singletonOperator` |

    - ### Fields inherited from class net.sf.saxon.expr.BinaryExpression

      `operator`

    - ### 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
    --- | ---
    `GeneralComparison​(Expression p0, int op, Expression p1)` | Create a relational expression identifying the two operands and the operator

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `BooleanValue` | `call​(XPathContext context, Sequence[] arguments)` | Evaluate the expression
    `static boolean` | `compare​(AtomicValue a0, int operator, AtomicValue a1, AtomicComparer comparer, boolean checkTypes, XPathContext context, NamespaceResolver nsResolver)` | Compare two atomic values
    `int` | `computeCardinality()` | Determine the static cardinality.
    `boolean` | `convertsUntypedToOther()` | Determine whether untyped atomic values should be converted to the type of the other operand
    `boolean` | `effectiveBooleanValue​(XPathContext context)` | Evaluate the expression in a boolean context
    `boolean` | `equals​(java.lang.Object other)` | Is this expression the same as another expression?
    `BooleanValue` | `evaluateItem​(XPathContext context)` | Evaluate the expression in a given context
    `boolean` | `evaluateManyToMany​(SequenceIterator iter0, SequenceIterator iter1, XPathContext context)` | Evaluate a (zero-or-one)-to-(zero-or-one) comparison
    `protected void` | `explainExtraAttributes​(ExpressionPresenter out)` | Add subclass-specific attributes to the expression tree explanation.
    `AtomicComparer` | `getAtomicComparer()` | Get the AtomicComparer used to compare atomic values.
    `GeneralComparison.ComparisonCardinality` | `getComparisonCardinality()` | Ask whether the comparison is known to be many-to-one, one-to-one, or many-to-many.
    `static int` | `getCorrespondingSingletonOperator​(int op)` | Return the singleton form of the comparison operator, e.g.
    `java.lang.String` | `getExpressionName()` | Get a name identifying the kind of expression, in terms meaningful to a user.
    `int` | `getIntrinsicDependencies()` | Determine the intrinsic dependencies of an expression, that is, those which are not derived from the dependencies of its subexpressions.
    `protected GeneralComparison` | `getInverseComparison()` |
    `ItemType` | `getItemType()` | Determine the data type of the expression
    `NamespaceResolver` | `getNamespaceResolver()` | Get the namespace context for this expression, needed in the event that one operand contains untyped atomic values and the other contains QNames
    `int` | `getSingletonOperator()` | Get the primitive (singleton) operator used: one of Token.FEQ, Token.FNE, Token.FLT, Token.FGT, Token.FLE, Token.FGE
    `UType` | `getStaticUType​(UType contextItemType)` | Get the static type of the expression as a UType, following precisely the type inference rules defined in the XSLT 3.0 specification.
    `java.lang.String` | `getStreamerName()` | Get the (partial) name of a class that supports streaming of this kind of expression
    `boolean` | `needsRuntimeCheck()` | Ask whether a runtime check of the types of the operands is needed
    `Expression` | `optimize​(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo)` | Optimize the expression
    `void` | `setAtomicComparer​(AtomicComparer comparer)` | Set the comparer to be used
    `void` | `setComparisonCardinality​(GeneralComparison.ComparisonCardinality card)` | Say whether the comparison is known to be many-to-one, one-to-one, or many-to-many.
    `void` | `setNeedsRuntimeCheck​(boolean needsCheck)` | Say whether a runtime check of the types of the operands is needed
    `java.lang.String` | `tag()` | Get the element name used to identify this expression in exported expression format
    `Expression` | `typeCheck​(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo)` | Type-check the expression

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

      `computeHashCode, computeSpecialProperties, displayOperator, export, getImplementationMethod, getLhs, getLhsExpression, getOperandRole, getOperator, getRhs, getRhsExpression, isAssociative, isCommutative, isInverse, operands, setFlattened, setLhsExpression, setRhsExpression, toShortString, toString`

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

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

      `getLhs, getLhsExpression, getRhs, getRhsExpression`

    - ### Methods inherited from interface net.sf.saxon.trace.Traceable

      `gatherProperties`

- - ### Field Detail

    - #### singletonOperator

          protected int singletonOperator

    - #### comparer

          protected AtomicComparer comparer

    - #### needsRuntimeCheck

          protected boolean needsRuntimeCheck

    - #### comparisonCardinality

          protected GeneralComparison.ComparisonCardinality comparisonCardinality

    - #### doneWarnings

          protected boolean doneWarnings

  - ### Constructor Detail

    - #### GeneralComparison

          public GeneralComparison​(Expression p0,
                                   int op,
                                   Expression p1)

      Create a relational expression identifying the two operands and the operator
      Parameters:
        `p0` - the left-hand operand
        `op` - the operator, as a token returned by the Tokenizer (e.g. Token.LT)
        `p1` - the right-hand operand

  - ### Method Detail

    - #### needsRuntimeCheck

          public boolean needsRuntimeCheck()

      Ask whether a runtime check of the types of the operands is needed
      Returns:
        true if the types of the operands need to be checked at run-time

    - #### setNeedsRuntimeCheck

          public void setNeedsRuntimeCheck​(boolean needsCheck)

      Say whether a runtime check of the types of the operands is needed
      Parameters:
        `needsCheck` - true if the types of the operands need to be checked at run-time

    - #### getComparisonCardinality

          public GeneralComparison.ComparisonCardinality getComparisonCardinality()

      Ask whether the comparison is known to be many-to-one, one-to-one, or many-to-many. (Note, an expression that is one-to-many will be converted to one that is many-to-one).
      Returns:
        the Cardinality of the comparison as one of the values `GeneralComparison.ComparisonCardinality.ONE_TO_ONE`, `GeneralComparison.ComparisonCardinality.MANY_TO_MANY`, `GeneralComparison.ComparisonCardinality.MANY_TO_ONE`

    - #### setComparisonCardinality

          public void setComparisonCardinality​(GeneralComparison.ComparisonCardinality card)

      Say whether the comparison is known to be many-to-one, one-to-one, or many-to-many.
      Parameters:
        `card` - the Cardinality of the comparison as one of the values `GeneralComparison.ComparisonCardinality.ONE_TO_ONE`, `GeneralComparison.ComparisonCardinality.MANY_TO_MANY`, `GeneralComparison.ComparisonCardinality.MANY_TO_ONE`

    - #### setAtomicComparer

          public void setAtomicComparer​(AtomicComparer comparer)

      Set the comparer to be used
      Parameters:
        `comparer` - the comparer to be used

    - #### 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 explain() output displaying the expression.

    - #### getNamespaceResolver

          public NamespaceResolver getNamespaceResolver()

      Get the namespace context for this expression, needed in the event that one operand contains untyped atomic values and the other contains QNames

    - #### getAtomicComparer

          public AtomicComparer getAtomicComparer()

      Get the AtomicComparer used to compare atomic values. This encapsulates any collation that is used
      Specified by:
        `getAtomicComparer` in interface `ComparisonExpression`

    - #### getSingletonOperator

          public int getSingletonOperator()

      Get the primitive (singleton) operator used: one of Token.FEQ, Token.FNE, Token.FLT, Token.FGT, Token.FLE, Token.FGE
      Specified by:
        `getSingletonOperator` in interface `ComparisonExpression`

    - #### convertsUntypedToOther

          public boolean convertsUntypedToOther()

      Determine whether untyped atomic values should be converted to the type of the other operand
      Specified by:
        `convertsUntypedToOther` in interface `ComparisonExpression`
      Returns:
        true if untyped values should be converted to the type of the other operand, false if they should be converted to strings.

    - #### computeCardinality

          public int computeCardinality()

      Determine the static cardinality. Returns [1..1]
      Overrides:
        `computeCardinality` in class `BinaryExpression`
      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`. May also return `StaticProperty.ALLOWS_ZERO` if the result is known to be an empty sequence, or `StaticProperty.ALLOWS_MANY` if if is known to return a sequence of length two or more.

    - #### typeCheck

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

      Type-check the expression
      Overrides:
        `typeCheck` in class `BinaryExpression`
      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 checked expression
      Throws:
        `XPathException` - if an error is discovered during this phase (typically a type error)

    - #### getIntrinsicDependencies

          public int getIntrinsicDependencies()

      Description copied from class: `Expression`
      Determine the intrinsic dependencies of an expression, that is, those which are not derived from the dependencies of its subexpressions. For example, position() has an intrinsic dependency on the context position, while (position()+1) does not. The default implementation of the method returns 0, indicating "no dependencies".
      Overrides:
        `getIntrinsicDependencies` in class `Expression`
      Returns:
        a set of bit-significant flags identifying the "intrinsic" dependencies. The flags are documented in class net.sf.saxon.value.StaticProperty

    - #### equals

          public boolean equals​(java.lang.Object other)

      Description copied from class: `BinaryExpression`
      Is this expression the same as another expression?
      Overrides:
        `equals` in class `BinaryExpression`
      Parameters:
        `other` - the other operand; the result is false if this is not an Expression
      Returns:
        true if the other operand is an expression and if it can be determined that the two expressions are equivalent, in the sense that they will always return the same result.

    - #### optimize

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

      Optimize the expression
      Overrides:
        `optimize` in class `BinaryExpression`
      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 checked expression
      Throws:
        `XPathException` - if an error is discovered during this phase (typically a type error)

    - #### evaluateItem

          public BooleanValue evaluateItem​(XPathContext context)
                                    throws XPathException

      Evaluate the expression in a given context
      Overrides:
        `evaluateItem` in class `Expression`
      Parameters:
        `context` - the given context for evaluation
      Returns:
        a BooleanValue representing the result of the numeric comparison of the two operands
      Throws:
        `XPathException` - if any dynamic error occurs evaluating the expression

    - #### call

          public BooleanValue call​(XPathContext context,
                                   Sequence[] arguments)
                            throws XPathException

      Evaluate the expression
      Specified by:
        `call` in interface `Callable`
      Parameters:
        `context` - the dynamic evaluation context
        `arguments` - the values of the arguments, supplied as SequenceIterators
      Returns:
        the result of the evaluation, in the form of a SequenceIterator
      Throws:
        `XPathException` - if a dynamic error occurs during the evaluation of the expression

    - #### effectiveBooleanValue

          public boolean effectiveBooleanValue​(XPathContext context)
                                        throws XPathException

      Evaluate the expression in a boolean context
      Overrides:
        `effectiveBooleanValue` in class `Expression`
      Parameters:
        `context` - the given context for evaluation
      Returns:
        a boolean representing the result of the numeric comparison of the two operands
      Throws:
        `XPathException` - if any dynamic error occurs evaluating the expression

    - #### evaluateManyToMany

          public boolean evaluateManyToMany​(SequenceIterator iter0,
                                            SequenceIterator iter1,
                                            XPathContext context)
                                     throws XPathException

      Evaluate a (zero-or-one)-to-(zero-or-one) comparison
      Parameters:
        `iter0` - iterator over the first value
        `iter1` - iterator the second value
        `context` - dynamic evaluation context
      Returns:
        the comparison result
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### compare

          public static boolean compare​(AtomicValue a0,
                                        int operator,
                                        AtomicValue a1,
                                        AtomicComparer comparer,
                                        boolean checkTypes,
                                        XPathContext context,
                                        NamespaceResolver nsResolver)
                                 throws XPathException

      Compare two atomic values
      Parameters:
        `a0` - the first value
        `operator` - the singleton version of the comparison operator, for example `Token.FEQ`
        `a1` - the second value
        `comparer` - the comparer to be used to perform the comparison. If the comparer is context-sensitive then the context must already have been bound using comparer.provideContext().
        `checkTypes` - set to true if the operand types need to be checked for comparability at runtime
        `context` - the XPath evaluation context
        `nsResolver` - namespace resolver
      Returns:
        true if the comparison succeeds
      Throws:
        `XPathException` - if a dynamic error occurs during the comparison

    - #### getItemType

          public ItemType getItemType()

      Determine the data type of the expression
      Specified by:
        `getItemType` in class `Expression`
      Returns:
        the value BuiltInAtomicType.BOOLEAN

    - #### getStaticUType

          public UType getStaticUType​(UType contextItemType)

      Get the static type of the expression as a UType, following precisely the type inference rules defined in the XSLT 3.0 specification.
      Overrides:
        `getStaticUType` in class `Expression`
      Parameters:
        `contextItemType` - static information about the context item
      Returns:
        the static item type of the expression according to the XSLT 3.0 defined rules

    - #### getCorrespondingSingletonOperator

          public static int getCorrespondingSingletonOperator​(int op)

      Return the singleton form of the comparison operator, e.g. FEQ for EQUALS, FGT for GT
      Parameters:
        `op` - the many-to-many form of the operator, for example `Token.LE`
      Returns:
        the corresponding singleton operator, for example `Token.FLE`

    - #### getInverseComparison

          protected GeneralComparison getInverseComparison()

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

    - #### tag

          public java.lang.String tag()

      Get the element name used to identify this expression in exported expression format
      Overrides:
        `tag` in class `BinaryExpression`
      Returns:
        the element name used to identify this expression

    - #### explainExtraAttributes

          protected void explainExtraAttributes​(ExpressionPresenter out)

      Description copied from class: `BinaryExpression`
      Add subclass-specific attributes to the expression tree explanation. Default implementation does nothing; this is provided for subclasses to override.
      Overrides:
        `explainExtraAttributes` in class `BinaryExpression`
      Parameters:
        `out` - the output destination for the displayed expression tree