Package net.sf.saxon.s9api

Class XdmValue

  • All Implemented Interfaces:
    Iterable<XdmItem>
    Direct Known Subclasses:
    XdmEmptySequence, XdmItem
    public class XdmValue
extends Object
implements Iterable<XdmItem>
    An value in the XDM data model. A value is a sequence of zero or more items, each item being either an atomic value or a node.

    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 Detail

      • XdmValue

        protected XdmValue()

      • XdmValue

        public XdmValue​(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​(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.

    • Method Detail

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

      • 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 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:
        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.

      • 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 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 Object
        Returns:
        a string representation of the value

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