T
- The type of items delivered by the stream.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:
List<XdmNode>
or
an Optional<XdmNode>
more conveniently than using the general-purpose
Collector
interface.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.
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. |
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> |
flatMapToXdm(Step<U> mapper)
|
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
|
public XdmStream(java.util.stream.Stream<T> base)
XdmStream
from a general Stream
that returns XDM items.base
- the stream of itemspublic XdmStream<T> filter(java.util.function.Predicate<? super T> predicate)
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")))
filter
in interface java.util.stream.Stream<T extends XdmItem>
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".public <R> java.util.stream.Stream<R> map(java.util.function.Function<? super T,? extends R> mapper)
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
.
map
in interface java.util.stream.Stream<T extends XdmItem>
R
- The element type of the new streammapper
- a non-interfering,
stateless
function to apply to each elementpublic java.util.stream.IntStream mapToInt(java.util.function.ToIntFunction<? super T> mapper)
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.
mapToInt
in interface java.util.stream.Stream<T extends XdmItem>
mapper
- a non-interfering,
stateless
function to apply to each elementpublic java.util.stream.LongStream mapToLong(java.util.function.ToLongFunction<? super T> mapper)
LongStream
consisting of the results of applying the
given function to the elements of this stream.
This is an intermediate operation.
mapToLong
in interface java.util.stream.Stream<T extends XdmItem>
mapper
- a non-interfering,
stateless
function to apply to each elementpublic java.util.stream.DoubleStream mapToDouble(java.util.function.ToDoubleFunction<? super T> mapper)
DoubleStream
consisting of the results of applying the
given function to the elements of this stream.
This is an intermediate operation.
mapToDouble
in interface java.util.stream.Stream<T extends XdmItem>
mapper
- a non-interfering,
stateless
function to apply to each elementpublic <R> java.util.stream.Stream<R> flatMap(java.util.function.Function<? super T,? extends java.util.stream.Stream<? extends R>> mapper)
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.
flatMap
in interface java.util.stream.Stream<T extends XdmItem>
R
- The element type of the new streammapper
- a non-interfering,
stateless
function to apply to each element which produces a stream
of new valuespublic <U extends XdmItem> XdmStream<U> flatMapToXdm(Step<U> mapper)
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("*", "*"))
U
- the type of items returned by the mapping functionmapper
- the mapping functionpublic java.util.stream.IntStream flatMapToInt(java.util.function.Function<? super T,? extends java.util.stream.IntStream> mapper)
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.
flatMapToInt
in interface java.util.stream.Stream<T extends XdmItem>
mapper
- a non-interfering,
stateless
function to apply to each element which produces a stream
of new valuesflatMap(Function)
public java.util.stream.LongStream flatMapToLong(java.util.function.Function<? super T,? extends java.util.stream.LongStream> mapper)
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.
flatMapToLong
in interface java.util.stream.Stream<T extends XdmItem>
mapper
- a non-interfering,
stateless
function to apply to each element which produces a stream
of new valuesflatMap(Function)
public java.util.stream.DoubleStream flatMapToDouble(java.util.function.Function<? super T,? extends java.util.stream.DoubleStream> mapper)
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.
flatMapToDouble
in interface java.util.stream.Stream<T extends XdmItem>
mapper
- a non-interfering,
stateless
function to apply to each element which produces a stream
of new valuesflatMap(Function)
public XdmStream<T> distinct()
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).public XdmStream<T> sorted()
Note, this method is unlikely to be useful, because most XdmItem
values do
not implement Comparable
.
public XdmStream<T> sorted(java.util.Comparator<? super T> comparator)
Comparator
.public XdmStream<T> peek(java.util.function.Consumer<? super T> action)
This method is designed primarily for debugging, to allow the contents of a stream to be monitored.
public XdmStream<T> limit(long maxSize)
public XdmStream<T> skip(long n)
public void forEach(java.util.function.Consumer<? super T> action)
public void forEachOrdered(java.util.function.Consumer<? super T> action)
public java.lang.Object[] toArray()
public <A> A[] toArray(java.util.function.IntFunction<A[]> generator)
toArray
in interface java.util.stream.Stream<T extends XdmItem>
generator
- a function that takes an integer as argument and returns an array
of the given lengthpublic T reduce(T identity, java.util.function.BinaryOperator<T> accumulator)
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)
reduce
in interface java.util.stream.Stream<T extends XdmItem>
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))
public java.util.Optional<T> reduce(java.util.function.BinaryOperator<T> accumulator)
on the underlying stream
public <U> U reduce(U identity, java.util.function.BiFunction<U,? super T,U> accumulator, java.util.function.BinaryOperator<U> combiner)
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)
public <R,A> R collect(java.util.stream.Collector<? super T,A,R> collector)
public java.util.Optional<T> min(java.util.Comparator<? super T> comparator)
Comparator
.public java.util.Optional<T> max(java.util.Comparator<? super T> comparator)
Comparator
.public long count()
public boolean anyMatch(java.util.function.Predicate<? super T> predicate)
public boolean allMatch(java.util.function.Predicate<? super T> predicate)
public boolean noneMatch(java.util.function.Predicate<? super T> predicate)
public java.util.Optional<T> findFirst()
Optional.empty()
if the stream is emptypublic java.util.Optional<T> findAny()
Optional.empty()
if the stream is emptypublic java.util.Iterator<T> iterator()
public java.util.Spliterator<T> spliterator()
public boolean isParallel()
public java.util.stream.Stream<T> sequential()
public java.util.stream.Stream<T> parallel()
public java.util.stream.Stream<T> unordered()
public java.util.stream.Stream<T> onClose(java.lang.Runnable closeHandler)
public void close()
public XdmValue asXdmValue()
public java.util.List<T> asList()
List<XdmItem>
. This is a terminal operation.List<XdmItem>
.public java.util.List<XdmNode> asListOfNodes()
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))
java.lang.ClassCastException
- if the stream contains an item that is not a nodepublic java.util.Optional<XdmNode> asOptionalNode()
Optional<XdmNode>
. This is a terminal operation.XdmCollectors.MultipleItemException
- if the stream contains more than one nodejava.lang.ClassCastException
- if the stream contains an item that is not a nodepublic XdmNode asNode()
XdmNode
. This is a terminal operation.java.lang.ClassCastException
- if the stream contains an item that is not a nodeXdmCollectors.MultipleItemException
- if the stream contains
more than one itemjava.util.NoSuchElementException
- if the stream is emptypublic java.util.List<XdmAtomicValue> asListOfAtomic()
List<XdmAtomicValue>
. This is a terminal operation.java.lang.ClassCastException
- if the stream contains an item that is not an atomic valuepublic java.util.Optional<XdmAtomicValue> asOptionalAtomic()
Optional<XdmAtomicValue>
. This is a terminal operation.XdmCollectors.MultipleItemException
- if the stream contains more than one itemjava.lang.ClassCastException
- if the stream contains an item that is not an atomic valuepublic XdmAtomicValue asAtomic()
XdmAtomicValue
. This is a terminal operation.java.lang.ClassCastException
- if the stream contains an item that is not atomicXdmCollectors.MultipleItemException
- if the stream contains more than one itemjava.util.NoSuchElementException
- if the stream is emptypublic java.util.Optional<java.lang.String> asOptionalString()
Optional<String>
. This is a terminal operation.XdmCollectors.MultipleItemException
- if the stream contains more than one itemjava.lang.UnsupportedOperationException
- if the stream contains an item that has no string value,
for example a function itempublic java.lang.String asString()
String
. This is a terminal operation.java.lang.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 itemjava.util.NoSuchElementException
- if the stream is emptypublic XdmStream<T> first()
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()
public T firstItem()
findFirst()
public boolean exists()
public XdmStream<T> last()
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()
public T lastItem()
lastItem()
.public java.util.Optional<T> at(int position)
position
- the required position; items in the stream are numbered from zero.Optional.empty()
public XdmStream<T> subStream(int start, int end)
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.public XdmStream<T> untilFirstInclusive(java.util.function.Predicate<? super XdmItem> predicate)
predicate
- a condition that determines when the stream should stoppublic XdmStream<T> untilFirstExclusive(java.util.function.Predicate<? super XdmItem> predicate)
predicate
- a condition that determines when the stream should stopCopyright (c) 2004-2022 Saxonica Limited. All rights reserved.