net.sf.saxon.s9api.streams

Class XdmStream<T extends XdmItem>

java.lang.Object

net.sf.saxon.s9api.streams.XdmStream<T>

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>

Constructor Summary

Constructors

Constructor and 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

Modifier and Type	Method and 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,A> R	collect(java.util.stream.Collector<? super T,A,R> collector)
<R> R	collect(java.util.function.Supplier<R> supplier, java.util.function.BiConsumer<R,? super T> accumulator, java.util.function.BiConsumer<R,R> combiner)
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

builder, concat, empty, generate, iterate, of, of

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.