NodeSetValue
Date: 2016-07-03

com.icl.saxon.expr

## Class NodeSetValue

- java.lang.Object
- - com.icl.saxon.expr.Expression
  - - com.icl.saxon.expr.Value
    - - com.icl.saxon.expr.NodeSetValue

- Direct Known Subclasses:
    EmptyNodeSet, NodeSetExtent, NodeSetIntent, SingletonNodeSet

      public abstract class NodeSetValue
      extends Value

  A node-set value. We use this both for node-sets and node-lists. The node set will only be sorted into document order when requested (using sort() or evaluate()). This is an abstract class with a number of concrete implementations including NodeSetExtent (for extensional node-sets) and NodeSetIntent (for intensional node-sets).

- - ### Field Summary

    - ### Fields inherited from class com.icl.saxon.expr.Value

      `ANY, BOOLEAN, NODESET, NUMBER, OBJECT, STRING`

    - ### Fields inherited from class com.icl.saxon.expr.Expression

      `staticContext`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NodeSetValue()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract boolean` | `asBoolean()` Evaluate as a boolean.
    `double` | `asNumber()` Evaluate as a number.
    `abstract java.lang.String` | `asString()` Convert to string value
    `boolean` | `compare(int operator, Value other)` Test how a nodeset compares to another Value under a relational comparison
    `int` | `conversionPreference(java.lang.Class required)` Get conversion preference for this value to a Java class.
    `java.lang.Object` | `convertToJava(java.lang.Class target)` Convert to Java object (for passing to external functions)
    `void` | `display(int level)` Diagnostic print of expression structure
    `abstract NodeEnumeration` | `enumerate()` Return an enumeration of this nodeset value.
    `NodeEnumeration` | `enumerate(Context c, boolean sorted)` Return an enumeration of this nodeset value.
    `boolean` | `equals(Value other)` Test whether a nodeset "equals" another Value
    `Value` | `evaluate(Context context)` Evaluate the Node Set.
    `NodeSetValue` | `evaluateAsNodeSet(Context context)` Evaluate an expression as a NodeSet.
    `abstract int` | `getCount()` Count the nodes in the node-set.
    `int` | `getDataType()` Determine the data type of the expression
    `abstract NodeInfo` | `getFirst()` Get the first node in the nodeset (in document order)
    `abstract boolean` | `isSorted()` Test whether the value is known to be sorted
    `boolean` | `notEquals(Value other)` Test whether a nodeset "not-equals" another Value
    `abstract void` | `setSorted(boolean isSorted)` Set a flag to indicate whether the nodes are sorted.
    `abstract NodeSetValue` | `sort()` Sort the nodes into document order.

    - ### Methods inherited from class com.icl.saxon.expr.Value

      `getDependencies, inverse, numericCompare, reduce, simplify, stringToNumber`

    - ### Methods inherited from class com.icl.saxon.expr.Expression

      `containsReferences, evaluateAsBoolean, evaluateAsNumber, evaluateAsString, getStaticContext, indent, isContextDocumentNodeSet, make, outputStringValue, setStaticContext, usesCurrent`

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### NodeSetValue

          public NodeSetValue()

  - ### Method Detail

    - #### getDataType

          public int getDataType()

      Determine the data type of the expression
      Specified by:
        `getDataType` in class `Expression`
      Returns:
        Value.NODESET

    - #### evaluate

          public Value evaluate(Context context)
                         throws XPathException

      Evaluate the Node Set. This guarantees to return the result in sorted order.
      Overrides:
        `evaluate` in class `Value`
      Parameters:
        `context` - The context for evaluation (not used)
      Returns:
        the value, unchanged
      Throws:
        `XPathException`

    - #### evaluateAsNodeSet

          public NodeSetValue evaluateAsNodeSet(Context context)
                                         throws XPathException

      Evaluate an expression as a NodeSet.
      Overrides:
        `evaluateAsNodeSet` in class `Expression`
      Parameters:
        `context` - The context in which the expression is to be evaluated
      Returns:
        the value of the expression, evaluated in the current context
      Throws:
        `XPathException` - when the expression does not return a nodeset.

    - #### enumerate

          public abstract NodeEnumeration enumerate()
                                             throws XPathException

      Return an enumeration of this nodeset value. Unless sort() has been called the nodes can be in any order.
      Throws:
        `XPathException`

    - #### enumerate

          public NodeEnumeration enumerate(Context c,
                                  boolean sorted)
                                    throws XPathException

      Return an enumeration of this nodeset value. This is to satisfy the interface for Expression.
      Overrides:
        `enumerate` in class `Expression`
      Parameters:
        `context` - The context is ignored.
        `sorted` - Indicates that the result must be in document order
      Throws:
        `XPathException` - when the expression does not return a nodeset.

    - #### setSorted

          public abstract void setSorted(boolean isSorted)

      Set a flag to indicate whether the nodes are sorted. Used when the creator of the node-set knows that they are already in document order.
      Parameters:
        `isSorted` - true if the caller wishes to assert that the nodes are in document order and do not need to be further sorted

    - #### isSorted

          public abstract boolean isSorted()
                                    throws XPathException

      Test whether the value is known to be sorted
      Returns:
        true if the value is known to be sorted in document order, false if it is not known whether it is sorted.
      Throws:
        `XPathException`

    - #### asString

          public abstract java.lang.String asString()
                                             throws XPathException

      Convert to string value
      Specified by:
        `asString` in class `Value`
      Returns:
        the value of the first node in the node-set if there is one, otherwise an empty string
      Throws:
        `XPathException`

    - #### asNumber

          public double asNumber()
                          throws XPathException

      Evaluate as a number.
      Specified by:
        `asNumber` in class `Value`
      Returns:
        the number obtained by evaluating as a String and converting the string to a number
      Throws:
        `XPathException`

    - #### asBoolean

          public abstract boolean asBoolean()
                                     throws XPathException

      Evaluate as a boolean.
      Specified by:
        `asBoolean` in class `Value`
      Returns:
        true if the node set is not empty
      Throws:
        `XPathException`

    - #### getCount

          public abstract int getCount()
                                throws XPathException

      Count the nodes in the node-set. Note this will sort the node set if necessary, to make sure there are no duplicates.
      Throws:
        `XPathException`

    - #### sort

          public abstract NodeSetValue sort()
                                     throws XPathException

      Sort the nodes into document order. This does nothing if the nodes are already known to be sorted; to force a sort, call setSorted(false)
      Parameters:
        `controller` - The controller used to sort nodes into document order
      Returns:
        the same NodeSetValue, after sorting. (The reason for returning this is that it makes life easier for the XSL compiler).
      Throws:
        `XPathException`

    - #### getFirst

          public abstract NodeInfo getFirst()
                                     throws XPathException

      Get the first node in the nodeset (in document order)
      Returns:
        the first node
      Throws:
        `XPathException`

    - #### equals

          public boolean equals(Value other)
                         throws XPathException

      Test whether a nodeset "equals" another Value
      Overrides:
        `equals` in class `Value`
      Returns:
        a boolean giving the value of the expression, evaluated in the current context
      Throws:
        `XPathException`

    - #### notEquals

          public boolean notEquals(Value other)
                            throws XPathException

      Test whether a nodeset "not-equals" another Value
      Overrides:
        `notEquals` in class `Value`
      Returns:
        a boolean giving the value of the expression, evaluated in the current context
      Throws:
        `XPathException`

    - #### compare

          public boolean compare(int operator,
                        Value other)
                          throws XPathException

      Test how a nodeset compares to another Value under a relational comparison
      Overrides:
        `compare` in class `Value`
      Parameters:
        `operator` - The comparison operator, one of Tokenizer.LE, Tokenizer.LT, Tokenizer.GE, Tokenizer.GT,
      Throws:
        `XPathException`

    - #### display

          public void display(int level)

      Diagnostic print of expression structure
      Specified by:
        `display` in class `Expression`

    - #### conversionPreference

          public int conversionPreference(java.lang.Class required)

      Get conversion preference for this value to a Java class. A low result indicates higher preference.
      Specified by:
        `conversionPreference` in class `Value`

    - #### convertToJava

          public java.lang.Object convertToJava(java.lang.Class target)
                                         throws XPathException

      Convert to Java object (for passing to external functions)
      Specified by:
        `convertToJava` in class `Value`
      Parameters:
        `target` - The class required by the external function
      Returns:
        an object of the target class
      Throws:
        `XPathException`