Package net.sf.saxon.s9api.streams

Class XdmStream<T extends XdmItem>

  • Type Parameters:
    T - The type of items delivered by the stream.
    All Implemented Interfaces:
    AutoCloseable, BaseStream<T,​Stream<T>>, Stream<T>
    public class XdmStream<T extends XdmItem>
extends Object
implements Stream<T>
    XdmStream extends the capabilities of the standard JDK Stream.

    The extensions are:

    • Additional terminal operations are provided, allowing the results of the stream to be delivered for example as a List<XdmNode> or an Optional<XdmNode> more conveniently than using the general-purpose Collector interface.
    • Many of these terminal operations are short-circuiting, that is, they stop processing input when no further input is required.
    • The additional terminal operations throw a checked exception if a dynamic error occurs while generating the content of the stream.

    The implementation is customized to streams of XdmItems.

    • Constructor Detail

      • XdmStream

        public XdmStream​(Stream<T> base)
        Create an XdmStream from a general Stream that returns XDM items.
        Parameters:
        base - the stream of items

      • XdmStream

        public XdmStream​(Optional<T> input)
        Create an XdmStream consisting of zero or one items, supplied in the form of an Optional<XdmItem>
        Parameters:
        input - the optional item

    • Method Detail

      • filter

        public XdmStream<T> filter​(Predicate<? super T> predicate)
        Filter a stream of items, to create a new stream containing only those items that satisfy a supplied condition
        Specified by:
        filter in interface Stream<T extends XdmItem>
        Parameters:
        predicate - the supplied condition
        Returns:
        the filtered stream

      • flatMapToXdm

        public <U extends XdmItem> XdmStream<U> flatMapToXdm​(Step<U> mapper)
        Create a new XdmStream by applying a mapping function (specifically, a Step) to each item in the stream. The Step returns a sequence of items, which are inserted into the result sequence in place of the original item.
        Type Parameters:
        U - the type of items returned by the mapping function
        Parameters:
        mapper - the mapping function
        Returns:
        a new stream of items

      • asXdmValue

        public XdmValue asXdmValue()
        Return the result of the stream as an XdmValue. This is a terminal operation.
        Returns:
        the contents of the stream, as an XdmValue.

      • asList

        public List<T> asList()
        Return the result of the stream as a List<XdmItem>. This is a terminal operation.
        Returns:
        the contents of the stream, as a List<XdmItem>.

      • asListOfNodes

        public List<XdmNode> asListOfNodes()
        Return the result of the stream as a List<XdmNode>. This is a terminal operation.
        Returns:
        the list of nodes delivered by the stream
        Throws:
        ClassCastException - if the stream contains an item that is not a node

      • asOptionalNode

        public Optional<XdmNode> asOptionalNode()
        Return the result of the stream as an Optional<XdmNode>. This is a terminal operation.
        Returns:
        the single node delivered by the stream, or absent if the stream is empty
        Throws:
        XdmCollectors.MultipleItemException - if the stream contains more than one node
        ClassCastException - if the stream contains an item that is not a node

      • asListOfAtomic

        public List<XdmAtomicValue> asListOfAtomic()
        Return the result of the stream as a List<XdmAtomicValue>. This is a terminal operation.
        Returns:
        the list of atomic values delivered by the stream
        Throws:
        ClassCastException - if the stream contains an item that is not an atomic value

      • asOptionalAtomic

        public Optional<XdmAtomicValue> asOptionalAtomic()
        Return the result of the stream as an Optional<XdmAtomicValue>. This is a terminal operation.
        Returns:
        the string value of the single item delivered by the stream, or absent if the stream is empty
        Throws:
        XdmCollectors.MultipleItemException - if the stream contains more than one item
        ClassCastException - if the stream contains an item that is not an atomic value

      • asOptionalString

        public Optional<String> asOptionalString()
        Return the result of the stream as an Optional<String>. This is a terminal operation.
        Returns:
        the string value of the single item delivered by the stream, or absent if the stream is empty
        Throws:
        XdmCollectors.MultipleItemException - if the stream contains more than one item
        UnsupportedOperationException - if the stream contains an item that has no string value, for example a function item

      • first

        public XdmStream<T> first()
        Return the first item of this stream, if there is one, discarding the remainder. This is a short-circuiting operation similar to findFirst(), but it returns XdmStream<T> rather than Optional<T> so that further operations such as atomize() can be applied, and so that a typed result can be returned using a method such as asOptionalNode() or asOptionalString()

      • exists

        public boolean exists()
        Return true if the stream is non-empty. This is a short-circuiting terminal operation.
        Returns:
        true if at least one item is present in the stream.

      • last

        public XdmStream<T> last()
        Return the last item of this stream, if there is one, discarding the remainder. This is a short-circuiting operation similar to first(); it returns XdmStream<T> rather than Optional<T> so that further operations such atomize() can be applied, and so that a typed result can be returned using a method such as asOptionalNode() or asOptionalString()
        Returns:
        a stream containing only the last item in the stream, or an empty stream if the input is empty.

      • at

        public Optional<T> at​(int position)
        Return the item at a given position in the stream. This is a short-circuiting terminal operation.
        Parameters:
        position - the required position; items in the stream are numbered from zero.
        Returns:
        the item at the given position if there is one; otherwise, Optional.empty()

      • subStream

        public XdmStream<T> subStream​(int start,
                              int end)
        Return the items at a given range of positions in the stream. For example, subStream(0, 3) returns the first three items in the stream. This is a short-circuiting terminal operation.
        Parameters:
        start - the position of the first required item; items in the stream are numbered from zero.
        end - the position immediately after the last required item.
        Returns:
        a stream containing those items whose zero-based position is greater-than-or-equal-to start, and less-than end. No error occurs if either start or end is out of range, or if end is less than start.

      • untilFirstInclusive

        public XdmStream<T> untilFirstInclusive​(Predicate<? super XdmItem> predicate)
        Experimental method to return the content of a stream up to the first item that satisfies a given predicate, including that item
        Parameters:
        predicate - a condition that determines when the stream should stop
        Returns:
        a stream containing all items in the base stream up to and including the first item that satisfies a given predicate.

      • untilFirstExclusive

        public XdmStream<T> untilFirstExclusive​(Predicate<? super XdmItem> predicate)
        Experimental method to return the content of a stream up to the first item that satisfies a given predicate, excluding that item
        Parameters:
        predicate - a condition that determines when the stream should stop
        Returns:
        a stream containing all items in the base stream up to the item immediately before the first item that satisfies a given predicate.