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:
    Serializable, SourceLocator, LocationProvider, SaxonLocator, Callable, ComparisonExpression, InstructionInfo, Locator
  Direct Known Subclasses:
    GeneralComparison20, GeneralComparisonEE

      public 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
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected AtomicComparer` | `comparer`
    `protected int` | `comparisonCardinality`
    `static int` | `MANY_TO_MANY`
    `static int` | `MANY_TO_ONE`
    `protected boolean` | `needsRuntimeCheck`
    `static int` | `ONE_TO_ONE`
    `protected int` | `singletonOperator`

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

      `operand0, operand1, operator`

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

      `EFFECTIVE_BOOLEAN_VALUE, EVALUATE_METHOD, EVENT_FEED_METHOD, INHERITED_CONTEXT, INSPECTION_CONTEXT, ITEM_FEED_METHOD, ITERATE_METHOD, locationId, MAX_SEQUENCE_LENGTH, MAX_STRING_LENGTH, NAVIGATION_CONTEXT, NODE_VALUE_CONTEXT, PROCESS_METHOD, PUSH_SELECTION, staticProperties, UNBOUNDED_LOWER, UNBOUNDED_UPPER, W3C_CONSUMING, W3C_FREE_RANGING, W3C_GROUP_CONSUMING, W3C_MOTIONLESS, WATCH_METHOD`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GeneralComparison(Expression p0, int op, Expression p1)` Create a relational expression identifying the two operands and the operator

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Sequence` | `call(XPathContext context, Sequence[] arguments)` Evaluate the expression
    `static boolean` | `compare(AtomicValue a0, int operator, AtomicValue a1, AtomicComparer comparer, boolean checkTypes, XPathContext context)` 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
    `Expression` | `copy()` Copy an expression.
    `boolean` | `effectiveBooleanValue(XPathContext context)` Evaluate the expression in a boolean context
    `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.
    `int` | `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.
    `ExpressionCompiler` | `getExpressionCompiler()` Return the compiler of the GeneralComparison expression
    `String` | `getExpressionName()` Get a name identifying the kind of expression, in terms meaningful to a user.
    `protected GeneralComparison` | `getInverseComparison()`
    `ItemType` | `getItemType(TypeHierarchy th)` Determine the data type of the expression
    `int` | `getSingletonOperator()` Get the primitive (singleton) operator used: one of Token.FEQ, Token.FNE, Token.FLT, Token.FGT, Token.FLE, Token.FGE
    `GeneralComparisonAdjunct` | `getStreamingAdjunct()` Get a class that supports streamed evaluation of this expression
    `boolean` | `needsRuntimeCheck()` Ask whether a runtime check of the types of the operands is needed
    `Expression` | `optimize(ExpressionVisitor visitor, ExpressionVisitor.ContextItemType contextItemType)` Optimize the expression
    `void` | `setAtomicComparer(AtomicComparer comparer)` Set the comparer to be used
    `void` | `setComparisonCardinality(int 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
    `Expression` | `simplify(ExpressionVisitor visitor)` Simplify an expression
    `Expression` | `typeCheck(ExpressionVisitor visitor, ExpressionVisitor.ContextItemType contextItemType)` Type-check the expression

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

      `computeSpecialProperties, displayOperator, equals, explain, getArguments, getOperands, getOperator, hashCode, isAssociative, isCommutative, isInverse, iterateSubExpressionInfo, iterateSubExpressions, promote, replaceSubExpression, setFlattened, toString`

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

      `addToPathMap, adoptChildExpression, checkForUpdatingSubexpressions, checkPermittedContents, computeDependencies, computeStaticProperties, doPromotion, dynamicError, evaluateAsString, evaluatePendingUpdates, explain, getCardinality, getColumnNumber, getColumnNumber, getConstructType, getContainer, getDependencies, getEvaluationMethod, getExecutable, getHostLanguage, getImplementationMethod, getIntegerBounds, getIntrinsicDependencies, getLineNumber, getLineNumber, getLocationId, getLocationProvider, getObjectName, getProperties, getProperty, getPublicId, getSlotsUsed, getSpecialProperties, getStreamability, getSystemId, getSystemId, hasVariableBinding, implementsStaticTypeCheck, isSubtreeExpression, isUpdatingExpression, isVacuousExpression, iterate, iterateEvents, markTailFunctionCalls, process, resetLocalStaticProperties, setContainer, setEvaluationMethod, setFiltered, setLocationId, staticTypeCheck, suppressValidation, toPattern, toStreamingPattern, typeError`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface net.sf.saxon.expr.ComparisonExpression

      `getOperands`

- - ### Field Detail

    - #### ONE_TO_ONE

          public static final int ONE_TO_ONE

      See Also:
        Constant Field Values

    - #### MANY_TO_ONE

          public static final int MANY_TO_ONE

      See Also:
        Constant Field Values

    - #### MANY_TO_MANY

          public static final int MANY_TO_MANY

      See Also:
        Constant Field Values

    - #### singletonOperator

          protected int singletonOperator

    - #### comparer

          protected AtomicComparer comparer

    - #### needsRuntimeCheck

          protected boolean needsRuntimeCheck

    - #### comparisonCardinality

          protected int comparisonCardinality

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

    - #### setNeedsRuntimeCheck

          public void setNeedsRuntimeCheck(boolean needsCheck)

      Say whether a runtime check of the types of the operands is needed

    - #### getComparisonCardinality

          public int 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).

    - #### setComparisonCardinality

          public void setComparisonCardinality(int card)

      Say whether the comparison is known to be many-to-one, one-to-one, or many-to-many.

    - #### setAtomicComparer

          public void setAtomicComparer(AtomicComparer comparer)

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

    - #### simplify

          public Expression simplify(ExpressionVisitor visitor)
                              throws XPathException

      Description copied from class: `BinaryExpression`
      Simplify an expression
      Overrides:
        `simplify` in class `BinaryExpression`
      Parameters:
        `visitor` - an expression visitor
      Returns:
        the simplified expression
      Throws:
        `XPathException` - if an error is discovered during expression rewriting

    - #### getExpressionName

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

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

    - #### typeCheck

          public Expression typeCheck(ExpressionVisitor visitor,
                             ExpressionVisitor.ContextItemType contextItemType)
                               throws XPathException

      Type-check the expression
      Overrides:
        `typeCheck` in class `BinaryExpression`
      Parameters:
        `visitor` - an expression visitor
        `contextItemType` - 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)

    - #### optimize

          public Expression optimize(ExpressionVisitor visitor,
                            ExpressionVisitor.ContextItemType contextItemType)
                              throws XPathException

      Optimize the expression
      Overrides:
        `optimize` in class `BinaryExpression`
      Parameters:
        `visitor` - an expression visitor
        `contextItemType` - 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)

    - #### copy

          public Expression copy()

      Copy an expression. This makes a deep copy.
      Specified by:
        `copy` in class `Expression`
      Returns:
        the copy of the original expression

    - #### 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 Sequence 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)
                                 throws XPathException

      Compare two atomic values
      Parameters:
        `a0` - the first value
        `operator` - the operator, for example `Token.EQUALS`
        `a1` - the second value
        `comparer` - the comparer to be used to perform the comparison
        `checkTypes` - set to true if the operand types need to be checked for comparability at runtime
        `context` - the XPath evaluation context @return true if the comparison succeeds
      Throws:
        `XPathException`

    - #### getItemType

          public ItemType getItemType(TypeHierarchy th)

      Determine the data type of the expression
      Specified by:
        `getItemType` in class `Expression`
      Parameters:
        `th` - the type hierarchy cache
      Returns:
        the value BuiltInAtomicType.BOOLEAN

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

    - #### getExpressionCompiler

          public ExpressionCompiler getExpressionCompiler()

      Return the compiler of the GeneralComparison expression
      Overrides:
        `getExpressionCompiler` in class `Expression`
      Returns:
        the relevant ExpressionCompiler

    - #### getStreamingAdjunct

          public GeneralComparisonAdjunct getStreamingAdjunct()

      Get a class that supports streamed evaluation of this expression
      Overrides:
        `getStreamingAdjunct` in class `Expression`
      Returns:
        the relevant StreamingAdjunct, or null if none is available

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

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.