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 GroundedValue toGroundedValue​(SequenceIterator iterator)
        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:
        UncheckedXPathException - 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

      • supportsGetLength

        public static boolean supportsGetLength​(SequenceIterator iterator)
        Ask whether a SequenceIterator supports the capability to call getLength() to establish the number of items in the sequence.
        Parameters:
        iterator - the iterator we are asking about
        Returns:
        true if the iterator is a LastPositionFinder with this capability. Note that some iterators implement this interface, but do not actually have the capability to determine the length, because they delegate to another iterator.

      • getLength

        public static int getLength​(SequenceIterator iterator)
        Get the number of items in the sequence identified by a SequenceIterator. This method can only be used if supportsGetLength(SequenceIterator) has been called and returns true. The length is returned regardless of the current position of the iterator. The state of the iterator is not changed
        Parameters:
        iterator - the iterator we are asking about
        Returns:
        the number of items in the sequence
        Throws:
        java.lang.UnsupportedOperationException - if the iterator does not have this capability

      • supply

        public static void supply​(SequenceIterator iter,
                          ItemConsumer<? super Item> consumer)
        Supply the (remaining) items in a sequence to a consumer of items
        Parameters:
        iter - a sequence iterator, which will be consumed by calling this method
        consumer - the consumer which will be called to process the remaining items in the sequence, in turn
        Throws:
        UncheckedXPathException - if the computation of the input sequence reports an XPathException, or if the consumer throws an 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

        Note: this is more efficient than counting the items and testing whether the result is N, because the sequence only needs to be read as far as the Nth item.

        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 - if an error is detected

      • sameLength

        public static boolean sameLength​(SequenceIterator a,
                                 SequenceIterator b)
        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 sequence
        Returns:
        true if the lengths of the two sequences are the same

      • itemAt

        public static Item itemAt​(Sequence sequence,
                          int index)
        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:
        UncheckedXPathException - 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

      • focusTracker

        public static FocusIterator focusTracker​(SequenceIterator basis)
        Factory method to create a FocusIterator wrapping a supplied SequenceIterator
        Parameters:
        basis - the SequenceIterator to be wrapped. This must be positioned at the start.
        Returns:
        a FocusIterator that returns the same items as the supplied iterator, while tracking position() and current().

      • 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 UnicodeString 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

      • stringify

        public static java.lang.String stringify​(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
        Returns:
        the new array

      • fromItems

        public static Sequence[] fromItems​(Item... items)
        Make an array of general-purpose Sequence objects with supplied contents
        Parameters:
        items - the contents for the array
        Returns:
        the new array

      • attributeMapFromList

        public static AttributeMap attributeMapFromList​(java.util.List<AttributeInfo> list)
        Construct an AttributeMap given a list of AttributeInfo objects representing the individual attributes.
        Parameters:
        list - the list of attributes. It is the caller's responsibility to ensure that this list contains no duplicates. The method may detect this, but is not guaranteed to do so. Calling AttributeMap.verify() after constructing the attribute map verifies that there are no duplicates. The order of items in the input list is not necessarily preserved.
        Returns:
        an AttributeMap containing the specified attributes.
        Throws:
        java.lang.IllegalArgumentException - if duplicate attributes are detected

      • itemOrEmpty

        public static GroundedValue itemOrEmpty​(Item item)
        Helper method to convert an Item or null to a Sequence
        Parameters:
        item - the item to convert
        Returns:
        the converted sequence