Package net.sf.saxon.om

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

      • 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

      • 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