Package net.sf.saxon.om

## Class SequenceTool

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

-     public class SequenceTool
      extends java.lang.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 | Description
    --- | --- | ---
    `static int` | `INDETERMINATE_ORDERING` | Constant returned by compareTo() method to indicate an indeterminate ordering between two values

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SequenceTool()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static Item` | `asItem​(Sequence sequence)` | Static method to make an Item from a Value
    `static java.lang.Object` | `convertToJava​(Item item)` | Convert an XPath value to a Java object.
    `static Sequence[]` | `fromItems​(Item... items)` | Make an array of general-purpose Sequence objects with supplied contents
    `static int` | `getCardinality​(Sequence sequence)` | Get the cardinality of a sequence
    `static ItemType` | `getItemType​(Sequence sequence, TypeHierarchy th)` | Get the item type of the items in a sequence.
    `static int` | `getLength​(Sequence sequence)` | Get the length of a sequence (the number of items it contains)
    `static java.lang.String` | `getStringValue​(Sequence sequence)` | Get the string value of a sequence.
    `static UType` | `getUType​(Sequence sequence)` | Get the UType of the items in a sequence.
    `static boolean` | `hasLength​(SequenceIterator iter, int length)` | Ask whether the length of a sequence is exactly N
    `static boolean` | `isUnrepeatable​(Sequence seq)` |
    `static Item` | `itemAt​(Sequence sequence, int index)` | Get the item at a given offset in a sequence.
    `static Sequence[]` | `makeSequenceArray​(int length)` | Make an array of general-purpose Sequence objects of a given length
    `static void` | `process​(Sequence value, Outputter output, Location locationId)` | Process a supplied value by copying it to the current output destination
    `static boolean` | `sameLength​(SequenceIterator a, SequenceIterator b)` | Determine whether two sequences have the same number of items.
    `static <T extends Item> 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` | `toLazySequence2​(SequenceIterator iterator)` |
    `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 <T extends Item> 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 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 Sequence 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

    - #### toLazySequence2

          public static Sequence toLazySequence2​(SequenceIterator iterator)
                                          throws XPathException

      Throws:
        `XPathException`

    - #### isUnrepeatable

          public static boolean isUnrepeatable​(Sequence seq)

    - #### 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` - if an error occurs (due to lazy evaluation)

    - #### hasLength

          public static boolean hasLength​(SequenceIterator iter,
                                          int length)
                                   throws XPathException

      Ask whether the length of a sequence is exactly N
      Parameters:
        `iter` - an iterator over the sequence in question (which is typically consumed)
        `length` - the supposed length
      Returns:
        true if and only if the length of the sequence is the supposed length
      Throws:
        `XPathException`

    - #### sameLength

          public static boolean sameLength​(SequenceIterator a,
                                           SequenceIterator b)
                                    throws XPathException

      Determine whether two sequences have the same number of items. This is more efficient than comparing the counts, because the longer sequence is evaluated only as far as the length of the shorter sequence. The method consumes the supplied iterators.
      Parameters:
        `a` - iterator over the first sequence
        `b` - iterator over the second sequece
      Returns:
        true if the lengths of the two sequences are the same
      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` - for example if the value is a closure that needs to be evaluated, and evaluation fails

    - #### 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 java.lang.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 java.lang.String getStringValue​(Sequence sequence)
                                                 throws XPathException

      Get the string value of a sequence. For an item, this is same as the result of calling the XPath string() function. For a sequence of more than one item, it is the concatenation of the individual string values of the items in the sequence, space-separated.
      Parameters:
        `sequence` - the input sequence
      Returns:
        a string representation of the items in the supplied sequence
      Throws:
        `XPathException` - if the sequence contains an item with no string value, for example a function item

    - #### getItemType

          public static ItemType getItemType​(Sequence sequence,
                                             TypeHierarchy th)

      Get the item type of the items in a sequence. If the sequence is heterogeneous, the method returns the lowest common supertype. If the sequence is empty, it returns ErrorType (the type to which no instance can belong)
      Parameters:
        `sequence` - the input sequence
        `th` - the Type Hierarchy cache
      Returns:
        the lowest common supertype of the types of the items in the sequence

    - #### getUType

          public static UType getUType​(Sequence sequence)

      Get the UType of the items in a sequence. If the sequence is heterogeneous, the method returns the lowest common supertype. If the sequence is empty, it returns ErrorType (the type to which no instance can belong)
      Parameters:
        `sequence` - the input sequence
      Returns:
        the lowest common supertype of the types of the items in the sequence

    - #### getCardinality

          public static int getCardinality​(Sequence sequence)

      Get the cardinality of a sequence
      Parameters:
        `sequence` - the supplied sequence
      Returns:
        the cardinality, as one of the constants `StaticProperty.ALLOWS_ZERO` (for an empty sequence) `StaticProperty.EXACTLY_ONE` (for a singleton), or `StaticProperty.ALLOWS_ONE_OR_MORE` (for a sequence with more than one item)

    - #### process

          public static void process​(Sequence value,
                                     Outputter output,
                                     Location locationId)
                              throws XPathException

      Process a supplied value by copying it to the current output destination
      Parameters:
        `value` - the sequence to be processed
        `output` - the destination for the result
        `locationId` - (can be set to -1 if absent) information about the location of the value, which can be resolved by reference to the PipelineConfiguration of the current output destination
      Throws:
        `XPathException` - if an error occurs (for example if the value is a closure that needs to be evaluated)

    - #### makeSequenceArray

          public static Sequence[] makeSequenceArray​(int length)

      Make an array of general-purpose Sequence objects of a given length
      Parameters:
        `length` - the length of the returned array

    - #### fromItems

          public static Sequence[] fromItems​(Item... items)

      Make an array of general-purpose Sequence objects with supplied contents