net.sf.saxon.om

## Class SequenceTool

- java.lang.Object
- - net.sf.saxon.om.SequenceTool

-     public class SequenceTool
      extends Object

  Utility class for manipulating sequences. Some of these methods should be regarded as temporary scaffolding while the model is in transition.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `INDETERMINATE_ORDERING` Constant returned by compareTo() method to indicate an indeterminate ordering between two values

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SequenceTool()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Item` | `asItem(Sequence sequence)` Static method to make an Item from a Value
    `static Object` | `convertToJava(Item item)` Convert an XPath value to a Java object.
    `static int` | `getCardinality(Sequence sequence)`
    `static ItemType` | `getItemType(Sequence sequence, TypeHierarchy th)`
    `static int` | `getLength(Sequence sequence)` Get the length of a sequence (the number of items it contains)
    `static String` | `getStringValue(Sequence sequence)`
    `static Item` | `itemAt(Sequence sequence, int index)` Get the item at a given offset in a sequence.
    `static void` | `process(Sequence value, XPathContext context, int locationId)` Process the value as an instruction, without returning any tail calls
    `static GroundedValue` | `toGroundedValue(Sequence sequence)` Produce a GroundedValue containing the same values as a supplied sequence.
    `static GroundedValue` | `toGroundedValue(SequenceIterator iterator)` Produce a GroundedValue containing the same values as a supplied sequence.
    `static Sequence` | `toLazySequence(SequenceIterator iterator)` Construct a sequence capable of returning the same items as an iterator, without incurring the cost of evaluating the iterator and storing all the items.
    `static Sequence` | `toMemoSequence(SequenceIterator iterator)` Produce a Sequence containing the same values as a supplied sequence; the input is read progressively as required, and saved in a buffer as it is read in case it is needed again.

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

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

- - ### Field Detail

    - #### INDETERMINATE_ORDERING

          public static final int INDETERMINATE_ORDERING

      Constant returned by compareTo() method to indicate an indeterminate ordering between two values
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SequenceTool

          public SequenceTool()

  - ### Method Detail

    - #### toGroundedValue

          public static GroundedValue toGroundedValue(Sequence sequence)
                                               throws XPathException

      Produce a GroundedValue containing the same values as a supplied sequence.
      Parameters:
        `sequence` - the supplied sequence
      Returns:
        a GroundedValue containing the same items
      Throws:
        `XPathException`

    - #### toGroundedValue

          public static GroundedValue toGroundedValue(SequenceIterator iterator)
                                               throws XPathException

      Produce a GroundedValue containing the same values as a supplied sequence.
      Parameters:
        `iterator` - the supplied sequence. The iterator may or may not be consumed as a result of passing it to this method.
      Returns:
        a GroundedValue containing the same items
      Throws:
        `XPathException` - if a failure occurs reading the input iterator

    - #### toMemoSequence

          public static Sequence toMemoSequence(SequenceIterator iterator)
                                         throws XPathException

      Produce a Sequence containing the same values as a supplied sequence; the input is read progressively as required, and saved in a buffer as it is read in case it is needed again. But if the iterator is already backed by a grounded value, we return an iterator over that value.
      Parameters:
        `iterator` - the supplied sequence. The iterator may or may not be consumed as a result of passing it to this method.
      Returns:
        a GroundedValue containing the same items
      Throws:
        `XPathException` - if a failure occurs reading the input iterator

    - #### toLazySequence

          public static Sequence toLazySequence(SequenceIterator iterator)
                                         throws XPathException

      Construct a sequence capable of returning the same items as an iterator, without incurring the cost of evaluating the iterator and storing all the items.
      Parameters:
        `iterator` - the supplied sequence. The iterator may or may not be consumed as a result of passing it to this method.
      Returns:
        a Sequence containing the same items as the supplied iterator
      Throws:
        `XPathException` - if a failure occurs reading the input iterator

    - #### getLength

          public static int getLength(Sequence sequence)
                               throws XPathException

      Get the length of a sequence (the number of items it contains)
      Parameters:
        `sequence` - the sequence
      Returns:
        the length in items
      Throws:
        `XPathException`

    - #### itemAt

          public static Item itemAt(Sequence sequence,
                    int index)
                             throws XPathException

      Get the item at a given offset in a sequence. Uses zero-base indexing
      Parameters:
        `sequence` - the input sequence
        `index` - the 0-based subscript
      Returns:
        the n'th item if it exists, or null otherwise
      Throws:
        `XPathException`

    - #### asItem

          public static Item asItem(Sequence sequence)
                             throws XPathException

      Static method to make an Item from a Value
      Parameters:
        `sequence` - the value to be converted
      Returns:
        null if the value is an empty sequence; or the only item in the value if it is a singleton sequence
      Throws:
        `XPathException` - if the supplied Sequence contains multiple items

    - #### convertToJava

          public static Object convertToJava(Item item)
                                      throws XPathException

      Convert an XPath value to a Java object. An atomic value is returned as an instance of the best available Java class. If the item is a node, the node is "unwrapped", to return the underlying node in the original model (which might be, for example, a DOM or JDOM node).
      Parameters:
        `item` - the item to be converted
      Returns:
        the value after conversion
      Throws:
        `XPathException` - if an error occurs: for example, if the XPath value is an integer and is too big to fit in a Java long

    - #### getStringValue

          public static String getStringValue(Sequence sequence)
                                       throws XPathException

      Throws:
        `XPathException`

    - #### getItemType

          public static ItemType getItemType(Sequence sequence,
                             TypeHierarchy th)

    - #### getCardinality

          public static int getCardinality(Sequence sequence)

    - #### process

          public static void process(Sequence value,
                     XPathContext context,
                     int locationId)
                              throws XPathException

      Process the value as an instruction, without returning any tail calls
      Parameters:
        `context` - The dynamic context, giving access to the current node, the current variables, etc.
      Throws:
        `XPathException` - if an error occurs (for example if the value is a closure that needs to be evaluated)

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