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>
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 anOptional<XdmNode>
more conveniently than using the general-purposeCollector
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 XdmItem
s.
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
Stream.Builder<T>
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
Returns true if every item in the stream matches a supplied predicateboolean
Returns true if any item in the stream matches a supplied predicateasAtomic()
Return the result of the stream as anXdmAtomicValue
.asList()
Return the contents of the stream as aList<XdmItem>
.Return the result of the stream as aList<XdmAtomicValue>
.Return the result of the stream as aList<XdmNode>
.asNode()
Return the result of the stream as anXdmNode
.Return the result of the stream as anOptional<XdmAtomicValue>
.Return the result of the stream as anOptional<XdmNode>
.Return the result of the stream as anOptional<String>
.asString()
Return the result of the stream as anString
.Return the contents of the stream as an XdmValue.at
(int position) Return the item at a given position in the stream.void
close()
Close the stream<R> R
collect
(Supplier<R> supplier, BiConsumer<R, ? super T> accumulator, BiConsumer<R, R> combiner) <R,
A> R long
count()
Returns the number of items in the streamdistinct()
Returns a stream consisting of the distinct items present in this stream.boolean
exists()
Return true if the stream is non-empty.Filter a stream of items, to create a new stream containing only those items that satisfy a supplied condition.findAny()
Returns an item in the stream, chosen arbitrarily, orOptional.empty()
if the stream is emptyReturns the first item in the stream, orOptional.empty()
if the stream is emptyfirst()
Return the first item of this stream, if there is one, discarding the remainder.Return the first item of this stream, if there is one, discarding the remainder; return null if the stream is empty.<R> Stream
<R> 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.flatMapToDouble
(Function<? super T, ? extends DoubleStream> mapper) Returns anDoubleStream
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.flatMapToInt
(Function<? super T, ? extends IntStream> mapper) Returns anIntStream
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.flatMapToLong
(Function<? super T, ? extends LongStream> mapper) Returns anLongStream
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.flatMapToXdm
(Step<U> mapper) void
Performs a given action once for each item of the stream, in non-deterministic ordervoid
forEachOrdered
(Consumer<? super T> action) Performs a given action once for each item of the stream, in the order in which the items appearboolean
Ask whether this stream will be evaluated in paralleliterator()
Get an iterator over the items in the streamlast()
Return the last item of this stream, if there is one, discarding the remainder.lastItem()
Return the last item of this stream, if there is one, discarding the remainder; return null if the stream is empty.limit
(long maxSize) Returns a stream containing the initial items of this stream, up to a maximum size<R> Stream
<R> Returns a stream consisting of the results of applying the given function to the elements of this stream.mapToDouble
(ToDoubleFunction<? super T> mapper) Returns aDoubleStream
consisting of the results of applying the given function to the elements of this stream.mapToInt
(ToIntFunction<? super T> mapper) Returns anIntStream
consisting of the results of applying the given function to the elements of this stream.mapToLong
(ToLongFunction<? super T> mapper) Returns aLongStream
consisting of the results of applying the given function to the elements of this stream.max
(Comparator<? super T> comparator) Returns the maximum item in the stream of items, comparing them using the suppliedComparator
.min
(Comparator<? super T> comparator) Returns the minimum item in the stream of items, comparing them using the suppliedComparator
.boolean
Returns true if no item in the stream matches a supplied predicateReturns an equivalent stream with a specified handler to be called when the stream is exhaustedparallel()
Returns an equivalent stream that will (where possible and appropriate) be evaluated in parallelReturns the supplied stream, while invoking a supplied action on each element of the stream as it is processed.reduce
(BinaryOperator<T> accumulator) Callson the underlying stream
reduce
(T identity, BinaryOperator<T> accumulator) Performs a reduction or fold operation on the items in the stream.<U> U
reduce
(U identity, BiFunction<U, ? super T, U> accumulator, BinaryOperator<U> combiner) Returns an equivalent stream that will be evaluated sequentiallyskip
(long n) Returns a stream containing the items of this stream after skipping a specified number of items.sorted()
Returns a stream consisting of the elements of this stream, in sorted order.sorted
(Comparator<? super T> comparator) Returns a stream consisting of the elements of this stream, in sorted order using a suppliedComparator
.Get a Spliterator over the items in the streamsubStream
(int start, int end) Return the items at a given range of positions in the stream.Object[]
toArray()
Returns an array containing the items in this stream<A> A[]
toArray
(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.Returns an equivalent stream that offers no guarantee of retaining the order of itemsuntilFirstExclusive
(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 itemuntilFirstInclusive
(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 itemMethods 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, mapMulti, mapMultiToDouble, mapMultiToInt, mapMultiToLong, takeWhile, toList
-
Constructor Details
-
XdmStream
- Parameters:
base
- the stream of items
-
XdmStream
Create anXdmStream
consisting of zero or one items, supplied in the form of anOptional<XdmItem>
- Parameters:
input
- the optional item
-
-
Method Details
-
filter
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 ofbody
whose local name starts with "h".Note: an alternative to filtering a stream is to use a
Step
that incorporates aPredicate
, for examplebody.select(child("*").where(n -> n.getNodeName().getLocalName().startsWith("h")))
- Specified by:
filter
in interfaceStream<T extends XdmItem>
- Parameters:
predicate
- the supplied condition. AnyPredicate
can be supplied, but some particularly useful predicates are available by calling static methods on thePredicates
class, for examplePredicates.empty(Steps.child("author"))
, which is true for a node that has no child elements with local name "author".- Returns:
- the filtered stream
-
map
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 ofn
, as instances ofjava.lang.String
. Note the result is aStream
, not anXdmStream
. -
mapToInt
Returns anIntStream
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 ofn
. Note the result is aStream
, not anXdmStream
.This is an intermediate operation.
-
mapToLong
Returns aLongStream
consisting of the results of applying the given function to the elements of this stream.This is an intermediate operation.
-
mapToDouble
Returns aDoubleStream
consisting of the results of applying the given function to the elements of this stream.This is an intermediate operation.
- Specified by:
mapToDouble
in interfaceStream<T extends XdmItem>
- Parameters:
mapper
- a non-interfering, stateless function to apply to each element- Returns:
- the new stream
-
flatMap
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 isclosed
after its contents have been placed into this stream. (If a mapped stream isnull
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. -
flatMapToXdm
Create a newXdmStream
by applying a mapping function (specifically, aStep
) to each item in the stream. TheStep
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 anXdmStream
, 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 examplenode.select(child("*")).flatMapToXdm(child(*))
can be written asnode.select(child("*").then(child("*"))
. Both expressions return a stream containing all the grandchildren elements ofnode
. The same result can be achieved more concisely by writingnode.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
Returns anIntStream
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 isclosed
after its contents have been placed into this stream. (If a mapped stream isnull
an empty stream is used, instead.)This is an intermediate operation.
- Specified by:
flatMapToInt
in interfaceStream<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:
-
flatMapToLong
Returns anLongStream
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 isclosed
after its contents have been placed into this stream. (If a mapped stream isnull
an empty stream is used, instead.)This is an intermediate operation.
- Specified by:
flatMapToLong
in interfaceStream<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:
-
flatMapToDouble
Returns anDoubleStream
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 isclosed
after its contents have placed been into this stream. (If a mapped stream isnull
an empty stream is used, instead.)This is an intermediate operation.
- Specified by:
flatMapToDouble
in interfaceStream<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:
-
distinct
Returns a stream consisting of the distinct items present in this stream. Items are compared usingObject.equals(java.lang.Object)
. This means that twoXdmNode
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 interfaceStream<T extends XdmItem>
- Returns:
- the new stream, obtained by applying
Stream.distinct()
to the underlying stream
-
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 implementComparable
.- Specified by:
sorted
in interfaceStream<T extends XdmItem>
- Returns:
- the new stream, obtained by applying
Stream.sorted()
to the underlying stream
-
sorted
Returns a stream consisting of the elements of this stream, in sorted order using a suppliedComparator
.- Specified by:
sorted
in interfaceStream<T extends XdmItem>
- Returns:
- the new stream, obtained by applying
Stream.sorted(Comparator)
to the underlying stream
-
peek
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.
-
limit
Returns a stream containing the initial items of this stream, up to a maximum size -
skip
Returns a stream containing the items of this stream after skipping a specified number of items. -
forEach
Performs a given action once for each item of the stream, in non-deterministic order -
forEachOrdered
Performs a given action once for each item of the stream, in the order in which the items appear- Specified by:
forEachOrdered
in interfaceStream<T extends XdmItem>
- Parameters:
action
- the action to be performed on each item
-
toArray
Returns an array containing the items in this stream -
toArray
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. -
reduce
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 aschanges.stream().select(attribute("rise")) .map(a->a.getTypedValue().getDoubleValue()) .reduce(1, (x, y) -> x*y)
- Specified by:
reduce
in interfaceStream<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)
returnsV
for any value ofV
).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 asF(F(A, B), C))
- Returns:
- the final value of the accumulator variable after all items have been processed.
-
reduce
Callson the underlying stream
-
reduce
-
collect
public <R> R collect(Supplier<R> supplier, BiConsumer<R, ? super T> accumulator, BiConsumer<R, R> combiner) -
collect
-
min
Returns the minimum item in the stream of items, comparing them using the suppliedComparator
.- Specified by:
min
in interfaceStream<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
Returns the maximum item in the stream of items, comparing them using the suppliedComparator
.- Specified by:
max
in interfaceStream<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 -
anyMatch
Returns true if any item in the stream matches a supplied predicate -
allMatch
Returns true if every item in the stream matches a supplied predicate -
noneMatch
Returns true if no item in the stream matches a supplied predicate -
findFirst
Returns the first item in the stream, orOptional.empty()
if the stream is empty -
findAny
Returns an item in the stream, chosen arbitrarily, orOptional.empty()
if the stream is empty -
iterator
Get an iterator over the items in the stream -
spliterator
Get a Spliterator over the items in the stream- Specified by:
spliterator
in interfaceBaseStream<T extends XdmItem,
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 interfaceBaseStream<T extends XdmItem,
Stream<T extends XdmItem>> - Returns:
- true if execution is in parallel
-
sequential
Returns an equivalent stream that will be evaluated sequentially- Specified by:
sequential
in interfaceBaseStream<T extends XdmItem,
Stream<T extends XdmItem>> - Returns:
- an equivalent sequential stream
-
parallel
Returns an equivalent stream that will (where possible and appropriate) be evaluated in parallel -
unordered
Returns an equivalent stream that offers no guarantee of retaining the order of items -
onClose
Returns an equivalent stream with a specified handler to be called when the stream is exhausted -
close
public void close()Close the stream- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceBaseStream<T extends XdmItem,
Stream<T extends XdmItem>>
-
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
Return the contents of the stream as aList<XdmItem>
. This is a terminal operation.- Returns:
- the contents of the stream, as a
List<XdmItem>
.
-
asListOfNodes
Return the result of the stream as aList<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:
ClassCastException
- if the stream contains an item that is not a node
-
asOptionalNode
Return the result of the stream as anOptional<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 nodeClassCastException
- if the stream contains an item that is not a node
-
asNode
Return the result of the stream as anXdmNode
. This is a terminal operation.- Returns:
- the single node delivered by the stream
- Throws:
ClassCastException
- if the stream contains an item that is not a nodeXdmCollectors.MultipleItemException
- if the stream contains more than one itemNoSuchElementException
- if the stream is empty
-
asListOfAtomic
Return the result of the stream as aList<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
Return the result of the stream as anOptional<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 itemClassCastException
- if the stream contains an item that is not an atomic value
-
asAtomic
Return the result of the stream as anXdmAtomicValue
. 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:
ClassCastException
- if the stream contains an item that is not atomicXdmCollectors.MultipleItemException
- if the stream contains more than one itemNoSuchElementException
- if the stream is empty
-
asOptionalString
Return the result of the stream as anOptional<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 itemUnsupportedOperationException
- if the stream contains an item that has no string value, for example a function item
-
asString
Return the result of the stream as anString
. This is a terminal operation.- Returns:
- the string value of the single item delivered by the stream
- Throws:
UnsupportedOperationException
- if the stream contains an item that has no string value, for example a function itemXdmCollectors.MultipleItemException
- if the stream contains more than one itemNoSuchElementException
- if the stream is empty
-
first
Return the first item of this stream, if there is one, discarding the remainder. This is a short-circuiting operation similar tofindFirst()
, but it returnsXdmStream<T>
rather thanOptional<T>
so that further operations such asatomize()
can be applied, and so that a typed result can be returned using a method such asasOptionalNode()
orasOptionalString()
- Returns:
- a stream containing the first item in this stream
-
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 tofindFirst()
- 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
Return the last item of this stream, if there is one, discarding the remainder. This is a short-circuiting operation similar tofirst()
; it returnsXdmStream<T>
rather thanOptional<T>
so that further operations suchatomize()
can be applied, and so that a typed result can be returned using a method such asasOptionalNode()
orasOptionalString()
- Returns:
- a stream containing only the last item in the stream, or an empty stream if the input is empty.
-
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 tolastItem()
.- Returns:
- the last item in the stream, or null if the input is empty.
-
at
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
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
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
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.
-