Package net.sf.saxon.s9api

## Class XdmValue

- java.lang.Object
- - net.sf.saxon.s9api.XdmValue

- All Implemented Interfaces:
    `java.lang.Iterable<XdmItem>`
  Direct Known Subclasses:
    `XdmEmptySequence`, `XdmItem`

      public class XdmValue
      extends java.lang.Object
      implements java.lang.Iterable<XdmItem>

  A value in the XDM data model. A value is a sequence of zero or more items, each item being an atomic value, a node, or a function item.

  An XdmValue is immutable.

  A sequence consisting of a single item may be represented as an instance of `XdmItem`, which is a subtype of XdmValue. However, there is no guarantee that a sequence of length one will always be an instance of XdmItem.

  Similarly, a zero-length sequence may be represented as an instance of `XdmEmptySequence`, but there is no guarantee that every sequence of length zero will always be an instance of XdmEmptySequence.

  Since:
    9.0

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `XdmValue()` |
    `` | `XdmValue​(java.lang.Iterable<? extends XdmItem> items)` | Create an XdmValue as a sequence of XdmItem objects
    `` | `XdmValue​(java.util.Iterator<? extends XdmItem> iterator)` | Create an XdmValue containing the items returned by an `Iterator`.
    `` | `XdmValue​(java.util.stream.Stream<? extends XdmItem> stream)` | Create an XdmValue containing the results of reading a Stream

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `XdmValue` | `append​(XdmValue otherValue)` | Create a new XdmValue by concatenating the contents of this XdmValue and another XdmValue into a single sequence.
    `XdmValue` | `documentOrder()` | Return a new XdmValue containing the nodes present in this XdmValue, with duplicates eliminated, and sorted into document order
    `protected static XdmValue` | `fromGroundedValue​(GroundedValue value)` |
    `GroundedValue` | `getUnderlyingValue()` | Get the underlying implementation object representing the value.
    `boolean` | `isEmpty()` | Ask whether the sequence is empty
    `XdmItem` | `itemAt​(int n)` | Get the n'th item in the value, counting from zero.
    `XdmSequenceIterator<XdmItem>` | `iterator()` | Get an iterator over the items in this value.
    `static XdmValue` | `makeSequence​(java.lang.Iterable<?> list)` | Make an XDM sequence from a Java `Iterable`.
    `static XdmValue` | `makeValue​(java.lang.Object o)` | Make an XDM value from a Java object.
    `<T extends XdmItem> XdmStream<T>` | `select​(Step<T> step)` | Get a stream of items by applying a `Step` to the items in this value.
    `protected void` | `setValue​(GroundedValue value)` |
    `int` | `size()` | Get the number of items in the sequence
    `XdmStream<? extends XdmItem>` | `stream()` | Get a stream comprising the items in this value
    `java.lang.String` | `toString()` | Create a string representation of the value.
    `static XdmValue` | `wrap​(AtomicSequence value)` |
    `static XdmValue` | `wrap​(Sequence value)` | Create an XdmValue that wraps an existing Saxon Sequence

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Constructor Detail

    - #### XdmValue

          protected XdmValue()

    - #### XdmValue

          public XdmValue​(java.lang.Iterable<? extends XdmItem> items)

      Create an XdmValue as a sequence of XdmItem objects
      Parameters:
        `items` - a sequence of XdmItem objects. Note that if this is supplied as a list or similar collection, subsequent changes to the list/collection will have no effect on the XdmValue.
      Since:
        9.0.0.4

    - #### XdmValue

          public XdmValue​(java.util.Iterator<? extends XdmItem> iterator)
                   throws SaxonApiException

      Create an XdmValue containing the items returned by an `Iterator`.
      Parameters:
        `iterator` - the iterator that supplies the values
      Throws:
        `SaxonApiException` - if an error occurs reading values from the supplied iterator
      Since:
        9.6. Extended in 9.9 to take any Iterator, not just an `XdmSequenceIterator`.

    - #### XdmValue

          public XdmValue​(java.util.stream.Stream<? extends XdmItem> stream)
                   throws SaxonApiException

      Create an XdmValue containing the results of reading a Stream
      Parameters:
        `stream` - the stream to be read
      Throws:
        `SaxonApiException`

  - ### Method Detail

    - #### fromGroundedValue

          protected static XdmValue fromGroundedValue​(GroundedValue value)

    - #### setValue

          protected void setValue​(GroundedValue value)

    - #### wrap

          public static XdmValue wrap​(Sequence value)

      Create an XdmValue that wraps an existing Saxon Sequence
      Parameters:
        `value` - the supplied Sequence (which may be a singleton Item),
      Returns:
        an XdmValue corresponding to the supplied Sequence. If the supplied value is null, an empty sequence is returned. If the supplied value is an atomic value, the result will be an instance of XdmAtomicValue.
        - If the supplied value is a node, the result will be an instance of XdmNode.
        - If the supplied value is a map, the result will be an instance of XdmMap.
        - If the supplied value is an array, the result will be an instance of XdmArray.
        - If the supplied value is a function item, the result will be an instance of XdmFunctionItem.
      Throws:
        `SaxonApiUncheckedException` - if the supplied Sequence is not yet fully evaluated, and evaluation of the underlying expression fails with a dynamic error.
      Since:
        9.5 (previously a protected method)

    - #### wrap

          public static XdmValue wrap​(AtomicSequence value)

    - #### append

          public XdmValue append​(XdmValue otherValue)

      Create a new XdmValue by concatenating the contents of this XdmValue and another XdmValue into a single sequence. The two input XdmValue objects are unaffected by this operation.

      Note: creating a sequence of N values by successive calls on this method takes time proportional to N-squared.

      Parameters:
        `otherValue` - the value to be appended
      Returns:
        a new XdmValue containing the concatenation of the two input XdmValue objects
      Since:
        9.2

    - #### size

          public int size()

      Get the number of items in the sequence
      Returns:
        the number of items in the value, considered as a sequence. Note that for arrays and maps, the answer will be 1 (one) since arrays and maps are items.

    - #### isEmpty

          public boolean isEmpty()

      Ask whether the sequence is empty
      Returns:
        true if the value is an empty sequence
      Since:
        10.1

    - #### itemAt

          public XdmItem itemAt​(int n)
                         throws java.lang.IndexOutOfBoundsException,
                                SaxonApiUncheckedException

      Get the n'th item in the value, counting from zero.
      Parameters:
        `n` - the item that is required, counting the first item in the sequence as item zero
      Returns:
        the n'th item in the sequence making up the value, counting from zero
      Throws:
        `java.lang.IndexOutOfBoundsException` - if n is less than zero or greater than or equal to the number of items in the value
        `SaxonApiUncheckedException` - if the value is lazily evaluated and the delayed evaluation fails with a dynamic error.

    - #### iterator

          public XdmSequenceIterator<XdmItem> iterator()
                                                throws SaxonApiUncheckedException

      Get an iterator over the items in this value.
      Specified by:
        `iterator` in interface `java.lang.Iterable<XdmItem>`
      Returns:
        an Iterator over the items in this value.
      Throws:
        `SaxonApiUncheckedException` - if the value is lazily evaluated and the delayed evaluation fails with a dynamic error.

    - #### getUnderlyingValue

          public GroundedValue getUnderlyingValue()

      Get the underlying implementation object representing the value. This method allows access to lower-level Saxon functionality, including classes and methods that offer no guarantee of stability across releases.
      Returns:
        the underlying implementation object representing the value

    - #### toString

          public java.lang.String toString()

      Create a string representation of the value. The is the result of serializing the value using the adaptive serialization method.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the value

    - #### makeSequence

          public static XdmValue makeSequence​(java.lang.Iterable<?> list)
                                       throws java.lang.IllegalArgumentException

      Make an XDM sequence from a Java `Iterable`. Each value delivered by the iterable is first converted to an XDM value using the `makeValue(Object)` method; if the result is anything other than a single XDM item, it is then wrapped in an `XdmArray`.
      Returns:
        the result of the conversion if successful
      Throws:
        `java.lang.IllegalArgumentException` - if conversion is not possible

    - #### makeValue

          public static XdmValue makeValue​(java.lang.Object o)
                                    throws java.lang.IllegalArgumentException

      Make an XDM value from a Java object. The supplied object may be any of the following:
      - An instance of `XdmValue` (for example, an `XdmNode` or `XdmAtomicValue` or `XdmArray` or `XdmMap`), which is returned unchanged
      - An instance of `Sequence` (for example, a `NodeInfo` or `AtomicValue`), which is wrapped as an `XdmValue`
      - An instance of `Map`, which is converted to an XDM Map using the `XdmMap.makeMap(java.util.Map)` method
      - A Java array, of any type, which is converted to an XDM Array using the `XdmArray.makeArray(java.lang.Object[])` method
      - A Java collection, more specifically `Iterable`, which is converted to an XDM sequence using the `makeSequence(Iterable)` method
      - Any object that is convertible to an XDM atomic value using the method `XdmAtomicValue.makeAtomicValue(Object)`
      Returns:
        the result of the conversion if successful
      Throws:
        `java.lang.IllegalArgumentException` - if conversion is not possible

    - #### documentOrder

          public XdmValue documentOrder()
                                 throws SaxonApiException

      Return a new XdmValue containing the nodes present in this XdmValue, with duplicates eliminated, and sorted into document order
      Returns:
        the same nodes, sorted into document order, with duplicates eliminated
      Throws:
        `SaxonApiException` - if anything goes wrong (typically during delayed evaluation of the input sequence)
        `java.lang.ClassCastException` - if the sequence contains items that are not nodes
      Since:
        9.9

    - #### stream

          public XdmStream<? extends XdmItem> stream()

      Get a stream comprising the items in this value
      Returns:
        a Stream over the items in this value
      Since:
        9.9

    - #### select

          public <T extends XdmItem> XdmStream<T> select​(Step<T> step)

      Get a stream of items by applying a `Step` to the items in this value. This operation is analogous to the `Stream.flatMap` operation in Java, or to the "!" operator in XPath.
      Parameters:
        `step` - the Step to be applied to the items in this value
      Returns:
        a Stream of items obtained by replacing each item X in this value by the items obtained by applying the Step function to X.
      Since:
        9.9