Package 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`.

  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 `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

      `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)` |
    `boolean` | `anyMatch​(java.util.function.Predicate<? super T> predicate)` |
    `XdmAtomicValue` | `asAtomic()` | Return the result of the stream as an `XdmAtomicValue`.
    `java.util.List<T>` | `asList()` | Return the result 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 result 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()` |
    `<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()` |
    `XdmStream<T>` | `distinct()` |
    `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()` |
    `java.util.Optional<T>` | `findFirst()` |
    `XdmStream<T>` | `first()` | Return the first item of this stream, if there is one, discarding the remainder.
    `<R> java.util.stream.Stream<R>` | `flatMap​(java.util.function.Function<? super T,​? extends java.util.stream.Stream<? extends R>> mapper)` |
    `java.util.stream.DoubleStream` | `flatMapToDouble​(java.util.function.Function<? super T,​? extends java.util.stream.DoubleStream> mapper)` |
    `java.util.stream.IntStream` | `flatMapToInt​(java.util.function.Function<? super T,​? extends java.util.stream.IntStream> mapper)` |
    `java.util.stream.LongStream` | `flatMapToLong​(java.util.function.Function<? super T,​? extends java.util.stream.LongStream> mapper)` |
    `<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)` |
    `void` | `forEachOrdered​(java.util.function.Consumer<? super T> action)` |
    `boolean` | `isParallel()` |
    `java.util.Iterator<T>` | `iterator()` |
    `XdmStream<T>` | `last()` | Return the last item of this stream, if there is one, discarding the remainder.
    `XdmStream<T>` | `limit​(long maxSize)` |
    `<R> java.util.stream.Stream<R>` | `map​(java.util.function.Function<? super T,​? extends R> mapper)` |
    `java.util.stream.DoubleStream` | `mapToDouble​(java.util.function.ToDoubleFunction<? super T> mapper)` |
    `java.util.stream.IntStream` | `mapToInt​(java.util.function.ToIntFunction<? super T> mapper)` |
    `java.util.stream.LongStream` | `mapToLong​(java.util.function.ToLongFunction<? super T> mapper)` |
    `java.util.Optional<T>` | `max​(java.util.Comparator<? super T> comparator)` |
    `java.util.Optional<T>` | `min​(java.util.Comparator<? super T> comparator)` |
    `boolean` | `noneMatch​(java.util.function.Predicate<? super T> predicate)` |
    `java.util.stream.Stream<T>` | `onClose​(java.lang.Runnable closeHandler)` |
    `java.util.stream.Stream<T>` | `parallel()` |
    `XdmStream<T>` | `peek​(java.util.function.Consumer<? super T> action)` |
    `java.util.Optional<T>` | `reduce​(java.util.function.BinaryOperator<T> accumulator)` |
    `T` | `reduce​(T identity, java.util.function.BinaryOperator<T> accumulator)` |
    `<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()` |
    `XdmStream<T>` | `skip​(long n)` |
    `XdmStream<T>` | `sorted()` |
    `XdmStream<T>` | `sorted​(java.util.Comparator<? super T> comparator)` |
    `java.util.Spliterator<T>` | `spliterator()` |
    `XdmStream<T>` | `subStream​(int start, int end)` | Return the items at a given range of positions in the stream.
    `java.lang.Object[]` | `toArray()` |
    `<A> A[]` | `toArray​(java.util.function.IntFunction<A[]> generator)` |
    `java.util.stream.Stream<T>` | `unordered()` |
    `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
      Specified by:
        `filter` in interface `java.util.stream.Stream<T extends XdmItem>`
      Parameters:
        `predicate` - the supplied condition
      Returns:
        the filtered stream

    - #### map

          public <R> java.util.stream.Stream<R> map​(java.util.function.Function<? super T,​? extends R> mapper)

      Specified by:
        `map` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### mapToInt

          public java.util.stream.IntStream mapToInt​(java.util.function.ToIntFunction<? super T> mapper)

      Specified by:
        `mapToInt` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### mapToLong

          public java.util.stream.LongStream mapToLong​(java.util.function.ToLongFunction<? super T> mapper)

      Specified by:
        `mapToLong` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### mapToDouble

          public java.util.stream.DoubleStream mapToDouble​(java.util.function.ToDoubleFunction<? super T> mapper)

      Specified by:
        `mapToDouble` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### flatMap

          public <R> java.util.stream.Stream<R> flatMap​(java.util.function.Function<? super T,​? extends java.util.stream.Stream<? extends R>> mapper)

      Specified by:
        `flatMap` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### flatMapToXdm

          public <U extends XdmItem> XdmStream<U> flatMapToXdm​(Step<U> mapper)

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

    - #### flatMapToInt

          public java.util.stream.IntStream flatMapToInt​(java.util.function.Function<? super T,​? extends java.util.stream.IntStream> mapper)

      Specified by:
        `flatMapToInt` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### flatMapToLong

          public java.util.stream.LongStream flatMapToLong​(java.util.function.Function<? super T,​? extends java.util.stream.LongStream> mapper)

      Specified by:
        `flatMapToLong` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### flatMapToDouble

          public java.util.stream.DoubleStream flatMapToDouble​(java.util.function.Function<? super T,​? extends java.util.stream.DoubleStream> mapper)

      Specified by:
        `flatMapToDouble` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### distinct

          public XdmStream<T> distinct()

      Specified by:
        `distinct` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### sorted

          public XdmStream<T> sorted()

      Specified by:
        `sorted` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### sorted

          public XdmStream<T> sorted​(java.util.Comparator<? super T> comparator)

      Specified by:
        `sorted` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### peek

          public XdmStream<T> peek​(java.util.function.Consumer<? super T> action)

      Specified by:
        `peek` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### limit

          public XdmStream<T> limit​(long maxSize)

      Specified by:
        `limit` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### skip

          public XdmStream<T> skip​(long n)

      Specified by:
        `skip` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### forEach

          public void forEach​(java.util.function.Consumer<? super T> action)

      Specified by:
        `forEach` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### forEachOrdered

          public void forEachOrdered​(java.util.function.Consumer<? super T> action)

      Specified by:
        `forEachOrdered` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### toArray

          public java.lang.Object[] toArray()

      Specified by:
        `toArray` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### toArray

          public <A> A[] toArray​(java.util.function.IntFunction<A[]> generator)

      Specified by:
        `toArray` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### reduce

          public T reduce​(T identity,
                          java.util.function.BinaryOperator<T> accumulator)

      Specified by:
        `reduce` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### reduce

          public java.util.Optional<T> reduce​(java.util.function.BinaryOperator<T> accumulator)

      Specified by:
        `reduce` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### 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)

      Specified by:
        `min` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### max

          public java.util.Optional<T> max​(java.util.Comparator<? super T> comparator)

      Specified by:
        `max` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### count

          public long count()

      Specified by:
        `count` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### anyMatch

          public boolean anyMatch​(java.util.function.Predicate<? super T> predicate)

      Specified by:
        `anyMatch` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### allMatch

          public boolean allMatch​(java.util.function.Predicate<? super T> predicate)

      Specified by:
        `allMatch` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### noneMatch

          public boolean noneMatch​(java.util.function.Predicate<? super T> predicate)

      Specified by:
        `noneMatch` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### findFirst

          public java.util.Optional<T> findFirst()

      Specified by:
        `findFirst` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### findAny

          public java.util.Optional<T> findAny()

      Specified by:
        `findAny` in interface `java.util.stream.Stream<T extends XdmItem>`

    - #### iterator

          public java.util.Iterator<T> iterator()

      Specified by:
        `iterator` in interface `java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>`

    - #### spliterator

          public java.util.Spliterator<T> spliterator()

      Specified by:
        `spliterator` in interface `java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>`

    - #### isParallel

          public boolean isParallel()

      Specified by:
        `isParallel` in interface `java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>`

    - #### sequential

          public java.util.stream.Stream<T> sequential()

      Specified by:
        `sequential` in interface `java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>`

    - #### parallel

          public java.util.stream.Stream<T> parallel()

      Specified by:
        `parallel` in interface `java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>`

    - #### unordered

          public java.util.stream.Stream<T> unordered()

      Specified by:
        `unordered` in interface `java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>`

    - #### onClose

          public java.util.stream.Stream<T> onClose​(java.lang.Runnable closeHandler)

      Specified by:
        `onClose` in interface `java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>`

    - #### close

          public void close()

      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 result 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 result of the stream as a `List<XdmItem>`. This is a terminal operation.
      Returns:
        the contents of the stream, as a `List<XdmItem>`.

    - #### asListOfNodes

          public java.util.List<XdmNode> asListOfNodes()

      Return the result of the stream as a `List<XdmNode>`. This is a terminal operation.
      Returns:
        the list of nodes delivered by the stream
      Throws:
        `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()`

    - #### exists

          public boolean exists()

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

    - #### last

          public XdmStream<T> last()

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

    - #### at

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