net.sf.saxon.s9api

## Class XdmValue

- java.lang.Object
- - net.sf.saxon.s9api.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 Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `XdmValue()`
    `` | `XdmValue(Iterable<XdmItem> items)` Create an XdmValue as a sequence of XdmItem objects
    `protected` | `XdmValue(Sequence value)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `XdmValue` | `append(XdmValue otherValue)` Create a new XdmValue by concatenating the contents of this XdmValue and another XdmValue.
    `Sequence` | `getUnderlyingValue()` Get the underlying implementation object representing the value.
    `XdmItem` | `itemAt(int n)` Get the n'th item in the value, counting from zero.
    `XdmSequenceIterator` | `iterator()` Get an iterator over the items in this value.
    `protected void` | `setValue(Sequence value)`
    `int` | `size()` Get the number of items in the sequence
    `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, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### XdmValue

          protected XdmValue()

    - #### XdmValue

          public XdmValue(Iterable<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

          protected XdmValue(Sequence value)

  - ### Method Detail

    - #### setValue

          protected void setValue(Sequence 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 function item (including map items), 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. 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
      Throws:
        `SaxonApiUncheckedException` - if the value is lazily evaluated and the delayed evaluation fails with a dynamic error.

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

    - #### iterator

          public XdmSequenceIterator iterator()
                                       throws SaxonApiUncheckedException

      Get an iterator over the items in this value.
      Specified by:
        `iterator` in interface `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 Sequence 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

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.