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:
    java.lang.AutoCloseable, java.util.stream.BaseStream<T,​java.util.stream.Stream<T>>, java.util.stream.Stream<T>
    public class XdmStream<T extends XdmItem>
extends java.lang.Object
implements java.util.stream.Stream<T>
    XdmStream extends the capabilities of the standard JDK Stream class.

    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.

    Note: This class is implemented by wrapping a base stream. Generally, the methods on this class delegate to the base stream; those methods that return a stream wrap the stream returned by the base class. The context object can be used by a terminal method on the XdmStream to signal to the originator of the stream that no further input is required.

    • Nested Class Summary

      • Nested classes/interfaces inherited from interface java.util.stream.Stream

        java.util.stream.Stream.Builder<T extends java.lang.Object>

    • Constructor Summary

      Constructors 
      Constructor Description
      XdmStream​(java.util.Optional<T> input)
      Create an XdmStream consisting of zero or one items, supplied in the form of an Optional<XdmItem>
      XdmStream​(java.util.stream.Stream<T> base)
      Create an XdmStream from a general Stream that returns XDM items.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean allMatch​(java.util.function.Predicate<? super T> predicate)
      Returns true if every item in the stream matches a supplied predicate
      boolean anyMatch​(java.util.function.Predicate<? super T> predicate)
      Returns true if any item in the stream matches a supplied predicate
      XdmAtomicValue asAtomic()
      Return the result of the stream as an XdmAtomicValue.
      java.util.List<T> asList()
      Return the contents of the stream as a List<XdmItem>.
      java.util.List<XdmAtomicValue> asListOfAtomic()
      Return the result of the stream as a List<XdmAtomicValue>.
      java.util.List<XdmNode> asListOfNodes()
      Return the result of the stream as a List<XdmNode>.
      XdmNode asNode()
      Return the result of the stream as an XdmNode.
      java.util.Optional<XdmAtomicValue> asOptionalAtomic()
      Return the result of the stream as an Optional<XdmAtomicValue>.
      java.util.Optional<XdmNode> asOptionalNode()
      Return the result of the stream as an Optional<XdmNode>.
      java.util.Optional<java.lang.String> asOptionalString()
      Return the result of the stream as an Optional<String>.
      java.lang.String asString()
      Return the result of the stream as an String.
      XdmValue asXdmValue()
      Return the contents of the stream as an XdmValue.
      java.util.Optional<T> at​(int position)
      Return the item at a given position in the stream.
      void close()
      Close the stream
      <R> R collect​(java.util.function.Supplier<R> supplier, java.util.function.BiConsumer<R,​? super T> accumulator, java.util.function.BiConsumer<R,​R> combiner)  
      <R,​A>
      R      		 collect​(java.util.stream.Collector<? super T,​A,​R> collector)  
      long count()
      Returns the number of items in the stream
      XdmStream<T> distinct()
      Returns a stream consisting of the distinct items present in this stream.
      boolean exists()
      Return true if the stream is non-empty.
      XdmStream<T> filter​(java.util.function.Predicate<? super T> predicate)
      Filter a stream of items, to create a new stream containing only those items that satisfy a supplied condition.
      java.util.Optional<T> findAny()
      Returns an item in the stream, chosen arbitrarily, or Optional.empty() if the stream is empty
      java.util.Optional<T> findFirst()
      Returns the first item in the stream, or Optional.empty() if the stream is empty
      XdmStream<T> first()
      Return the first item of this stream, if there is one, discarding the remainder.
      T firstItem()
      Return the first item of this stream, if there is one, discarding the remainder; return null if the stream is empty.
      <R> java.util.stream.Stream<R> flatMap​(java.util.function.Function<? super T,​? extends java.util.stream.Stream<? extends R>> mapper)
      Returns a stream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element.
      java.util.stream.DoubleStream flatMapToDouble​(java.util.function.Function<? super T,​? extends java.util.stream.DoubleStream> mapper)
      Returns an DoubleStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element.
      java.util.stream.IntStream flatMapToInt​(java.util.function.Function<? super T,​? extends java.util.stream.IntStream> mapper)
      Returns an IntStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element.
      java.util.stream.LongStream flatMapToLong​(java.util.function.Function<? super T,​? extends java.util.stream.LongStream> mapper)
      Returns an LongStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element.
      <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.
      void forEach​(java.util.function.Consumer<? super T> action)
      Performs a given action once for each item of the stream, in non-deterministic order
      void forEachOrdered​(java.util.function.Consumer<? super T> action)
      Performs a given action once for each item of the stream, in the order in which the items appear
      boolean isParallel()
      Ask whether this stream will be evaluated in parallel
      java.util.Iterator<T> iterator()
      Get an iterator over the items in the stream
      XdmStream<T> last()
      Return the last item of this stream, if there is one, discarding the remainder.
      T lastItem()
      Return the last item of this stream, if there is one, discarding the remainder; return null if the stream is empty.
      XdmStream<T> limit​(long maxSize)
      Returns a stream containing the initial items of this stream, up to a maximum size
      <R> java.util.stream.Stream<R> map​(java.util.function.Function<? super T,​? extends R> mapper)
      Returns a stream consisting of the results of applying the given function to the elements of this stream.
      java.util.stream.DoubleStream mapToDouble​(java.util.function.ToDoubleFunction<? super T> mapper)
      Returns a DoubleStream consisting of the results of applying the given function to the elements of this stream.
      java.util.stream.IntStream mapToInt​(java.util.function.ToIntFunction<? super T> mapper)
      Returns an IntStream consisting of the results of applying the given function to the elements of this stream.
      java.util.stream.LongStream mapToLong​(java.util.function.ToLongFunction<? super T> mapper)
      Returns a LongStream consisting of the results of applying the given function to the elements of this stream.
      java.util.Optional<T> max​(java.util.Comparator<? super T> comparator)
      Returns the maximum item in the stream of items, comparing them using the supplied Comparator.
      java.util.Optional<T> min​(java.util.Comparator<? super T> comparator)
      Returns the minimum item in the stream of items, comparing them using the supplied Comparator.
      boolean noneMatch​(java.util.function.Predicate<? super T> predicate)
      Returns true if no item in the stream matches a supplied predicate
      java.util.stream.Stream<T> onClose​(java.lang.Runnable closeHandler)
      Returns an equivalent stream with a specified handler to be called when the stream is exhausted
      java.util.stream.Stream<T> parallel()
      Returns an equivalent stream that will (where possible and appropriate) be evaluated in parallel
      XdmStream<T> peek​(java.util.function.Consumer<? super T> action)
      Returns the supplied stream, while invoking a supplied action on each element of the stream as it is processed.
      java.util.Optional<T> reduce​(java.util.function.BinaryOperator<T> accumulator)
      Calls on the underlying stream
      T reduce​(T identity, java.util.function.BinaryOperator<T> accumulator)
      Performs a reduction or fold operation on the items in the stream.
      <U> U reduce​(U identity, java.util.function.BiFunction<U,​? super T,​U> accumulator, java.util.function.BinaryOperator<U> combiner)  
      java.util.stream.Stream<T> sequential()
      Returns an equivalent stream that will be evaluated sequentially
      XdmStream<T> skip​(long n)
      Returns a stream containing the items of this stream after skipping a specified number of items.
      XdmStream<T> sorted()
      Returns a stream consisting of the elements of this stream, in sorted order.
      XdmStream<T> sorted​(java.util.Comparator<? super T> comparator)
      Returns a stream consisting of the elements of this stream, in sorted order using a supplied Comparator.
      java.util.Spliterator<T> spliterator()
      Get a Spliterator over the items in the stream
      XdmStream<T> subStream​(int start, int end)
      Return the items at a given range of positions in the stream.
      java.lang.Object[] toArray()
      Returns an array containing the items in this stream
      <A> A[] toArray​(java.util.function.IntFunction<A[]> generator)
      Returns an array containing the items in this stream, using a supplied function to generate the array; this allows the type of the returned array to be controlled.
      java.util.stream.Stream<T> unordered()
      Returns an equivalent stream that offers no guarantee of retaining the order of items
      XdmStream<T> untilFirstExclusive​(java.util.function.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
      XdmStream<T> untilFirstInclusive​(java.util.function.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

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.util.stream.Stream

        dropWhile, takeWhile

    • Constructor Detail

      • XdmStream

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

      • XdmStream

        public XdmStream​(java.util.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​(java.util.function.Predicate<? super T> predicate)
        Filter a stream of items, to create a new stream containing only those items that satisfy a supplied condition.

        For example, body.select(child("*")).filter(n -> n.getNodeName().getLocalName().startsWith("h")) returns a stream of all the child elements of body whose local name starts with "h".

        Note: an alternative to filtering a stream is to use a Step that incorporates a Predicate, for example body.select(child("*").where(n -> n.getNodeName().getLocalName().startsWith("h")))

        Specified by:
        filter in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        predicate - the supplied condition. Any Predicate can be supplied, but some particularly useful predicates are available by calling static methods on the Predicates class, for example Predicates.empty(Steps.child("author")), which is true for a node that has no child elements with local name "author".
        Returns:
        the filtered stream

      • map

        public <R> java.util.stream.Stream<R> map​(java.util.function.Function<? super T,​? extends R> mapper)
        Returns a stream consisting of the results of applying the given function to the elements of this stream.

        This is an intermediate operation.

        For example, n.select(child(*)).map(c -> c.getNodeName().getLocalName()) returns a stream delivering the local names of the element children of n, as instances of java.lang.String. Note the result is a Stream, not an XdmStream.

        Specified by:
        map in interface java.util.stream.Stream<T extends XdmItem>
        Type Parameters:
        R - The element type of the new stream
        Parameters:
        mapper - a non-interfering, stateless function to apply to each element
        Returns:
        the new stream

      • mapToInt

        public java.util.stream.IntStream mapToInt​(java.util.function.ToIntFunction<? super T> mapper)
        Returns an IntStream consisting of the results of applying the given function to the elements of this stream.

        For example, n.select(child(*)).map(c -> c.getStringValue().length()) returns a stream delivering the lengths of the string-values of the element children of n. Note the result is a Stream, not an XdmStream.

        This is an intermediate operation.

        Specified by:
        mapToInt in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        mapper - a non-interfering, stateless function to apply to each element
        Returns:
        the new stream

      • mapToLong

        public java.util.stream.LongStream mapToLong​(java.util.function.ToLongFunction<? super T> mapper)
        Returns a LongStream consisting of the results of applying the given function to the elements of this stream.

        This is an intermediate operation.

        Specified by:
        mapToLong in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        mapper - a non-interfering, stateless function to apply to each element
        Returns:
        the new stream

      • mapToDouble

        public java.util.stream.DoubleStream mapToDouble​(java.util.function.ToDoubleFunction<? super T> mapper)
        Returns a DoubleStream consisting of the results of applying the given function to the elements of this stream.

        This is an intermediate operation.

        Specified by:
        mapToDouble in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        mapper - a non-interfering, stateless function to apply to each element
        Returns:
        the new stream

      • flatMap

        public <R> java.util.stream.Stream<R> flatMap​(java.util.function.Function<? super T,​? extends java.util.stream.Stream<? extends R>> mapper)
        Returns a stream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. Each mapped stream is closed after its contents have been placed into this stream. (If a mapped stream is null an empty stream is used, instead.)

        This is an intermediate operation.

        Note: The flatMap() operation has the effect of applying a one-to-many transformation to the elements of the stream, and then flattening the resulting elements into a new stream. This corresponds to the action of the "!" operator in XPath.

        Specified by:
        flatMap in interface java.util.stream.Stream<T extends XdmItem>
        Type Parameters:
        R - The element type of the new stream
        Parameters:
        mapper - a non-interfering, stateless function to apply to each element which produces a stream of new values
        Returns:
        the new 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.

        This method is similar to flatMap(java.util.function.Function<? super T, ? extends java.util.stream.Stream<? extends R>>), but differs in that it returns an XdmStream, making additional methods available.

        Note: XdmValue.select(net.sf.saxon.s9api.streams.Step<T>) is implemented using this method, and in practice it is usually clearer to use that method directly. For example node.select(child("*")).flatMapToXdm(child(*)) can be written as node.select(child("*").then(child("*")). Both expressions return a stream containing all the grandchildren elements of node. The same result can be achieved more concisely by writing node.select(path("*", "*"))

        Type Parameters:
        U - the type of items returned by the mapping function
        Parameters:
        mapper - the mapping function
        Returns:
        a new stream of items

      • flatMapToInt

        public java.util.stream.IntStream flatMapToInt​(java.util.function.Function<? super T,​? extends java.util.stream.IntStream> mapper)
        Returns an IntStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. Each mapped stream is closed after its contents have been placed into this stream. (If a mapped stream is null an empty stream is used, instead.)

        This is an intermediate operation.

        Specified by:
        flatMapToInt in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        mapper - a non-interfering, stateless function to apply to each element which produces a stream of new values
        Returns:
        the new stream
        See Also:
        flatMap(Function)

      • flatMapToLong

        public java.util.stream.LongStream flatMapToLong​(java.util.function.Function<? super T,​? extends java.util.stream.LongStream> mapper)
        Returns an LongStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. Each mapped stream is closed after its contents have been placed into this stream. (If a mapped stream is null an empty stream is used, instead.)

        This is an intermediate operation.

        Specified by:
        flatMapToLong in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        mapper - a non-interfering, stateless function to apply to each element which produces a stream of new values
        Returns:
        the new stream
        See Also:
        flatMap(Function)

      • flatMapToDouble

        public java.util.stream.DoubleStream flatMapToDouble​(java.util.function.Function<? super T,​? extends java.util.stream.DoubleStream> mapper)
        Returns an DoubleStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. Each mapped stream is closed after its contents have placed been into this stream. (If a mapped stream is null an empty stream is used, instead.)

        This is an intermediate operation.

        Specified by:
        flatMapToDouble in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        mapper - a non-interfering, stateless function to apply to each element which produces a stream of new values
        Returns:
        the new stream
        See Also:
        flatMap(Function)

      • distinct

        public XdmStream<T> distinct()
        Returns a stream consisting of the distinct items present in this stream. Items are compared using Object.equals(java.lang.Object). This means that two XdmNode objects are compared by node identity (so two separate nodes are distinct even if they have the same name and the same content).
        Specified by:
        distinct in interface java.util.stream.Stream<T extends XdmItem>
        Returns:
        the new stream, obtained by applying Stream.distinct() to the underlying stream

      • sorted

        public XdmStream<T> sorted()
        Returns a stream consisting of the elements of this stream, in sorted order.

        Note, this method is unlikely to be useful, because most XdmItem values do not implement Comparable.

        Specified by:
        sorted in interface java.util.stream.Stream<T extends XdmItem>
        Returns:
        the new stream, obtained by applying Stream.sorted() to the underlying stream

      • sorted

        public XdmStream<T> sorted​(java.util.Comparator<? super T> comparator)
        Returns a stream consisting of the elements of this stream, in sorted order using a supplied Comparator.
        Specified by:
        sorted in interface java.util.stream.Stream<T extends XdmItem>
        Returns:
        the new stream, obtained by applying Stream.sorted(Comparator) to the underlying stream

      • peek

        public XdmStream<T> peek​(java.util.function.Consumer<? super T> action)
        Returns the supplied stream, while invoking a supplied action on each element of the stream as it is processed.

        This method is designed primarily for debugging, to allow the contents of a stream to be monitored.

        Specified by:
        peek in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        action - the (non-interfering) action to be performed on each element of the stream
        Returns:
        the supplied stream, unchanged.

      • limit

        public XdmStream<T> limit​(long maxSize)
        Returns a stream containing the initial items of this stream, up to a maximum size
        Specified by:
        limit in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        maxSize - the maximum number of items to be included in the returned stream
        Returns:
        a stream containing the initial items of this stream, up to the specified limit

      • skip

        public XdmStream<T> skip​(long n)
        Returns a stream containing the items of this stream after skipping a specified number of items.
        Specified by:
        skip in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        n - the number of items at the start of the stream to be omitted from the result stream
        Returns:
        the result stream, comprising the input stream except for its first n items.

      • forEach

        public void forEach​(java.util.function.Consumer<? super T> action)
        Performs a given action once for each item of the stream, in non-deterministic order
        Specified by:
        forEach in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        action - the action to be performed on each item

      • forEachOrdered

        public void forEachOrdered​(java.util.function.Consumer<? super T> action)
        Performs a given action once for each item of the stream, in the order in which the items appear
        Specified by:
        forEachOrdered in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        action - the action to be performed on each item

      • toArray

        public java.lang.Object[] toArray()
        Returns an array containing the items in this stream
        Specified by:
        toArray in interface java.util.stream.Stream<T extends XdmItem>
        Returns:
        an array containing all the items in the stream

      • toArray

        public <A> A[] toArray​(java.util.function.IntFunction<A[]> generator)
        Returns an array containing the items in this stream, using a supplied function to generate the array; this allows the type of the returned array to be controlled.
        Specified by:
        toArray in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        generator - a function that takes an integer as argument and returns an array of the given length
        Returns:
        an array containing all the items in the stream; the type of the array is determined by the generator function

      • reduce

        public T reduce​(T identity,
                java.util.function.BinaryOperator<T> accumulator)
        Performs a reduction or fold operation on the items in the stream.

        For example, given a sequence of elements of the form <change year="2020" rise="1.03"/> the accumulated rise over a number of years may be computed as

        
    changes.stream().select(attribute("rise"))
      .map(a->a.getTypedValue().getDoubleValue())
      .reduce(1, (x, y) -> x*y)
        Specified by:
        reduce in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        identity - an initial value of an accumulator variable. This must be an identity value for the supplied accumulator function (so if F is the accumulator function, F(identity, V) returns V for any value of V).
        accumulator - the accumulator function: this takes the old value of the accumulator variable and the current item from the stream as arguments, and returns a new value for the accumulator variable. This function must be associative, that is, F(A, F(B, C)) must always give the same result as F(F(A, B), C))
        Returns:
        the final value of the accumulator variable after all items have been processed.

      • reduce

        public java.util.Optional<T> reduce​(java.util.function.BinaryOperator<T> accumulator)
        Calls on the underlying stream
        Specified by:
        reduce in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        accumulator - an associative, stateless, non-interfering value operating on two items in the stream
        Returns:
        the result of the delegated call

      • reduce

        public <U> U reduce​(U identity,
                    java.util.function.BiFunction<U,​? super T,​U> accumulator,
                    java.util.function.BinaryOperator<U> combiner)
        Specified by:
        reduce in interface java.util.stream.Stream<T extends XdmItem>

      • collect

        public <R> R collect​(java.util.function.Supplier<R> supplier,
                     java.util.function.BiConsumer<R,​? super T> accumulator,
                     java.util.function.BiConsumer<R,​R> combiner)
        Specified by:
        collect in interface java.util.stream.Stream<T extends XdmItem>

      • collect

        public <R,​A> R collect​(java.util.stream.Collector<? super T,​A,​R> collector)
        Specified by:
        collect in interface java.util.stream.Stream<T extends XdmItem>

      • min

        public java.util.Optional<T> min​(java.util.Comparator<? super T> comparator)
        Returns the minimum item in the stream of items, comparing them using the supplied Comparator.
        Specified by:
        min in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        comparator - the comparator to be used for comparing items
        Returns:
        the minimum value, or Optional.empty() if the stream is empty.

      • max

        public java.util.Optional<T> max​(java.util.Comparator<? super T> comparator)
        Returns the maximum item in the stream of items, comparing them using the supplied Comparator.
        Specified by:
        max in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        comparator - the comparator to be used for comparing items
        Returns:
        the maximum value, or Optional.empty() if the stream is empty.

      • count

        public long count()
        Returns the number of items in the stream
        Specified by:
        count in interface java.util.stream.Stream<T extends XdmItem>
        Returns:
        the length of the stream

      • anyMatch

        public boolean anyMatch​(java.util.function.Predicate<? super T> predicate)
        Returns true if any item in the stream matches a supplied predicate
        Specified by:
        anyMatch in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        predicate - the predicate to be applied to each item
        Returns:
        true if an item is found for which the predicate function returns true

      • allMatch

        public boolean allMatch​(java.util.function.Predicate<? super T> predicate)
        Returns true if every item in the stream matches a supplied predicate
        Specified by:
        allMatch in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        predicate - the predicate to be applied to each item
        Returns:
        true if the predicate function returns true for every item in the stream

      • noneMatch

        public boolean noneMatch​(java.util.function.Predicate<? super T> predicate)
        Returns true if no item in the stream matches a supplied predicate
        Specified by:
        noneMatch in interface java.util.stream.Stream<T extends XdmItem>
        Parameters:
        predicate - the predicate to be applied to each item
        Returns:
        true if the predicate function returns false for every item in the stream

      • findFirst

        public java.util.Optional<T> findFirst()
        Returns the first item in the stream, or Optional.empty() if the stream is empty
        Specified by:
        findFirst in interface java.util.stream.Stream<T extends XdmItem>
        Returns:
        the first item in the stream

      • findAny

        public java.util.Optional<T> findAny()
        Returns an item in the stream, chosen arbitrarily, or Optional.empty() if the stream is empty
        Specified by:
        findAny in interface java.util.stream.Stream<T extends XdmItem>
        Returns:
        an arbitrary item from the stream

      • iterator

        public java.util.Iterator<T> iterator()
        Get an iterator over the items in the stream
        Specified by:
        iterator in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>
        Returns:
        an iterator over all the items, in order

      • spliterator

        public java.util.Spliterator<T> spliterator()
        Get a Spliterator over the items in the stream
        Specified by:
        spliterator in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>
        Returns:
        a Spliterator over all the items, in order

      • isParallel

        public boolean isParallel()
        Ask whether this stream will be evaluated in parallel
        Specified by:
        isParallel in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>
        Returns:
        true if execution is in parallel

      • sequential

        public java.util.stream.Stream<T> sequential()
        Returns an equivalent stream that will be evaluated sequentially
        Specified by:
        sequential in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>
        Returns:
        an equivalent sequential stream

      • parallel

        public java.util.stream.Stream<T> parallel()
        Returns an equivalent stream that will (where possible and appropriate) be evaluated in parallel
        Specified by:
        parallel in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>
        Returns:
        an equivalent parallel stream

      • unordered

        public java.util.stream.Stream<T> unordered()
        Returns an equivalent stream that offers no guarantee of retaining the order of items
        Specified by:
        unordered in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>
        Returns:
        an equivalent stream without guaranteed order

      • onClose

        public java.util.stream.Stream<T> onClose​(java.lang.Runnable closeHandler)
        Returns an equivalent stream with a specified handler to be called when the stream is exhausted
        Specified by:
        onClose in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>
        Parameters:
        closeHandler - the code to be executed when the stream is closed
        Returns:
        a stream that returns the same items, augmented with a close handler

      • close

        public void close()
        Close the stream
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>

      • asXdmValue

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

      • asList

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

      • asListOfNodes

        public java.util.List<XdmNode> asListOfNodes()
        Return the result of the stream as a List<XdmNode>. This is a terminal operation.

        Node: the method makes it convenient to process the contents of a stream using a for-each loop, for example:

        
     for (XdmNode n : start.select(child().where(isText())).asList()) {
          process(n)
     }

        A more idiomatic style, however, is to use the forEach(java.util.function.Consumer<? super T>) method:

        start.select(child().where(isText())).forEach(n -> process(n))

        Returns:
        the list of nodes delivered by the stream
        Throws:
        java.lang.ClassCastException - if the stream contains an item that is not a node

      • asOptionalNode

        public java.util.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
        java.lang.ClassCastException - if the stream contains an item that is not a node

      • asNode

        public XdmNode asNode()
        Return the result of the stream as an XdmNode. This is a terminal operation.
        Returns:
        the single node delivered by the stream
        Throws:
        java.lang.ClassCastException - if the stream contains an item that is not a node
        XdmCollectors.MultipleItemException - if the stream contains more than one item
        java.util.NoSuchElementException - if the stream is empty

      • asListOfAtomic

        public java.util.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:
        java.lang.ClassCastException - if the stream contains an item that is not an atomic value

      • asOptionalAtomic

        public java.util.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
        java.lang.ClassCastException - if the stream contains an item that is not an atomic value

      • asAtomic

        public XdmAtomicValue asAtomic()
        Return the result of the stream as an XdmAtomicValue. This is a terminal operation.
        Returns:
        the string value of the single item delivered by the stream, or a zero-length string if the stream is empty
        Throws:
        java.lang.ClassCastException - if the stream contains an item that is not atomic
        XdmCollectors.MultipleItemException - if the stream contains more than one item
        java.util.NoSuchElementException - if the stream is empty

      • asOptionalString

        public java.util.Optional<java.lang.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
        java.lang.UnsupportedOperationException - if the stream contains an item that has no string value, for example a function item

      • asString

        public java.lang.String asString()
        Return the result of the stream as an String. This is a terminal operation.
        Returns:
        the string value of the single item delivered by the stream
        Throws:
        java.lang.UnsupportedOperationException - if the stream contains an item that has no string value, for example a function item
        XdmCollectors.MultipleItemException - if the stream contains more than one item
        java.util.NoSuchElementException - if the stream is empty

      • 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()
        Returns:
        a stream containing the first item in this stream

      • firstItem

        public T firstItem()
        Return the first item of this stream, if there is one, discarding the remainder; return null if the stream is empty. This is a short-circuiting operation similar to findFirst()
        Returns:
        the first item in this stream, or null if the stream is empty.

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

      • lastItem

        public T lastItem()
        Return the last item of this stream, if there is one, discarding the remainder; return null if the stream is empty. This is a short-circuiting operation similar to lastItem().
        Returns:
        the last item in the stream, or null if the input is empty.

      • at

        public java.util.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​(java.util.function.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​(java.util.function.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.